Sunday, July 24, 2011

Towards an understanding of popcorn.js

This past week, as part of the Knight-Mozilla Ideas Challenge learning lab, we heard from speakers Christian Heilmann, a "developer evangelist" at Mozilla, as well as John Resig, the lead developer of jQuery . Christian's presentation was dramatic in many ways for the way it exposed that working solely in the browser with native html5 technologies was possible and important to an open web. But Heilmann also served as a subtle introduction to John Resig's presentation in that he impressed upon the group the importance of understanding how the code you are working with works:

Don't practice pixie magic... If you use someone's code, make sure you understand it... Don't just take it

As a bookend to this idea, John Resig's presentation showed how deliberate and thorough one needs to be to treat "every user [of your project] as a potential, future, contributor" and to lead them towards that goal.

Resig stressed that you should assume your users have little in the way of background knowledge and to make your documentation as explicit as possible. e.g. "Open text editor..."

With this in mind, I have decided to take a closer look at Popcorn.js, an amazing JavaScript library that allows you to create multimedia presentations in the browser using html5. (See these demos for some inspiring examples). Previously, I had created a presentation with popcorn.js using the authoring tool at butterapp.org, but I wanted to follow Heilmann's advice to not rely on "pixie magic" and to gain a better understanding for how the underlying code worked. I also wanted to use this as an opportunity to see how explicit the documentation for popcorn.js was, especially when held up to Resig's rigorous standards, and to write this blog post which could possibly serve as an aide to other users, like myself, who are approaching popcorn.js for the first time.

I was familiar with how to make minor modifications to the source code based on my experience with what I had created at butterapp.org. I knew the format of the page looked something like this (as described in the documentation Popcorn 101):

I knew that the page contained "popcorn commands" which could be as simple as "pop.play()" or could be configured like this:

I read the plugin guide and it kind of made sense, but I'm more experiential, so I went into the plugins folder and made a copy of the "footnote" folder and renamed it to my plugin, which I called "styler".

I then renamed the four files within the styler directory from popcorn.footnote.html to popcorn.styler.html (same for popcorn.footnote.js and so on).

Since the JavaScript and html pages resided in a different directory than the footnote directory, I had to adjust the path the JavaScript file in popcorn.styler.html from

Making your own plugin

If you plan to contribute your plugin back into the popcorn.js community, you may want to be familiar with the recommended workflow. It will probably also be helpful to read through the popcorn.js styleguide.

In your text-editor, set your "tab setting" to use two spaces instead of tabs.

Next, I edited my popcorn.styler.js renaming all instances of "footnote" to "styler" (making sure to use the match case parameter and to perform this same search and replace for all instances of the uppercase Footnote as well).

Note the sections of both the popcorn.styler.html page and the popcorn.styler.js script. In particular, note how the popcorn.styler.js script has a five main sections: the description, the manifest, the setup and the start and the end.

Next, change the description and the author information to reflect the name of the plugin and to describe what the plugin will do.

You'll also want to change the example and the manifest to match the parameters that you'll be placing in the popcorn.styler.html page for example:

Making your plugin change some things on the page

Rather than create a div on the page (as the footnote plugin does), let's let popcorn select the target object that we would like to change by changing the options._container variable from

options._container = document.createElement( 'div' )

to instead read

options._container = document.getElementById( options.target )

Next, in the start function, change

options._container.style.display = "inline";

to read

options._container.style.color = options.color;

Lastly, make the following change to the popcorn.styler.html file

Viola! There it is:
You should have a video that plays, some text that displays on the page 5 seconds into the video, and then this text should change color 10 seconds into the video!

Next steps

If you're like me, you should be asking yourself, what else can I do on the page? Is this really just javascript? Can I change things by way of CSS or the DOM? And what about popcorn.js? How does this popcorn.js file work? To what extent does this one file hold together the entire framework and what exactly does this file do? Which functions that I used in my HTML or my JavaScript file actually reside in popcorn.js? And what more can I do with this file and with this framework? Do they have an API... why yes they do. The work is just beginning. And while this exercise has dispelled some of the "pixie dust" I have a feeling that there is quite a bit of pixie dust left in store for developers wanting to explore what can be done with popcorn.js .

This really tremendous! Feel free to join us in the #popcorn channel on irc.mozilla.org - there is almost always someone there that is willing to help answer questions that you might have about the framework. Additionally, this is the place to be to get first hand experience or even to contribute to the project.

Rick, I already signed in twice to the IRC channel and people were most helpful. That's where I was advised about updating the .htaccess file (sorry I forgot to include attribution).

Brett, I'm going to reserve my comment on your question for a bit, as I'm new to the community and have a bit more learning to do. But, by the way of transferring what's familiar to me from one project to the next, the folks at web2py have a "welcome app" that they frequently update, and that people often use as a template for creating new apps. Perhaps popcorn would benefit from the same.

I'm looking forward to submitting a plugin for peer review. I don't know if this is the plugin here, but there should be one in the near future.

Cole, So glad you like the post.

You may have noticed, during our chat the other night you advised me to do the following:

1) dig into the source code2) create your own plugin3) make it change some stuff in the page

I started my blog post with these bullet points as working headings for this post :)

I tried to use popcorn.js a couple of months ago to add some interactivity to a page containing an html5 audio element. At the time I found the documentation woefully lacking while Butter was geared to video rather than audio and was too inflexible in page layout for what I had in mind.

In the end I rolled my own code. It has nowhere near the features of popcorn, but all I wanted to do was set/clear a CSS class on different elements in sync with the audio.

When a developer chooses to roll their own code because it will be a lot faster than working out how to do something relatively simple with your library, there's a definite need for better docs ;)

I'll continue to keep an eye on popcorn for future projects, and a lot of the problems I faced are already being addressed (e.g. with Popcorn Maker).