pluggable.js/index.html at master · conversejs/pluggable.js · GitHub

Repository navigation

History

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>

<title>pluggable.js by jcbrand</title>

</head>

<h1>pluggable.js</h1>

<h2>Lets you make your JS code pluggable while still keeping sensitive objects and data private through closures.</h2>

<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">View on GitHub</a>

</section>

</div>

</header>

<pre><code> ____ __ __ __ _

/ __ \/ /_ __ ___ ___ ____ _/ /_ / /__ (_)____

/ /_/ / / / / / __ \/ __ \/ __/ / __ \/ / _ \ / / ___/

/ ____/ / /_/ / /_/ / /_/ / /_/ / /_/ / / __/ / (__ )

/_/ /_/\__,_/\__, /\__, /\__/_/_.___/_/\___(_)_/ /____/

/____//____/ /___/

</code></pre>

<h1>

<a id="introduction" class="anchor" href="#introduction" aria-hidden="true"></a>Introduction</h1>

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.

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.

<h1>

<a id="size-and-dependencies" class="anchor" href="#size-and-dependencies" aria-hidden="true"></a>Size and dependencies</h1>

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.

Pluggable.js itself is only 2.5KB when minified and the custom lodash build is

26KB when minified (both without gzip compression).

<h1>

<a id="documentation" class="anchor" href="#documentation" aria-hidden="true"></a>Documentation</h1>

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>.

<h2>

<a id="live-demo-of-the-example-code" class="anchor" href="#live-demo-of-the-example-code" aria-hidden="true"></a>Live demo of the example code</h2>

Here's a small example which shows how pluggable.js can be used to

make a private, closured Javascript object pluggable.

Further below we'll show the example code and explain how it works.

</fieldset>

<h2>

<a id="usage" class="anchor" href="#usage" aria-hidden="true"></a>Usage</h2>

Please note: The examples to follow use the ES5 version of Javascript.

Pluggable.js however also works with ES2015 modules.

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.

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:

<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>

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.

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.

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.

For example:

<div class="highlight highlight-source-js"><pre> module.pluginSocket.initializePlugins();</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"></a>Example code of a module to be made pluggable</h3>

Let's now look at the code for our module (which will go into a file called <code>app.js</code>):

<div class="highlight highlight-source-js"><pre>// An example application, used to demonstrate how pluggable.js can

// allow a module to be made pluggable.

(function () {

var module = this;

// A private method, not available outside the scope of this module.

module._showNotification = function (text) {

/* Displays a notification message */

var el = document.createElement('p');

el.appendChild(document.createTextNode(text));

el = document.getElementById('notifications').appendChild(el);

setTimeout(() => module._fadeOut(el), 3000);

return el;

};

// Another private method, not available outside the scope of this module.

module._fadeOut = function (el) {

/* Fades out the passed in DOM element. */

el.style.opacity = 1;

(function fade() {

if ((el.style.opacity -= 0.1) < 0) {

el.remove();

} else {

setTimeout(fade, 25);

}

})();

};

// Initialize this module.

// -----------------------

// There are two buttons for which we register event handlers.

//

// This will be a public method.

module.initialize = function () {

var notify_el = document.getElementById('notify');

notify_el.addEventListener('click', function () {

module._showNotification('This is a notification.');

});

var enable_el = document.getElementById('enable');

enable_el.addEventListener('click', function () {

this.setAttribute('disabled', 'disabled');

module.pluginSocket.initializePlugins();

});

};

// Register a plugin for this module.

// ----------------------------------

// This is a wrapper method which defers to the `registerPlugin` method

// of pluggable.js, which is on the `pluginSocket` property of the

// private `module` object that was made pluggable, via

// `pluggable.enable(module).

//

// This will be a public method.

module.registerPlugin = function (name, plugin) {

module.pluginSocket.registerPlugin(name, plugin);

};

// Calling `pluggable.enable` on the closured `module` object, will make it

// pluggable. Additionally, it will get the `pluginSocket` attribute, which

// refers to the object that the plugins get plugged into.

pluggable.enable(module);

// Declare the two public methods

var _public = {

'initialize': module.initialize,

'registerPlugin': module.registerPlugin

};

window.myApp = _public;

return _public;

})();</pre></div>

