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.

Digging into the source code of popcorn js

1. I first downloaded the complete project as a zip file.
2. I then unzipped this archive into a folder on my computer.
3. Next I uploaded this to a directory on my web server.
4. I then made sure to edit the .htaccess file on my web server so that the mime-type are configured properly for html5 video

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:

pop.footnote({
start: 2,
end: 6,
text: "Pop!",
target: "footnotediv"
});

I also knew that the the properties target: "footnotediv" corresponded to a div with the id "footnotediv" within the body of the html page.

Getting ready to make your own plugin

1. I read the readme file and noted that I could get in touch with other popcorn developers by way of the mailing list or the IRC channel (irc://irc.mozilla.org/popcorn).
2. I skimmed the documentation and also found that there was a step-by step guide to Getting Started with Popcorn.js Plugins.
3. 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".
4. 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).
   
5. 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
   

   <script src="popcorn.footnote.js"> 
   to
   <script src="../footnote/popcorn.footnote.js">
   <script src="popcorn.styler.js">

6. I uploaded my "styler" directory to the web server under the popcorn-js/plugins folder and could test this by going to my web site at the url http://johntynan.com/scripts/popcorn-js/plugins/styler/popcorn.styler.html . Note the format of the path in the url. For your plugin, you should be going to a similar address.
7. This gives you a fully functioning page containing a working footnote demo that you could edit, build upon and test out your own ideas.

Making your own plugin

1. Remember to check out the Getting Started with Popcorn.js Plugins guide.
2. 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.
3. In your text-editor, set your "tab setting" to use two spaces instead of tabs.
4. 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).
5. 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.
6. Next, change the description and the author information to reflect the name of the plugin and to describe what the plugin will do.
7. 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

1. 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 )

2. Next, in the start function, change
   

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

   to read
   

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

3. 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 .