-
Notifications
You must be signed in to change notification settings - Fork 12
/
index.html
331 lines (257 loc) · 21.5 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
<!DOCTYPE html>
<html>
<head>
<meta charset='utf-8'>
<meta http-equiv="X-UA-Compatible" content="chrome=1">
<script type="text/javascript" src="dist/pluggable.js"></script>
<script type="text/javascript" src="example/app.js"></script>
<script type="text/javascript" src="example/plugin.js"></script>
<link rel="stylesheet" type="text/css" href="stylesheets/stylesheet.css" media="screen">
<link rel="stylesheet" type="text/css" href="stylesheets/github-dark.css" media="screen">
<link rel="stylesheet" type="text/css" href="stylesheets/example.css" media="screen">
<title>pluggable.js by jcbrand</title>
</head>
<body onload="myApp.initialize()">
<header>
<div class="container">
<h1>pluggable.js</h1>
<h2>Lets you make your JS code pluggable while still keeping sensitive objects and data private through closures.</h2>
<section id="downloads">
<a href="https://github.com/jcbrand/pluggable.js/zipball/master" class="btn">Download as .zip</a>
<a href="https://github.com/jcbrand/pluggable.js/tarball/master" class="btn">Download as .tar.gz</a>
<a href="https://github.com/jcbrand/pluggable.js" class="btn btn-github"><span class="icon"></span>View on GitHub</a>
</section>
</div>
</header>
<div class="container">
<section id="main_content">
<pre><code> ____ __ __ __ _
/ __ \/ /_ __ ___ ___ ____ _/ /_ / /__ (_)____
/ /_/ / / / / / __ \/ __ \/ __/ / __ \/ / _ \ / / ___/
/ ____/ / /_/ / /_/ / /_/ / /_/ / /_/ / / __/ / (__ )
/_/ /_/\__,_/\__, /\__, /\__/_/_.___/_/\___(_)_/ /____/
/____//____/ /___/
</code></pre>
<p><a href="https://travis-ci.org/jcbrand/pluggable.js"><img src="https://api.travis-ci.org/jcbrand/pluggable.js.png?branch=master" alt="Travis" /></a></p>
<h1>
<a id="introduction" class="anchor" href="#introduction" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Introduction</h1>
<p>pluggable.js lets you make your JS project extendable via plugins, while still
keeping sensitive objects and data private within es2015 modules or through closures.
</p>
<p>It was originally written for <a href="https://conversejs.org">converse.js</a>, to provide
a plugin architecture that allows 3rd party developers to extend and override
private objects and <a href="http://backbonejs.org">backbone.js</a> classes, but it does not
require nor depend on either library.</p>
<h1>
<a id="size-and-dependencies" class="anchor" href="#size-and-dependencies" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Size and dependencies</h1>
<p>Pluggable.js depends on 8 <a href="http://lodash.com">lodash</a> functions and provides
a custom lodash build with only these functions in the
<a href="https://github.com/jcbrand/pluggable.js/tree/master/3rdparty">3rdparty/</a> directory.
</p>
<p>Pluggable.js itself is only 2.5KB when minified and the custom lodash build is
26KB when minified (both without gzip compression).</p>
<h1>
<a id="documentation" class="anchor" href="#documentation" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Documentation</h1>
<p>To understand how it works under the hood, read the <a href="https://jcbrand.github.io/pluggable.js/docs/pluggable.html">annotated source code</a>.</p>
<h2>
<a id="live-demo-of-the-example-code" class="anchor" href="#live-demo-of-the-example-code" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Live demo of the example code</h2>
<p id="notifications"></p>
<p>
Here's a small example which shows how pluggable.js can be used to
make a private, closured Javascript object pluggable.
</p>
<p>
Further below we'll show the example code and explain how it works.
</p>
<fieldset>
<input type="button" class="btn btn-example" id="notify" value="Click me to show a notification"/>
<input type="button" class="btn btn-example" id="enable" value="Click me to enable the plugin"/>
</fieldset>
<h2>
<a id="usage" class="anchor" href="#usage" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Usage</h2>
<p><em>
Please note: The examples to follow use the ES5 version of Javascript.
Pluggable.js however also works with ES2015 modules.
</em></p>
<p>Suppose you have a module with a private scope and two private methods,
<code>_showNotification</code> and <code>_fadeOut</code>. Let's just assume for the sake of
illustration that there's a good reason why these methods are private.</p>
<p>What we want to do, is to make this module pluggable. In other words, we want
people to be able to write plugins for this module, in which they can:</p>
<ul>
<li>Access the closured scope of this module.</li>
<li>Add new methods to the module.</li>
<li>Override or extend existng methods (private or public) on this module.</li>
</ul>
<p>To make the module pluggable, we simply call <code>pluggable.enable(module);</code>.
Once we've made this call, the <code>module</code> object will have a new property
<code>pluginSocket</code>, which you can think of as the thing into which the plugins are
plugged into. It is an instance of <code>PluginSocket</code>, which represents the plugin
architecture and manages all the plugins.</p>
<p>Additionally, we need to expose some way for plugins to register themselves.
Since the module itself is private, we'll need to expose the <code>registerPlugin</code>
method on the <code>pluginSocket</code> via a public method.</p>
<p>And then finally, once all plugins have been registered, they need to be
initialized by calling <code>initializePlugins</code> on the <code>PluginSocket</code> instance.</p>
<p>For example:</p>
<div class="highlight highlight-source-js"><pre> <span class="pl-c1">module</span>.<span class="pl-smi">pluginSocket</span>.<span class="pl-en">initializePlugins</span>();</pre></div>
<h3>
<a id="example-code-of-a-module-to-be-made-pluggable" class="anchor" href="#example-code-of-a-module-to-be-made-pluggable" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Example code of a module to be made pluggable</h3>
<p>Let's now look at the code for our module (which will go into a file called <code>app.js</code>):</p>
<div class="highlight highlight-source-js"><pre><span class="pl-c">// An example application, used to demonstrate how pluggable.js can</span>
<span class="pl-c">// allow a module to be made pluggable.</span>
(<span class="pl-k">function</span> () {
<span class="pl-k">var</span> <span class="pl-c1">module</span> <span class="pl-k">=</span> <span class="pl-v">this</span>;
<span class="pl-c">// A private method, not available outside the scope of this module.</span>
<span class="pl-c1">module</span>.<span class="pl-en">_showNotification</span> <span class="pl-k">=</span> <span class="pl-k">function</span> (<span class="pl-smi">text</span>) {
<span class="pl-c">/* Displays a notification message */</span>
<span class="pl-k">var</span> el <span class="pl-k">=</span> <span class="pl-c1">document</span>.<span class="pl-c1">createElement</span>(<span class="pl-s"><span class="pl-pds">'</span>p<span class="pl-pds">'</span></span>);
<span class="pl-smi">el</span>.<span class="pl-c1">setAttribute</span>(<span class="pl-s"><span class="pl-pds">'</span>class<span class="pl-pds">'</span></span>, <span class="pl-s"><span class="pl-pds">'</span>notification<span class="pl-pds">'</span></span>);
<span class="pl-smi">el</span>.<span class="pl-c1">appendChild</span>(<span class="pl-c1">document</span>.<span class="pl-c1">createTextNode</span>(text));
el <span class="pl-k">=</span> <span class="pl-c1">document</span>.<span class="pl-c1">getElementById</span>(<span class="pl-s"><span class="pl-pds">'</span>notifications<span class="pl-pds">'</span></span>).<span class="pl-c1">appendChild</span>(el);
setTimeout(<span class="hljs-function"><span class="hljs-params">()</span> =></span> <span class="hljs-built_in">module</span>._fadeOut(el), <span class="hljs-number">3000</span>);
<span class="pl-k">return</span> el;
};
<span class="pl-c">// Another private method, not available outside the scope of this module.</span>
<span class="pl-c1">module</span>.<span class="pl-en">_fadeOut</span> <span class="pl-k">=</span> <span class="pl-k">function</span> (<span class="pl-smi">el</span>) {
<span class="pl-c">/* Fades out the passed in DOM element. */</span>
<span class="pl-smi">el</span>.<span class="pl-c1">style</span>.<span class="pl-smi">opacity</span> <span class="pl-k">=</span> <span class="pl-c1">1</span>;
(<span class="pl-k">function</span> <span class="pl-en">fade</span>() {
<span class="pl-k">if</span> ((<span class="pl-smi">el</span>.<span class="pl-c1">style</span>.<span class="pl-smi">opacity</span> <span class="pl-k">-=</span> <span class="pl-c1">0.1</span>) <span class="pl-k"><</span> <span class="pl-c1">0</span>) {
<span class="pl-smi">el</span>.<span class="pl-en">remove</span>();
} <span class="pl-k">else</span> {
<span class="pl-c1">setTimeout</span>(fade, <span class="pl-c1">25</span>);
}
})();
};
<span class="pl-c">// Initialize this module.</span>
<span class="pl-c">// -----------------------</span>
<span class="pl-c">// There are two buttons for which we register event handlers.</span>
<span class="pl-c">//</span>
<span class="pl-c">// This will be a public method.</span>
<span class="pl-c1">module</span>.<span class="pl-en">initialize</span> <span class="pl-k">=</span> <span class="pl-k">function</span> () {
<span class="pl-k">var</span> notify_el <span class="pl-k">=</span> <span class="pl-c1">document</span>.<span class="pl-c1">getElementById</span>(<span class="pl-s"><span class="pl-pds">'</span>notify<span class="pl-pds">'</span></span>);
<span class="pl-smi">notify_el</span>.<span class="pl-en">addEventListener</span>(<span class="pl-s"><span class="pl-pds">'</span>click<span class="pl-pds">'</span></span>, <span class="pl-k">function</span> () {
<span class="pl-c1">module</span>.<span class="pl-en">_showNotification</span>(<span class="pl-s"><span class="pl-pds">'</span>This is a notification.<span class="pl-pds">'</span></span>);
});
<span class="pl-k">var</span> enable_el <span class="pl-k">=</span> <span class="pl-c1">document</span>.<span class="pl-c1">getElementById</span>(<span class="pl-s"><span class="pl-pds">'</span>enable<span class="pl-pds">'</span></span>);
<span class="pl-smi">enable_el</span>.<span class="pl-en">addEventListener</span>(<span class="pl-s"><span class="pl-pds">'</span>click<span class="pl-pds">'</span></span>, <span class="pl-k">function</span> () {
<span class="pl-v">this</span>.<span class="pl-c1">setAttribute</span>(<span class="pl-s"><span class="pl-pds">'</span>disabled<span class="pl-pds">'</span></span>, <span class="pl-s"><span class="pl-pds">'</span>disabled<span class="pl-pds">'</span></span>);
<span class="pl-c1">module</span>.<span class="pl-smi">pluginSocket</span>.<span class="pl-en">initializePlugins</span>();
});
};
<span class="pl-c">// Register a plugin for this module.</span>
<span class="pl-c">// ----------------------------------</span>
<span class="pl-c">// This is a wrapper method which defers to the `registerPlugin` method</span>
<span class="pl-c">// of pluggable.js, which is on the `pluginSocket` property of the</span>
<span class="pl-c">// private `module` object that was made pluggable, via</span>
<span class="pl-c">// `pluggable.enable(module).</span>
<span class="pl-c">//</span>
<span class="pl-c">// This will be a public method.</span>
<span class="pl-c1">module</span>.<span class="pl-en">registerPlugin</span> <span class="pl-k">=</span> <span class="pl-k">function</span> (<span class="pl-smi">name</span>, <span class="pl-smi">plugin</span>) {
<span class="pl-c1">module</span>.<span class="pl-smi">pluginSocket</span>.<span class="pl-en">registerPlugin</span>(name, plugin);
};
<span class="pl-c">// Calling `pluggable.enable` on the closured `module` object, will make it</span>
<span class="pl-c">// pluggable. Additionally, it will get the `pluginSocket` attribute, which</span>
<span class="pl-c">// refers to the object that the plugins get plugged into.</span>
<span class="pl-smi">pluggable</span>.<span class="pl-en">enable</span>(<span class="pl-c1">module</span>);
<span class="pl-c">// Declare the two public methods</span>
<span class="pl-k">var</span> _public <span class="pl-k">=</span> {
<span class="pl-s"><span class="pl-pds">'</span>initialize<span class="pl-pds">'</span></span><span class="pl-k">:</span> <span class="pl-c1">module</span>.<span class="pl-smi">initialize</span>,
<span class="pl-s"><span class="pl-pds">'</span>registerPlugin<span class="pl-pds">'</span></span><span class="pl-k">:</span> <span class="pl-c1">module</span>.<span class="pl-smi">registerPlugin</span>
};
<span class="pl-c1">window</span>.<span class="pl-smi">myApp</span> <span class="pl-k">=</span> _public;
<span class="pl-k">return</span> _public;
})();</pre></div>
<h3>
<a id="creating-the-plugin" class="anchor" href="#creating-the-plugin" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Creating the plugin</h3>
<p>So, as you can see in the example above, the module has a private method
<code>_showNotification</code>, which will show a notification message in the page.</p>
<p>Let's now create a plugin which overrides this method, so that we can modify the
way the notification message will be displayed.</p>
<p>By the way, multiple plugins can override the same method. As long as
each overriding method calls the original method, via the <code>__super__</code> property,
the method call will travel up through all the overrides (in the reverse order
in which the plugins were registered) back to the original method.</p>
<p>The way to call the method being overridden, is like this:</p>
<div class="highlight highlight-source-js"><pre> <span class="pl-v">this</span>.<span class="pl-smi">__super__</span>.<span class="pl-smi">methodName</span>.<span class="pl-c1">apply</span>(<span class="pl-v">this</span>, <span class="pl-v">arguments</span>);</pre></div>
<p>where <code>methodName</code> is the name of the method. In our example, this will be
<code>showNotification</code>.</p>
<h3>
<a id="example-plugin-code" class="anchor" href="#example-plugin-code" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Example plugin code</h3>
<p>So, with that said, here's what the plugin code (which goes into the file <code>plugin.js</code>)
will look like:</p>
<div class="highlight highlight-source-js"><pre>(<span class="pl-k">function</span> () {
<span class="pl-c">// We call the public `registerPlugin` method from our module in app.js</span>
<span class="pl-c1">window</span>.<span class="pl-smi">myApp</span>.<span class="pl-en">registerPlugin</span>(<span class="pl-s"><span class="pl-pds">'</span>my-plugin<span class="pl-pds">'</span></span>, {
overrides<span class="pl-k">:</span> {
<span class="pl-c">// Here you specify your overrides of methods or objects on the</span>
<span class="pl-c">// module that has been made pluggable.</span>
<span class="pl-c">// Override _showNotification to change the color of notification</span>
<span class="pl-c">// messages.</span>
<span class="pl-en">_showNotification</span><span class="pl-k">:</span> <span class="pl-k">function</span> (<span class="pl-smi">text</span>) {
<span class="pl-c">// When overriding a method, you can still call the original method</span>
<span class="pl-c">// via `this.__super__`. To properly call with the proper `this`</span>
<span class="pl-c">// context and parameters, use `.apply(this, arguments)`.</span>
<span class="pl-k">var</span> el <span class="pl-k">=</span> <span class="pl-v">this</span>.<span class="pl-smi">__super__</span>.<span class="pl-smi">_showNotification</span>.<span class="pl-c1">apply</span>(<span class="pl-v">this</span>, <span class="pl-v">arguments</span>);
<span class="pl-c">// Now we simply set another class on the element containing</span>
<span class="pl-c">// the notifications, so that they'll appear in a different</span>
<span class="pl-c">// color.</span>
<span class="pl-smi">el</span>.<span class="pl-c1">setAttribute</span>(<span class="pl-s"><span class="pl-pds">'</span>class<span class="pl-pds">'</span></span>, <span class="pl-smi">el</span>.<span class="pl-c1">getAttribute</span>(<span class="pl-s"><span class="pl-pds">'</span>class<span class="pl-pds">'</span></span>)<span class="pl-k">+</span><span class="pl-s"><span class="pl-pds">'</span> extra<span class="pl-pds">'</span></span>);
}
<span class="pl-c">// BTW, new methods which don't exist yet can also be added here.</span>
},
<span class="pl-en">initialize</span><span class="pl-k">:</span> <span class="pl-k">function</span> (<span class="pl-smi">socket</span>) {
<span class="pl-c">// The initialize function gets called as soon as the plugin is</span>
<span class="pl-c">// loaded by pluggable.js's plugin machinery.</span>
<span class="pl-c">// We are passed in an instance of the `PluginSocket`, which</span>
<span class="pl-c">// represents the plugin architecture and gets created when</span>
<span class="pl-c">// `pluggable.enable` is called on an object.</span>
<span class="pl-c">// The `PluginSocket` instance is also accessible via the `pluginSocket`</span>
<span class="pl-c">// attribute, on the module that was passed to `pluggable.enable`.</span>
<span class="pl-c">// You can get hold of the module which was made pluggable</span>
<span class="pl-c">// via the `plugged` property of the `PluginSocket` instance.</span>
<span class="pl-c">// Once you have the module, you can access its private properties</span>
<span class="pl-c">// and call its private methods.</span>
<span class="pl-c">// Here, once this plugin is initialized, we show a notification.</span>
<span class="pl-smi">socket</span>.<span class="pl-smi">plugged</span>.<span class="pl-en">_showNotification</span>(
<span class="pl-s"><span class="pl-pds">"</span>The plugin has been enabled. Notifications are now a different color.<span class="pl-pds">"</span></span>
);
}
});
})();</pre></div>
<h3>
<a id="custom-plugin-code" class="anchor" href="#custom-plugin-code" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Custom plugin code</h3>
<p>The plugin has three important parts to it. Firstly, a call to register the
plugin must be made, and then passed in with this call is an object which
represents the plugin itself.</p>
<p>This plugin object has an <code>overrides</code> key, which is another object containing methods
and objects that will override similarly named methods and object properties on the
module itself.</p>
<p>Additionally, the <code>initializePlugins</code> method has been called on the
<code>pluginSocket</code> instance.</p>
<p>This happens inside our module in app.js and this methods should generally be
called once, after all plugins have been registered and after the module being
made pluggable has itself been initialized.</p>
<p>In the <code>initialize</code> method, you have access the module's scope, which would
otherwise not be available to you.</p>
<p>So, as you can see, the plugin lets us achieve our three goals stated earlier:</p>
<h3>
<a id="access-the-closured-scope-of-this-module" class="anchor" href="#access-the-closured-scope-of-this-module" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>1. Access the closured scope of this module.</h3>
<p>We have access to the module and all its properties and methods inside the
<code>initialize</code> method of our plugin.</p>
<h3>
<a id="add-new-methods-to-the-module" class="anchor" href="#add-new-methods-to-the-module" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>2. Add new methods to the module.</h3>
<p>We can add new methods to our module, either inside the <code>initialize</code> method of
our plugin, or by stating them declaratively in <code>overrides</code> object.</p>
<h3>
<a id="override-or-extend-existng-methods-private-or-public-on-this-module" class="anchor" href="#override-or-extend-existng-methods-private-or-public-on-this-module" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>3. Override or extend existng methods (private or public) on this module.</h3>
<p>We can override existing methods and object properties via the <code>overrides</code>
object.</p>
</section>
<h2>Contact</h2>
<p>For issues and requests, please use the project's <a href="https://github.com/jcbrand/pluggable.js/issues">issue tracker</a>.</p>
<p>You can reach me via my website's <a href="http://opkode.com/contact.html">contact form</a> and you can also <a href="https://twitter.com/jcopkode">follow me on twitter</a>.</p>
</div>
</body>
</html>