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..."
Digging into the source code of popcorn js
- I first downloaded the complete project as a zip file.
- I then unzipped this archive into a folder on my computer.
- Next I uploaded this to a directory on my web server.
- 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:
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
- 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).
- I skimmed the documentation and also found that there was a step-by step guide to Getting Started with Popcorn.js Plugins.
- 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).
<script src="popcorn.footnote.js"> to <script src="../footnote/popcorn.footnote.js"> <script src="popcorn.styler.js">
- 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.
- 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
- Remember to check out the Getting Started with Popcorn.js Plugins guide.
- 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
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!