Friday, March 7, 2014

Creating a Google Spreadsheet Restaurant Map for Shenyang

Recently, starting with a gpx file from a member of the Shenyang Expats Facebook group, I decided to create a Map of Restaurants in Shenyang using a Google Spreadsheet as the database.

If you are interested in this project from an expat's point of view, the following three links should be interesting to you:

If you are interested in this project from a developer's point of view, read on...

Here is an example of the map as rendered in an Iframe:

Here are some initial thoughts about the project as things start to get rolling.

How can we have an easy way to get the latitude / longitude of a restaurant:
  • when someone is at the restaurant (within the form? within the browser?)
  • when an app administrator is at home editing an entry that was submitted via a form.
Where will this web page be hosted (on the Embrace Shenyang blog? As a showcase project at Open Source Broadcasting (this blog) or at or elsewhere)?

Should the versioning and rendering all be done at google code? To download the current codebase, visit:

  • The map needs to use Sheynang city center as its central point on loading.
  • The map needs to center on a point when it's clicked from the right hand index.
  • The map script needs to be changed to display the address field.
  • We will need to figure out how to show only restaurants that do take-out or restaurants that only deliver... or should users be directed directly to the spreadsheet to make these kinds of queries for now?
  • How can this map be made useful to show "restaurants that are near you" when you open it in a browser on your mobile phone?
Other thoughts? Submit a comment below...

Wednesday, April 25, 2012

Buttering Popcorn.js with Templates

When I first stared looking into popcorn.js it seemed like it was all popcorn.  It happened that, at the time, there was a tool called the butter app (which has been updated and renamed to Popcorn Maker) but, in my mind, it was still all this one magical javascript library.  However, as I get more familiar with the project, it seems there are multiple facets to using this tool, so much so that I feel like I need to clarify for myself (and hopefully for the benefit of others) exactly what we are talking about when we say we want to create a presentation using popcorn.js.

Getting our Bearings

There are numerous parts to popcorn, and depending on what you want to do, different parts will be more important to you than others.


Two good places to get started with popcorn is and where you will find the following definition:
Popcorn.js is an event system for HTML5 media developers. Think jQuery for video. You can leave the heavy lifting to Popcorn, and concentrate on what you do best: writing awesome code.
I think of popcorn.js as a "timing engine", a script that synchronizes a piece of audio and video to any number of discreet and disparate events.  Just as watching a movie happens over the course of a limited, uninterrupted period of time and just as popcorn is consumed incrementally in little bits of popped kernels at various intervals over the course of that movie, so too does popcorn.js allow a person to incrementally trigger many "little bits" of popped kernels, of events (whether they are text, tweets, maps etc.) at any particular time during the timeline of watching that movie.  For me, this is a great metaphor for describing the overall project and a metaphor which helps me personally to understand the way the different parts of the project fit together.

A person who is interested in contributing to popcorn.js likely will want to customize the way a audio or video file displays in the browser or enable some event to happen that is not covered by existing plugins (such as footnotes, tweets, images, web pages, google maps and more...).  This person is likely to have a good degree of experience with JavaScript and knowledge of APIs and the browser's DOM.

How to get involved with popcorn.js

Ben Moskowitz, the Media Program Lead at the Mozilla Foundation, in his excellent blog post Mozilla Pocorn: How to Get Involved cites these ways where you can start getting involved with popcorn.js:
When paired with specific Popcorn templates, custom plugins can offer sophisticated authoring capabilities to end-users.


Popcorn Maker

If you are more of an author, a story teller, someone who wants to create an interesting presentation using popcorn but don't want to get into the code unless you have to, Popcorn Maker is a great tool that Mozilla is currently developing.  If you would like to try out the tool in it's early stages, click on the "Try the alpha" button an it will take you here.


If you are an organization or team of content producers who has very specific needs which would necessitate you building your own version of Popcorn Maker and if you or people on your team have a good degree of experience with 
JavaScript and knowledge of APIs and the browser's DOM, then then getting familiar with butter is for you.

Once again, I'll cite Ben Moskowitz' blog post on How to Get Involved with Mozilla Popcorn.  Here, Ben provides a great description of Butter as well as a list of ways you can start getting involved :

Butter is a software development kit to create HTML5 web apps that time user inputs with media. It's the foundation on which Popcorn Maker is built.
Butter manages track data, saved projects, saved media, user interface construction, publishing, and more.
You are welcome to file a bug report, a feature request, or—even better—to contribute to the project!
To contribute to Butter, join us at our Lighthouse issue tracker. Have a look at the open tickets and feel free to take one. When you're done with a ticket, issue a pull request to the main repository on GitHub.


Making a template???

When I first started creating presentations using popcorn, I found it easy to work off existing templates... er I should say "demos" included in the documentation or in popcorn plugin folders.  Like this one, for instance, or this one upon which I based a recent presentation (thanks folks! amazing work).

For me, these demos functioned as templates and allowed me to get up and running quickly doing what I needed to do.

However, in order to clearly define some next steps for how I'd like to continue participating with popcorn.js, I needed to realize that I need to start thinking beyond the plugin demos that I had found so useful, and that if I want to contribute in a way that will be useful to other media creators using popcorn is to start thinking about creating Templates for Butter.

Templates for Butter.  Plugins for Popcorn.  Okay, I can get that.

Without discounting the initial two thirds, this point was driven home nicely at about 23 minutes into this recent presentation by Ben Mozkowitz and Bobby Richter where Ben exhorts developers to:

