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
- 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
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.
1 // Pattern 1
2 // Provide a function that returns an object
3 (function( Popcorn ) {
4 Popcorn.plugin( "pluginName" , function( options ) {
5 // do stuff
6 // this refers to the popcorn object
7
8 // You are required to return an object
9 // with a start and end property
10 return {
11 _setup: function( track ) {
12 // setup code, fire on initialization
13
14 // |track| refers to the TrackEvent created by the options passed
15 // into the plugin on init
16
17 // this refers to the popcorn object
18 },
19 _update: function( track, updates ) {
20 // update code, fire on update/modification of a plugin created track event.
21
22 // |track| refers to the TrackEvent created by the options passed
23 // into the plugin on init
24
25 // |updates| refers to the new plugin data to be applied,
26 // loop through this and apply the necessary updates to track
27
28 // this refers to the popcorn object
29 },
30 _teardown: function( track ) {
31 // teardown code, fire on removal of plugin or destruction of instance
32
33 // |track| refers to the TrackEvent created by the options passed
34 // into the plugin on init
35
36 // this refers to the popcorn object
37 },
38 start: function( event, track ) {
39 // fire on track.start
40
41 // |event| refers to the event object
42
43 // |track| refers to the TrackEvent created by the options passed
44 // into the plugin on init
45
46 // this refers to the popcorn object
47 },
48 end: function( event, track ) {
49 // fire on track.end
50
51 // |event| refers to the event object
52
53 // |track| refers to the TrackEvent created by the options passed
54 // into the plugin on init
55
56 // this refers to the popcorn object
57 },
58 frame: function( event, track ) {
59 // when frameAnimation is enabled, fire on every frame between start and end
60
61 // |event| refers to the event object
62
63 // |track| refers to the TrackEvent created by the options passed
64 // into the plugin on init
65
66 // this refers to the popcorn object
67 },
68 toString: function() {
69 // provide a custom toString method for each plugin
70 // defaults to return start, end, id, and target
71 // this refers to the popcorn object
72 }
73 };
74 });
75 })(Popcorn);
76
77
78 // Pattern 2
79 // Provide an object
80 // Popcorn will manage the events
81 (function( Popcorn ) {
82 Popcorn.plugin( "pluginName" , {
83 _setup: function( track ) {
84 // setup code, fire on initialization
85
86 // |track| refers to the TrackEvent created by the options passed
87 // into the plugin on init
88
89 // this refers to the popcorn object
90 },
91 _update: function( track ) {
92 // update code, fire on update/modification of a plugin created track event.
93
94 // |track| refers to the TrackEvent created by the options passed
95 // into the plugin on init
96
97 // this refers to the popcorn object
98 },
99 _teardown: function( track ) {
100 // teardown code, fire on removal of plugin or destruction of instance
101
102 // |track| refers to the TrackEvent created by the options passed
103 // into the plugin on init
104
105 // this refers to the popcorn object
106 },
107 start: function( event, track ) {
108 // fire on track.start
109
110 // |event| refers to the event object
111
112 // |track| refers to the TrackEvent created by the options passed
113 // into the plugin on init
114
115 // this refers to the popcorn object
116 },
117 end: function( event, track ) {
118 // fire on track.end
119
120 // |event| refers to the event object
121
122 // |track| refers to the TrackEvent created by the options passed
123 // into the plugin on init
124
125 // this refers to the popcorn object
126 },
127 frame: function( event, track ) {
128 // when frameAnimation is enabled, fire on every frame between start and end
129
130 // |event| refers to the event object
131
132 // |track| refers to the TrackEvent created by the options passed
133 // into the plugin on init
134
135 // this refers to the popcorn object
136 },
137 toString: function() {
138 // provide a custom toString method for each plugin
139 // defaults to return start, end, id, and target
140 // this refers to the popcorn object
141 }
142 });
143 })(Popcorn);
144
145
146 // Pattern 3
147 // Provide an object with a plugin wide name space
148 // Popcorn will manage the events
149 (function( Popcorn ) {
150 Popcorn.plugin( "pluginName", (function() {
151
152 // Define plugin wide variables out here
153
154 return {
155 _setup: function( track ) {
156 // setup code, fire on initialization
157
158 // |track| refers to the TrackEvent created by the options passed
159 // into the plugin on init
160
161 // this refers to the popcorn object
162 },
163 _update: function( track ) {
164 // update code, fire on update/modification of a plugin created track event.
165
166 // |track| refers to the TrackEvent created by the options passed
167 // into the plugin on init
168
169 // this refers to the popcorn object
170 },
171 _teardown: function( track ) {
172 // teardown code, fire on removal of plugin or destruction of instance
173
174 // |track| refers to the TrackEvent created by the options passed
175 // into the plugin on init
176
177 // this refers to the popcorn object
178 },
179 start: function( event, track ) {
180 // fire on track.start
181
182 // |event| refers to the event object
183
184 // |track| refers to the TrackEvent created by the options passed
185 // into the plugin on init
186
187 // this refers to the popcorn object
188 },
189 end: function( event, track ) {
190 // fire on track.end
191
192 // |event| refers to the event object
193
194 // |track| refers to the TrackEvent created by the options passed
195 // into the plugin on init
196
197 // this refers to the popcorn object
198 },
199 frame: function( event, track ) {
200 // when frameAnimation is enabled, fire on every frame between start and end
201
202 // |event| refers to the event object
203
204 // |track| refers to the TrackEvent created by the options passed
205 // into the plugin on init
206
207 // this refers to the popcorn object
208 },
209 toString: function() {
210 // provide a custom toString method for each plugin
211 // defaults to return start, end, id, and target
212 // this refers to the popcorn object
213 }
214 };
215 })();
216 })(Popcorn);
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:
1 // Pattern 3
2 // Provide a plugin manifest with your plugin
3 // This allows for butter to register your plugin
4 (function( Popcorn ) {
5 Popcorn.plugin( "pluginName", (function() {
6
7 // Define plugin wide variables out here
8
9 return {
10 // Define a manifest for the butter authoring tool to use
11 manifest: {
12 // Plugin meta data
13 // will be used in the butter ui
14 about: {
15 name: "name of plugin",
16 version: "semantic version",
17 author: "author name",
18 website: "author url"
19 },
20 // Object representation of the plugin options
21 // a form will be constructed against this object
22 options: {
23 start: { elem: "input", type: "text", label: "In" },
24 end: { elem: "input", type: "text", label: "Out" },
25 target: "id-selector",
26 text: { elem: "input", type: "text", label: "Text" }
27 }
28 },
29 _setup: function( options ){...},
30 start: function( options ){...},
31 end: function( options ){...},
32 frame: function( options ){...},
33 toString: function( options ){...}
34 })());
35 })(Popcorn);