| title |
|---|
Plugins |
Popcorn offers a plugin factory that allows user to create their own plugins to synchronize with the playable media timeline.
- Create a folder popcorn-js/plugins/pluginname
- 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
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.
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 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 %}