Make a template!  The really cool thing about Popcorn Maker is that we are going to be some providing starter templates. But this thing isn't going to take off until we have a community of tens or hundreds or even thousands of people writing templates in the same way that you have tens or hundreds or even thousands of people writing WordPress themes.
What a great goal!  And one that I think is not too unrealistic actually.

My next step is to find out how I can begin contributing Butter templates.  I was a little confused as to what a butter template would look like and where exactly are the sample files upon which I would base my work.

Shortly after, in the presentation, Ben briefly describes that:
So, to do this is actually really easy. This is probably the easiest way to get involved aside from testing the app. Making a template, again, is just using regular web technologies like HTML, CSS and JavaScript,  layout the template to look like you want, add any functionality that you think you might need, and then to make it work INSIDE of butter, inside popcorn maker,  you simply use these declarative attributes like data-butter = "media" so every popcorn template needs one piece of media which is going to be the kind of baseline... And it doesn't need the same piece of media, it's just where will this media be on the page...
So if it's just a regular template with a video and then a box for extra context, that div, where you want the video to be is data-butter = "media" and in the interface the user can add their own video to that div.
Target. Anything on the page that's targetable by Butter any div on the page where you want a map to come in , or some flickr to come in, or you want to have anything happen, you simply give it a data-butter = "target"
If there is stuff that you don't want to appear in the finished export use data-butter = "exclude"
If there are things that you don't want to appear in the interface use data-butter = "invisible"
That is basically it.  So, if you want to create a template for Popcorn Maker, you write it using using regular HTML, CSS and JavaScript, you give it some declarative attributes and that's like 90% of the job right there....
So now, My job was to look around and find a template that made use of these declarative attributes.  I'm not sure if this is where people are intending that we look for templates, but after looking here:

I found this one template that interests me in particular:

And indeed, I found these declarative attributes that Ben had mentioned.

Also, as a test, I decided to see the difference between a Butter template, and the exported presentation:

So, this gets me started in thinking about where to begin, where things will end up once the presentation gets exported out of popcorn maker.

Also, it looks like here is where I will find the documentation for all of those declarations that I will need in order to use my template inside Butter:

Well, I certainly have my work cut out for me.  For the next month I'll be adapting one of my existing presentations... (er, one of my presentations that I had originally based off of the hard work of the bright and brilliant folks who created popcorn and popcorn plugins) for use in Butter.

Wish me luck.  I hope to write back and let you all know how it went.

Monday, March 5, 2012

Taking Popcorn.js for a Promenade in Paris

I am not a jounalist, but I play one on the web

Recently, I packed up my wife's trusty Marantz audio recorder, a set of headphones, a microphone and a camera and hopped on the metro. I literally had no idea what story I was setting out to tell, but I was confident that something would present itself... or that I would at least learn something. I did have a few general ideas in mind:

  • I was inspired by a story that I heard on 99% invisible about the Feltron Annual Report where Nicholas Felton is quoted as saying something like how your life (or memory) isn't measured by the the big trips or events, but it's measured instead by the little things that you do repeatedly each day.
  • I specifically wanted to emulate the great work from the New York Times' One in 8 Million series.
  • I wanted to keep in mind Ira Glass' description of the anecdote, a series of events, to craft a story in its purest form: "This happened, and that led to this next thing, and that led to this next thing... How it has a momentum in and of itself."
Here is the result of my work, an interview with musician Bernard Constant:

Things I learned

  • Bring two sets of batteries
  • Since I was running low on batteries, just before I walked close enough to almost hear Bernard playing under the bridge, I opted not to record the sound of water hitting the boats... and I didn't take a good picture of the boats so I had to use one that I took last spring. Pausing to get that sound and take that picture likely would have added an extra degree of polish.
  • Get further away when recording music.
  • I should have read the section on interviewing in the Radio Diaries Teen Reporter Handbook. In particular, the paragraph on "Let people talk in full sentences." Had I done that, I could have kept myself, as narrator, out of the story. Then, this truly would have been more true to the format used in the NYT's One in 8 Million series.
  • Next time, I'm going to make sure that all my images have the same orientation and dimensions.
  • Next time, bring a tripod: Get a photo of yourself on location.
  • If the story leads you to a particular destination, get photos of every landmark along the way, in the direction you'll be walking when telling the story.
One interesting thing that this exercise impressed upon me was this: you hear a lot about journo-coders, about journalists who have learned to code and integrate coding in the service of a story; however it may be equally useful for journalism organizations to conduct "journalism bootcamps" for developers and programmers and to look for surprising, innovative and untold stories coming from this direction as well.

Goals for the One in 8 Million Popcorn.js Template

In addition to the journalism angle I had some technical goals for this project as well:

  • Be focused. Set out to do only a narrow set of tasks and to do them well.
  • Be embeddable.
  • Enable viewing the presentation in "Full Screen" mode.
  • Figure out how to get images to scale well in smaller posts such as facebook posts.
  • Separate content from the scripting... thinking of using a google spreadsheet and the Tabletop JavaScript library to generate the timeline for the subtitles and the images; separating content from presentation and scripts.
  • Allowing anyone the ability to modify the colors or theme of the page by way of variables in the url.
  • Styling the audio player. I've been going back and forth now about using the default soundcloud player and getting all the features that go with it, or being true to the original One in 8 Million app and having a minimal player.
  • Image hosting: Should there be a way to easily use Flickr or some other service for images? Perhaps it might be useful to write a script that could initially import a flickr set or tag to get urls and titles, attribution etc.
Updates to the template used for this presentation can be found on

Thank You