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 ) {
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 // this refers to the popcorn object
26 },
27 _teardown: function( track ) {
28 // teardown code, fire on removal of plugin or destruction of instance
29
30 // |track| refers to the TrackEvent created by the options passed
31 // into the plugin on init
32
33 // this refers to the popcorn object
34 },
35 start: function( event, track ) {
36 // fire on track.start
37
38 // |event| refers to the event object
39
40 // |track| refers to the TrackEvent created by the options passed
41 // into the plugin on init
42
43 // this refers to the popcorn object
44 },
45 end: function( event, track ) {
46 // fire on track.end
47
48 // |event| refers to the event object
49
50 // |track| refers to the TrackEvent created by the options passed
51 // into the plugin on init
52
53 // this refers to the popcorn object
54 },
55 frame: function( event, track ) {
56 // when frameAnimation is enabled, fire on every frame between start and end
57
58 // |event| refers to the event object
59
60 // |track| refers to the TrackEvent created by the options passed
61 // into the plugin on init
62
63 // this refers to the popcorn object
64 },
65 toString: function() {
66 // provide a custom toString method for each plugin
67 // defaults to return start, end, id, and target
68 // this refers to the popcorn object
69 }
70 };
71 });
72 })(Popcorn);
73
74
75 // Pattern 2
76 // Provide an object
77 // Popcorn will manage the events
78 (function( Popcorn ) {
79 Popcorn.plugin( "pluginName" , {
80 _setup: function( track ) {
81 // setup code, fire on initialization
82
83 // |track| refers to the TrackEvent created by the options passed
84 // into the plugin on init
85
86 // this refers to the popcorn object
87 },
88 _update: function( track ) {
89 // update code, fire on update/modification of a plugin created track event.
90
91 // |track| refers to the TrackEvent created by the options passed
92 // into the plugin on init
93
94 // this refers to the popcorn object
95 },
96 _teardown: function( track ) {
97 // teardown code, fire on removal of plugin or destruction of instance
98
99 // |track| refers to the TrackEvent created by the options passed
100 // into the plugin on init
101
102 // this refers to the popcorn object
103 },
104 start: function( event, track ) {
105 // fire on track.start
106
107 // |event| refers to the event object
108
109 // |track| refers to the TrackEvent created by the options passed
110 // into the plugin on init
111
112 // this refers to the popcorn object
113 },
114 end: function( event, track ) {
115 // fire on track.end
116
117 // |event| refers to the event object
118
119 // |track| refers to the TrackEvent created by the options passed
120 // into the plugin on init
121
122 // this refers to the popcorn object
123 },
124 frame: function( event, track ) {
125 // when frameAnimation is enabled, fire on every frame between start and end
126
127 // |event| refers to the event object
128
129 // |track| refers to the TrackEvent created by the options passed
130 // into the plugin on init
131
132 // this refers to the popcorn object
133 },
134 toString: function() {
135 // provide a custom toString method for each plugin
136 // defaults to return start, end, id, and target
137 // this refers to the popcorn object
138 }
139 });
140 })(Popcorn);
141
142
143 // Pattern 3
144 // Provide an object with a plugin wide name space
145 // Popcorn will manage the events
146 (function( Popcorn ) {
147 Popcorn.plugin( "pluginName", (function() {
148
149 // Define plugin wide variables out here
150
151 return {
152 _setup: function( track ) {
153 // setup code, fire on initialization
154
155 // |track| refers to the TrackEvent created by the options passed
156 // into the plugin on init
157
158 // this refers to the popcorn object
159 },
160 _update: function( track ) {
161 // update code, fire on update/modification of a plugin created track event.
162
163 // |track| refers to the TrackEvent created by the options passed
164 // into the plugin on init
165
166 // this refers to the popcorn object
167 },
168 _teardown: function( track ) {
169 // teardown code, fire on removal of plugin or destruction of instance
170
171 // |track| refers to the TrackEvent created by the options passed
172 // into the plugin on init
173
174 // this refers to the popcorn object
175 },
176 start: function( event, track ) {
177 // fire on track.start
178
179 // |event| refers to the event object
180
181 // |track| refers to the TrackEvent created by the options passed
182 // into the plugin on init
183
184 // this refers to the popcorn object
185 },
186 end: function( event, track ) {
187 // fire on track.end
188
189 // |event| refers to the event object
190
191 // |track| refers to the TrackEvent created by the options passed
192 // into the plugin on init
193
194 // this refers to the popcorn object
195 },
196 frame: function( event, track ) {
197 // when frameAnimation is enabled, fire on every frame between start and end
198
199 // |event| refers to the event object
200
201 // |track| refers to the TrackEvent created by the options passed
202 // into the plugin on init
203
204 // this refers to the popcorn object
205 },
206 toString: function() {
207 // provide a custom toString method for each plugin
208 // defaults to return start, end, id, and target
209 // this refers to the popcorn object
210 }
211 };
212 })();
213 })(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);