Popcorn.destroy( instance )
Purpose
Stops the instance’s timeUpdate loop and removes any associated events.
Options
- instance [Object] - a reference to the instance you wish to destroy;
Use Case
Your web application needs to create a new instance of Popcorn, using the same video source as the first.
Examples
Destroying a popcorn instance
// Create the instance
var pop = Popcorn( "video" );
// Add event
pop.exec( 5, function() { console.log( "exec" ); } );
// Destroy instance
Popcorn.destroy( pop );
Popcorn.extend( target, source [, … ] )
Purpose
Merge the contents of two or more objects onto the first object.
This provides developers an easy means to copy one or more objects into another.
returns our extended object
Options
- target [String] - the destination object
- obj1 [Object] - the first source object
- objectN [Object] - optional arbitrary number of further objects to be copied from
Use Case
Need to copy an object
Examples
Popcorn.forEach( [ object|array ], callback, context )
Purpose
Iterates over either an object or an array, passing each item or property to callback( value, key ). If a context parameter is provided, it will be used as the this value of callback. If it is not provided, the current context is used instead.
Options
-
| item [Object |
Array] - the item to be parsed |
- callback [Function] - a callback function with the following parameters:
-
| value [String |
Number] - the value of the current object that is keyed by key |
-
| key [String |
Number] - the position in the object or value where the value is stored |
-
| item [Object |
Function] - our original object or array |
Example
Live demo showing how to iterate over each item in an object and console.log its key and value
Popcorn.getJSONP( url, successCallback )
Purpose
Request remote JSONP data
Options
- url [String] - a string of the name of the script to be loaded
- callback=jsonp ( or similar ) [Function] - params are required to use with any JSONP service
- successCallback [Function] - a function to be run when the script has been successfully loaded
Examples
An example showing how to get JSON data from a local json file using Popcorn.xhr
1 Popcorn.xhr({
2
3 url: "jsonp.json?callback=jsonp",
4 dataType: "jsonp",
5 success: function( data ) {
6 /*
7 `data` will be the parsed json object
8
9 */
10 }
11 });
An example showing how to get JSON data from a local json file using Popcorn.getJSONP
1 Popcorn.getJSONP(
2
3 "jsonp.json?callback=jsonp",
4 function( data ) {
5 /*
6 `data` will be the parsed json object
7
8 */
9 }
10 );
An example showing how to get JSON data from a remote site using Popcorn.xhr
1 Popcorn.xhr({
2
3 url: "http://domain.com/service/?callback=jsonp",
4 dataType: "jsonp",
5 success: function( data ) {
6 /*
7 `data` will be the parsed json object
8
9 */
10 }
11 });
An example showing how to get JSON data from a remote site using Popcorn.JSONP
1 Popcorn.getJSONP(
2
3 "http://domain.com/service/?callback=jsonp",
4 function( data ) {
5 /*
6 `data` will be the parsed json object
7
8 */
9 }
10 );
Popcorn.getScript( url, successCallback )
Purpose
Request remote JavaScript resources.
Options
- url [String] - a string of the name of the script to be loaded
- successCallback [Function] - a function to be run when the script has been loaded
Use Case
Load an external script for a plugin ( take a look at many of the current Popcorn plugins )
Examples
An example showing how to get a remote script, no callback being used
1 // Load in Processing.js
2 Popcorn.getScript(
3 "http://processingjs.org/content/download/processing-js-1.0.0/processing-1.0.0.min.js"
4 );
An example how to get a local script using Popcorn.xhr with a callback function
1 Popcorn.xhr({
2
3 url: "local-script-resource.js",
4 dataType: "script",
5 success: function() {
6 /*
7 fired when script has loaded and is ready to use
8 */
9 }
10 });
An example of how to get a local script using Popcorn.getScript with a callback
1 Popcorn.getScript(
2
3 "local-script-resource.js",
4 function() {
5 /*
6 fired when script has loaded and is ready to use
7 */
8 }
9 );
An example of how to get a remote script using Popcorn.getScript with a callback
1 Popcorn.getScript(
2
3 "http://processingjs.org/content/download/processing-js-1.0.0/processing-1.0.0.min.js",
4 function() {
5 /*
6 fired when script has loaded and is ready to use
7 */
8 }
9 );
Popcorn.guid( [prefix] )
Purpose
Return a unique id with an optional prefix
Options
- prefix [String] - string representing the string that will prefix the guid that is returned. For example if prefix is “foo” the returned value would be foo1319565291420
Example
Live demo showing how to create a guid
Popcorn.Locale
Purpose
Provide language and region locale information
When a page loads, Popcorn will initialize a table of useful language and locale related values. The table can be updated with a call to Popcorn.locale.set(), eg. Popcorn.locale.set(“fr-CA”);. Calls to Popcorn.locale.set(); will result in the “locale:changed” event being fired on all currently existing Popcorn instances. This allows program code, plugins and players to listen for changes in the locale and react accordingly.
Options
- Popcorn.locale.get() [Function] - returns the current locale object
- Popcorn.locale.set( langRegion ) [Function]- set the locale, which is a string that takes the form of “lang-region” ex: “fr-CA”
- Event: “locale:changed” - an event fired when the locale changes
Examples
Popcorn.parser( parserName, fn, data )
Purpose
- Used to create a new Popcorn.js parser
Options
- parserName [String] - will be the name for your newly created parser. Will also be the name of the instance method in which your parser will be accessed through.
- fn [Function] - function that will get run in order to parse the data being passed in
- data [Object] - the passed in data to be parsed
Example
1 Popcorn.parser( "parseJSON", function( data ) {
2
3 // declare needed variables
4 var retObj = {
5 title: "",
6 remote: "",
7 data: []
8 },
9 manifestData = {},
10 dataObj = data;
11
12 Popcorn.forEach( dataObj.data, function ( obj, key ) {
13 retObj.data.push( obj );
14 });
15
16 return retObj;
17 });
18
19 var pop = Popcorn( "#video" );
20
21 pop.parseJSON( "data.json" );
Popcorn.plugin( pluginName, definitionObject, manifest )
Purpose
Creates a new Popcorn proto method of the name provided with the definitionObject.
All Popcorn instances will inherit this newly created method. See below for plugin authoring patterns; see the Step-by-step instructions for creating Popcorn Plugins for detailed plugin authoring information.
Options
- pluginName [String] - will be the name for your newly created plugin. Will also be the name of the instance method in which your plugin will be accessed through.
- definitionObject [Object] - an object in which the setup, start, end, teardown functions will be implemented for the given plugin
- manifest [Object] - an object that explains the given plugin. Any options that are passed on to the user are documented here. Manifest are read in by Popcorn-Maker in order to create a meaningful editor. A more in-depth explanation can be found here
Use Cases
Develop a plugin for a popular web service in order to extend additional content during a popcorn video
Example
Live demo showing how to create a basic plugin that simply does something on start and end
Popcorn.plugin.debug
Purpose
Popcorn.plugin.debug is a boolean flag that toggles error suppression on Popcorn plugin functions (start, end, etc.).
When it is set to false, errors are caught and stored inside Popcorn.plugin.errors, and an “error” event is triggered on the instance.
When set to true, errors will not be suppressed.
Options
- Popcorn.plugin.debug [Boolean] - Toggle debug mode on or off
Use Case
- During plugin development, debug mode may be turned on to have Popcorn suppress errors thrown inside of plugins.
- In production environments, debug mode should be set to false, allowing error handling to be performed by listening to the “error” event on the Popcorn instance.
Examples
1 // Turn on debug mode
2 Popcorn.plugin.debug = true;
3
4 // Create a plugin that will throw an error when it's start function runs
5 pop.plugin( "foo", {
6 start: function() {
7 throw new Error();
8 }
9 });
10
11 // Create Popcorn instance
12 var pop = Popcorn( "#video-element-id" );
13
14 // set up "foo" event
15 pop.foo({ start: 1 });
16
17 // The error will not be caught by Popcorn
18 pop.play();
1 // Debug mode is off by default
2
3 // Create a plugin that will throw an error when it's start function runs
4 Popcorn.plugin( "foo", {
5 start: function() {
6 throw new Error();
7 }
8 });
9
10 // Create Popcorn instance
11 var pop = Popcorn( "#video-element-id" );
12
13 // set up "foo" event
14 pop.foo({ start: 1 });
15
16 // The error will be caught by Popcorn.plugin.errors
17 pop.listen( "error", function( e ) {
18 // 'e' is Popcorn.plugin.errors, which can be accessed outside the "error" event callback.
19 console.log( e );
20 });
21
22 pop.play();
Popcorn.plugin.errors
Purpose
Popcorn.plugin.errors is an array object that contains errors thrown from plugins when Popcorn is not in debug mode.
Each error object in Popcorn.plugin.errors will look like:
{
plugin: pluginName,
thrown: originalErrorObject,
source: pluginFunction-toString
}
Options
- Popcorn.plugin.errors [Array Object] - Stores suppressed errors from plugins
Use Case
- Inspection of this object can help a developer solve problems with their Popcorn projects.
- The redirection of errors to Popcorn.plugin.errors makes sure that execution of the entire project continues even in the case of a single plugin failing during runtime.
Examples
1 // Debug mode is off by default
2
3 // Create a plugin that will throw an error when it's start function runs
4 Popcorn.plugin( "foo", {
5 start: function() {
6 throw new Error();
7 }
8 });
9
10 // Create Popcorn instance
11 var pop = Popcorn( "#video-element-id" );
12
13 // set up "foo" event
14 pop.foo({ start: 1 });
15
16 // The error will be caught by Popcorn.plugin.errors
17 pop.listen( "error", function( e ) {
18 // 'e' is Popcorn.plugin.errors, which can be accessed outside the "error" event callback.
19 console.log( e );
20 });
21
22 pop.play();
Popcorn( callback )
Purpose
An optional way to use Popcorn’s constructor. Instead of passing in an id as a parameter, a callback function is passed in that will be called when the DOM is ready.
Options
- callback [Function] - function. A function that will be called when the DOM is ready
Use Case
- Execute a block of code once the DOM has loaded
Examples
1 Popcorn(function() {
2
3 var popcorn = Popcorn( "#video" );
4 });
Live demo of the using Popcorn to call a callback function when the DOM is ready
Popcorn Constructor
Popcorn.util.toSeconds( smpte [, fps ] )
Purpose
Convert a SMPTE timestamp to time in seconds
returns a floating point number
Options
- smpte [String] - a string that contains a valid timestamp in the form of either HH:MM:SS.MMM or HH:MM:SS;FF. Hours and minutes are optional and will default to 0.
- fps - an optional number specifying the frames per second
Examples
Live demo showing how to convert from timestamp to time in seconds