<h3>

<a id="creating-the-plugin" class="anchor" href="#creating-the-plugin" aria-hidden="true"></a>Creating the plugin</h3>

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.

Let's now create a plugin which overrides this method, so that we can modify the

way the notification message will be displayed.

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.

The way to call the method being overridden, is like this:

<div class="highlight highlight-source-js"><pre> this.__super__.methodName.apply(this, arguments);</pre></div>

where <code>methodName</code> is the name of the method. In our example, this will be

<code>showNotification</code>.

<h3>

<a id="example-plugin-code" class="anchor" href="#example-plugin-code" aria-hidden="true"></a>Example plugin code</h3>

So, with that said, here's what the plugin code (which goes into the file <code>plugin.js</code>)

will look like:

<div class="highlight highlight-source-js"><pre>(function () {

// We call the public `registerPlugin` method from our module in app.js

window.myApp.registerPlugin('my-plugin', {

overrides: {

// Here you specify your overrides of methods or objects on the

// module that has been made pluggable.

// Override _showNotification to change the color of notification

// messages.

_showNotification: function (text) {

// When overriding a method, you can still call the original method

// via `this.__super__`. To properly call with the proper `this`

// context and parameters, use `.apply(this, arguments)`.

var el = this.__super__._showNotification.apply(this, arguments);

// Now we simply set another class on the element containing

// the notifications, so that they'll appear in a different

// color.

el.setAttribute('class', el.getAttribute('class')+' extra');

}

// BTW, new methods which don't exist yet can also be added here.

initialize: function (socket) {

// The initialize function gets called as soon as the plugin is

// loaded by pluggable.js's plugin machinery.

// We are passed in an instance of the `PluginSocket`, which

// represents the plugin architecture and gets created when

// `pluggable.enable` is called on an object.

// The `PluginSocket` instance is also accessible via the `pluginSocket`

// attribute, on the module that was passed to `pluggable.enable`.

// You can get hold of the module which was made pluggable

// via the `plugged` property of the `PluginSocket` instance.

// Once you have the module, you can access its private properties

// and call its private methods.

// Here, once this plugin is initialized, we show a notification.

socket.plugged._showNotification(

"The plugin has been enabled. Notifications are now a different color."

);

}

});

})();</pre></div>

<h3>

<a id="custom-plugin-code" class="anchor" href="#custom-plugin-code" aria-hidden="true"></a>Custom plugin code</h3>

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.

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.

Additionally, the <code>initializePlugins</code> method has been called on the

<code>pluginSocket</code> instance.

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.

In the <code>initialize</code> method, you have access the module's scope, which would

otherwise not be available to you.

So, as you can see, the plugin lets us achieve our three goals stated earlier:

<h3>

<a id="access-the-closured-scope-of-this-module" class="anchor" href="#access-the-closured-scope-of-this-module" aria-hidden="true"></a>1. Access the closured scope of this module.</h3>

We have access to the module and all its properties and methods inside the

<code>initialize</code> method of our plugin.

<h3>

<a id="add-new-methods-to-the-module" class="anchor" href="#add-new-methods-to-the-module" aria-hidden="true"></a>2. Add new methods to the module.</h3>

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.

<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"></a>3. Override or extend existng methods (private or public) on this module.</h3>

We can override existing methods and object properties via the <code>overrides</code>

object.

</section>

<h2>Contact</h2>

For issues and requests, please use the project's <a href="https://github.com/jcbrand/pluggable.js/issues">issue tracker</a>.

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>.

</div>

</body>

</html>

pluggable.js/index.html at master · conversejs/pluggable.js · GitHub

Repository navigation

Expand file tree

Breadcrumbs

index.html

Latest commit

History

Breadcrumbs

index.html

File metadata and controls