Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Tree: e844c26f3a
Fetching contributors…

Cannot retrieve contributors at this time

289 lines (219 sloc) 10.015 kB
title
Plugins

Plugins

Popcorn offers a plugin factory that allows user to create their own plugins to synchronize with the playable media timeline.

Document and Directory Setup

  1. Create a folder popcorn-js/plugins/pluginname
  2. Create 4 files:
    • popcorn.pluginname.html – The demo file, contains html to run plugin
    • popcorn.pluginname.js – The code file, contains plugin
    • popcorn.pluginname.unit.html – The demo test file, contains html test framework
    • popcorn.pluginname.unit.js – The code test file, contains unit tests

Making the plugin

Choose a pattern from the Popcorn Plugin API section below.

Be sure to eliminate dependencies. A plugin should not require jQuery to run. We have also written a best practices guide for plugin development.

Making unit tests

qunit is used for unit tests. The unit test files are only necessary if you wish to make your plugin an official popcorn.js plugin and get it reviewed.

Popcorn Plugin API

Popcorn also offers a plugin factory. Popcorn plugins are a way for developers to wrap functionality that responds to a point in a video. Pattern 1 below lets you manage time updating by your self, where as patterns 2 and 3 offer a structure to manage your video events for you.

{% highlight js linenos %} // Pattern 1 // Provide a function that returns an object (function( Popcorn ) { Popcorn.plugin( "pluginName" , function( options ) { // do stuff // this refers to the popcorn object

    // You are required to return an object
    // with a start and end property
    return {
      _setup: function( track ) {
        // setup code, fire on initialization

        // |track| refers to the TrackEvent created by the options passed
        // into the plugin on init

        // this refers to the popcorn object
      },
      _update: function( track ) {
        // update code, fire on update/modification of a plugin created track event.

        // |track| refers to the TrackEvent created by the options passed
        // into the plugin on init

        // this refers to the popcorn object
      },
      _teardown: function( track ) {
        // teardown code, fire on removal of plugin or destruction of instance

        // |track| refers to the TrackEvent created by the options passed
        // into the plugin on init

        // this refers to the popcorn object
      },
      start: function( event, track ) {
        // fire on track.start

        // |event| refers to the event object

        // |track| refers to the TrackEvent created by the options passed
        // into the plugin on init

        // this refers to the popcorn object
      },
      end: function( event, track ) {
        // fire on track.end

        // |event| refers to the event object

        // |track| refers to the TrackEvent created by the options passed
        // into the plugin on init

        // this refers to the popcorn object
      },
      frame: function( event, track ) {
        // when frameAnimation is enabled, fire on every frame between start and end

        // |event| refers to the event object

        // |track| refers to the TrackEvent created by the options passed
        // into the plugin on init

        // this refers to the popcorn object
      },
      toString: function() {
        // provide a custom toString method for each plugin
        // defaults to return start, end, id, and target
        // this refers to the popcorn object
      }
    };
  });
})(Popcorn);


// Pattern 2
// Provide an object
// Popcorn will manage the events
(function( Popcorn ) {
  Popcorn.plugin( "pluginName" , {
    _setup: function( track ) {
      // setup code, fire on initialization

      // |track| refers to the TrackEvent created by the options passed
      // into the plugin on init

      // this refers to the popcorn object
    },
    _update: function( track ) {
      // update code, fire on update/modification of a plugin created track event.

      // |track| refers to the TrackEvent created by the options passed
      // into the plugin on init

      // this refers to the popcorn object
    },
    _teardown: function( track ) {
      // teardown code, fire on removal of plugin or destruction of instance

      // |track| refers to the TrackEvent created by the options passed
      // into the plugin on init

      // this refers to the popcorn object
    },
    start: function( event, track ) {
      // fire on track.start

      // |event| refers to the event object

      // |track| refers to the TrackEvent created by the options passed
      // into the plugin on init

      // this refers to the popcorn object
    },
    end: function( event, track ) {
      // fire on track.end

      // |event| refers to the event object

      // |track| refers to the TrackEvent created by the options passed
      // into the plugin on init

      // this refers to the popcorn object
    },
    frame: function( event, track ) {
      // when frameAnimation is enabled, fire on every frame between start and end

      // |event| refers to the event object

      // |track| refers to the TrackEvent created by the options passed
      // into the plugin on init

      // this refers to the popcorn object
    },
    toString: function() {
      // provide a custom toString method for each plugin
      // defaults to return start, end, id, and target
      // this refers to the popcorn object
    }
  });
})(Popcorn);


// Pattern 3
// Provide an object with a plugin wide name space
// Popcorn will manage the events
(function( Popcorn ) {
  Popcorn.plugin( "pluginName", (function() {

    // Define plugin wide variables out here

    return {
      _setup: function( track ) {
        // setup code, fire on initialization

        // |track| refers to the TrackEvent created by the options passed
        // into the plugin on init

        // this refers to the popcorn object
      },
      _update: function( track ) {
        // update code, fire on update/modification of a plugin created track event.

        // |track| refers to the TrackEvent created by the options passed
        // into the plugin on init

        // this refers to the popcorn object
      },
      _teardown: function( track ) {
        // teardown code, fire on removal of plugin or destruction of instance

        // |track| refers to the TrackEvent created by the options passed
        // into the plugin on init

        // this refers to the popcorn object
      },
      start: function( event, track ) {
        // fire on track.start

        // |event| refers to the event object

        // |track| refers to the TrackEvent created by the options passed
        // into the plugin on init

        // this refers to the popcorn object
      },
      end: function( event, track ) {
        // fire on track.end

        // |event| refers to the event object

        // |track| refers to the TrackEvent created by the options passed
        // into the plugin on init

        // this refers to the popcorn object
      },
      frame: function( event, track ) {
        // when frameAnimation is enabled, fire on every frame between start and end

        // |event| refers to the event object

        // |track| refers to the TrackEvent created by the options passed
        // into the plugin on init

        // this refers to the popcorn object
      },
      toString: function() {
        // provide a custom toString method for each plugin
        // defaults to return start, end, id, and target
        // this refers to the popcorn object
      }
    };
  })();
})(Popcorn);

{% endhighlight %}

Plugin Manifest Interface for Butter

Butter, popcorn’s point and click authoring tool offers plugin authors a turnkey interface to it’s UI through plugin manifests as demonstrated below:

{% highlight js linenos %} // Pattern 3 // Provide a plugin manifest with your plugin // This allows for butter to register your plugin (function( Popcorn ) { Popcorn.plugin( "pluginName", (function() {

    // Define plugin wide variables out here

    return {
      // Define a manifest for the butter authoring tool to use
      manifest: {
        // Plugin meta data
        // will be used in the butter ui
        about: {
          name: "name of plugin",
          version: "semantic version",
          author: "author name",
          website: "author url"
        },
        // Object representation of the plugin options
        // a form will be constructed against this object
        options: {
          start: { elem: "input", type: "text", label: "In" },
          end: { elem: "input", type: "text", label: "Out" },
          target: "id-selector",
          text: { elem: "input", type: "text", label: "Text" }
        }
      },
      _setup: function( options ){...},
      start: function( options ){...},
      end: function( options ){...},
      frame: function( options ){...},
      toString: function( options ){...}
  })());
})(Popcorn);

{% endhighlight %}

Jump to Line
Something went wrong with that request. Please try again.