Popcorn API, Three Popcorn.js plugin patterns, and the plugin manifes

popcorn-api.js

// Popcorn Instance Methods
var p = Popcorn( "#video" )

p.play()
// Play the video (Native "pass through" method)
// Returns the Popcorn instance object

p.load()
// Load the video (Native "pass through" method)
// Returns the Popcorn instance object

p.pause()
// Pause the video (Native "pass through" method)
// Returns the Popcorn instance object

p.mute()
// Toggle mute (Native "pass through" method)
// Returns the Popcorn instance object

p.volume( arg )
// Get and set the volume (Native "pass through" method)
// Returns the Popcorn instance object

p.duration()
// Get the duration (Native "pass through" method)
// Returns the Popcorn instance object

p.currentTime( [arg] )
// Get and set the current time (Native "pass through" method)
// Getter returns current time
// Setter returns the Popcorn instance object

p.playbackRate( [arg] )
// Get and set the playback rate (Native "pass through" method)
// Getter returns playback rate
// Setter returns the Popcorn instance object

p.exec( time, callback )
// Bind a callback function to a time in miliseconds (New Popcorn.js method)
// Returns the Popcorn instance object

p.trigger( type, data )
// Trigger an event (New Popcorn.js method)
// Returns the Popcorn instance object

p.listen( eventtype, callback )
// Bind to an event (New Popcorn.js method)
// Returns the Popcorn instance object

p.unlisten( eventtype, 'callbackbackname' )
// Unbind an event listen (New Popcorn.js method)er
// Returns the Popcorn instance object

p.removeTrackEvent( id )
// Remove a track event (New Popcorn.js method)
// Returns undefined

p.getTrackEvents()
// Get the track events (New Popcorn.js method)
// Returns the track events

p.getLastTrackEventId()
// Get the id of the last track event that was added (New Popcorn.js method)
// Returns the id of the last track event added

p.removePlugin( 'pluginname' )
// Remove a plugin from the registry (New Popcorn.js method)


//Popcorn HTMLVideoElement reference
Popcorn.video: HTMLVideoElement


//Popcorn Utility Methods
Popcorn.plugin( 'pluginname', definition )
// Register a plugin with popcorn
// Definition can be a function or an object
// Returns reference to the plugin when possible

Popcorn.forEach( object, callback( value, index ), context )
// ES5 compliant foreach
// Returns the object that you passed into it

Popcorn.extend( object, [ argN ] )
// Merge two objects
// Returns the extended object

Popcorn.sizeOf( object )
// Get number of properties in an object
// Returns the number of properties in the object

Popcorn.nop()
// A no operation function expression
// Returns undefined


// Popcorn Events
loadstart, progress, suspend, emptied, stalled, play, pause,
loadedmetadata, loadeddata, waiting, playing, canplay, canplaythrough,
seeking, seeked, timeupdate, ended, ratechange, durationchange, volumechange

popcorn-manifest.js

// 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 ){...}
  })();
})(Popcorn);

popcorn-plugin-patterns.js

// 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 {
      start: function(){...},
      end: function(){...}
    };
  });
})(Popcorn);


// Pattern 2
// Provide an object
// Popcorn will manage the events 
(function (Popcorn) {  
  Popcorn.plugin( "pluginName" , {
    _setup : function( options ) {
       // setup code, fire on initialization
       // options refers to the options passed into the plugin on init
       // this refers to the popcorn object
    },
    start: function( event, options ){
       // fire on options.start
       // event refers to the event object
       // options refers to the options passed into the plugin on init
       // this refers to the popcorn object
    },
    end: function( event, options ){
       // fire on options.end
       // event refers to the event object
       // options refers to the options passed into the plugin on init
       // 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( options ) {
         // setup code, fire on initialization
         // options refers to the options passed into the plugin on init
         // this refers to the popcorn object
      },
      start: function( event, options ){
         // fire on options.start
         // event refers to the event object
         // options refers to the options passed into the plugin on init
         // this refers to the popcorn object
      },
      end: function( event, options ){
         // fire on options.end
         // event refers to the event object
         // options refers to the options passed into the plugin on init
         // this refers to the popcorn object
      }
  })();
})(Popcorn);