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.

John Resig - JQuery - Watch the full process

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 .

7 comments:

cole said...

bravo! great explanation of how to get started with popcorn.js

brett said...

This is great, John! So how did our documentation stand up in your eyes? Where should we improve?

Would love to see you submit this plugin for peer review. It would certainly give you some great insight.

Regards,
Brett

rick said...

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.

John Tynan said...

Thanks everyone!

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 code
2) create your own plugin
3) make it change some stuff in the page

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

Thanks for the advice!

Xav said...

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

Phillip Smith said...

Great stuff, John. Really enjoyed this post, and really enjoyed your Popcorn-powered presentation during today's group pitch / feedback session. Bravo. :)

--Phillip.

John Tynan said...

Thanks, Phillip! So glad you liked this and my presentation from Monday. The feedback was most valuable. I wanted to mention, Rick, I just checked out your slide deck from

http://code.bocoup.com/popcorn.js/jqcon/#landing-slide

I especially like slides 15 + very helpful in gaining a bit of an understanding of how the framework has evolved, and how to get started extending this. Great stuff!