Popcorn.js Documentation

Utility Methods

Utility methods provide various helper functions that may be useful to the user. Each of these utility methods are accesable through the Popcorn namespace and are not instance specific.

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
2
3
4
5
6
7
8
9
10
11

    Popcorn.xhr({

      url: "jsonp.json?callback=jsonp",
      dataType: "jsonp",
      success: function( data ) {
        /*
          `data` will be the parsed json object

        */
      }
    });

An example showing how to get JSON data from a local json file using Popcorn.getJSONP

1
2
3
4
5
6
7
8
9
10

    Popcorn.getJSONP(

      "jsonp.json?callback=jsonp",
      function( data ) {
        /*
          `data` will be the parsed json object

        */
      }
    );

An example showing how to get JSON data from a remote site using Popcorn.xhr

1
2
3
4
5
6
7
8
9
10
11

    Popcorn.xhr({

      url: "http://domain.com/service/?callback=jsonp",
      dataType: "jsonp",
      success: function( data ) {
        /*
          `data` will be the parsed json object

        */
      }
    });

An example showing how to get JSON data from a remote site using Popcorn.JSONP

1
2
3
4
5
6
7
8
9
10

    Popcorn.getJSONP(

      "http://domain.com/service/?callback=jsonp",
      function( data ) {
        /*
          `data` will be the parsed json object

        */
      }
    );

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
2
3
4

    //  Load in Processing.js
    Popcorn.getScript(
      "http://processingjs.org/content/download/processing-js-1.0.0/processing-1.0.0.min.js"
    );

An example how to get a local script using Popcorn.xhr with a callback function

1
2
3
4
5
6
7
8
9
10

    Popcorn.xhr({

      url: "local-script-resource.js",
      dataType: "script",
      success: function() {
        /*
          fired when script has loaded and is ready to use
        */
      }
    });

An example of how to get a local script using Popcorn.getScript with a callback

1
2
3
4
5
6
7
8
9

    Popcorn.getScript(

      "local-script-resource.js",
      function() {
        /*
          fired when script has loaded and is ready to use
        */
      }
    );

An example of how to get a remote script using Popcorn.getScript with a callback

1
2
3
4
5
6
7
8
9

    Popcorn.getScript(

      "http://processingjs.org/content/download/processing-js-1.0.0/processing-1.0.0.min.js",
      function() {
        /*
          fired when script has loaded and is ready to use
        */
      }
    );

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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

    Popcorn.parser( "parseJSON", function( data ) {

        // declare needed variables
        var retObj = {
              title: "",
              remote: "",
              data: []
            },
            manifestData = {},
            dataObj = data;

        Popcorn.forEach( dataObj.data, function ( obj, key ) {
          retObj.data.push( obj );
        });

        return retObj;
      });

    var pop = Popcorn( "#video" );

    pop.parseJSON( "data.json" );

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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

    // Turn on debug mode
    Popcorn.plugin.debug = true;

    // Create a plugin that will throw an error when it's start function runs
    pop.plugin( "foo", {
      start: function() {
        throw new Error();
      }
    });

    // Create Popcorn instance
    var pop = Popcorn( "#video-element-id" );

    // set up "foo" event
    pop.foo({ start: 1 });

    // The error will not be caught by Popcorn
    pop.play();

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

    // Debug mode is off by default

    // Create a plugin that will throw an error when it's start function runs
    Popcorn.plugin( "foo", {
      start: function() {
        throw new Error();
      }
    });

    // Create Popcorn instance
    var pop = Popcorn( "#video-element-id" );

    // set up "foo" event
    pop.foo({ start: 1 });

    // The error will be caught by Popcorn.plugin.errors
    pop.listen( "error", function( e ) {
      // 'e' is Popcorn.plugin.errors, which can be accessed outside the "error" event callback.
      console.log( e );
    });

    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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

    // Debug mode is off by default

    // Create a plugin that will throw an error when it's start function runs
    Popcorn.plugin( "foo", {
      start: function() {
        throw new Error();
      }
    });

    // Create Popcorn instance
    var pop = Popcorn( "#video-element-id" );

    // set up "foo" event
    pop.foo({ start: 1 });

    // The error will be caught by Popcorn.plugin.errors
    pop.listen( "error", function( e ) {
      // 'e' is Popcorn.plugin.errors, which can be accessed outside the "error" event callback.
      console.log( e );
    });

    pop.play();

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( 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
2
3
4

    Popcorn(function() {
      
      var popcorn = Popcorn( "#video" );
    });

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