Update plugin example with code from the yeoman generator
Also improve the introductory text.
This commit is contained in:
parent
4104dec89b
commit
f668f2981a
|
@ -14,24 +14,36 @@ Writing a plugin
|
||||||
Introduction
|
Introduction
|
||||||
------------
|
------------
|
||||||
|
|
||||||
Developers are able to extend and override the objects, functions and the
|
Converse.js is exposes a plugin architecture which allows developers to modify
|
||||||
Backbone models and views that make up converse.js by means of writing plugins.
|
and extend its functionality.
|
||||||
|
|
||||||
|
Specifically, plugins enable developers to extend and override existing objects,
|
||||||
|
functions and `Backbone <http://backbonejs.org/>`_ models and views that make up
|
||||||
|
Converse.js, and also give them the ability to write new models and views.
|
||||||
|
|
||||||
|
Various core features of Converse.js, such as
|
||||||
|
`Message Archive Management <https://xmpp.org/extensions/xep-0313.html>`_ and
|
||||||
|
`Group chats <https://xmpp.org/extensions/xep-0045.html>`_ are implemented
|
||||||
|
as plugins, thereby showing their power and flexibility.
|
||||||
|
|
||||||
Converse.js uses `pluggable.js <https://github.com/jcbrand/pluggable.js/>`_ as
|
Converse.js uses `pluggable.js <https://github.com/jcbrand/pluggable.js/>`_ as
|
||||||
its plugin architecture.
|
its plugin architecture.
|
||||||
|
|
||||||
To understand how this plugin architecture works, please read the
|
To more deeply understand how this plugin architecture works, please read the
|
||||||
`pluggable.js documentation <https://jcbrand.github.io/pluggable.js/>`_
|
`pluggable.js documentation <https://jcbrand.github.io/pluggable.js/>`_
|
||||||
and to understand its inner workins, please refer to the `annotated source code
|
and to understand its inner workins, please refer to the `annotated source code
|
||||||
<https://jcbrand.github.io/pluggable.js/docs/pluggable.html>`_.
|
<https://jcbrand.github.io/pluggable.js/docs/pluggable.html>`_.
|
||||||
|
|
||||||
Below you'll find an example plugin. Because convers.js is only Javascript,
|
Playing with a Converse.js plugin in JSFiddle
|
||||||
HTML and CSS (with no backend code required like PHP, Python or Ruby) it runs
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
fine in JSFiddle.
|
|
||||||
|
|
||||||
Here's an Fiddle with a plugin that calls `alert` when the plugin gets
|
Because Converse.js consists only of JavaScript, HTML and CSS (with no backend
|
||||||
initialized and when a message gets rendered: https://jsfiddle.net/4drfaok0/15/
|
code required like PHP, Python or Ruby) it runs fine in JSFiddle.
|
||||||
|
|
||||||
|
Here's an Fiddle with a Converse.js plugin that calls `alert` once it gets
|
||||||
|
initialized and also when a chat message gets rendered:
|
||||||
|
|
||||||
|
https://jsfiddle.net/4drfaok0/15/
|
||||||
|
|
||||||
Registering a plugin
|
Registering a plugin
|
||||||
--------------------
|
--------------------
|
||||||
|
@ -234,7 +246,7 @@ A full example plugin
|
||||||
(function (root, factory) {
|
(function (root, factory) {
|
||||||
if (typeof define === 'function' && define.amd) {
|
if (typeof define === 'function' && define.amd) {
|
||||||
// AMD. Register as a module called "myplugin"
|
// AMD. Register as a module called "myplugin"
|
||||||
define("myplugin", ["converse"], factory);
|
define("<%= name %>", ["converse"], factory);
|
||||||
} else {
|
} else {
|
||||||
// Browser globals. If you're not using a module loader such as require.js,
|
// Browser globals. If you're not using a module loader such as require.js,
|
||||||
// then this line below executes. Make sure that your plugin's <script> tag
|
// then this line below executes. Make sure that your plugin's <script> tag
|
||||||
|
@ -256,121 +268,130 @@ A full example plugin
|
||||||
moment = converse.env.moment;
|
moment = converse.env.moment;
|
||||||
|
|
||||||
// The following line registers your plugin.
|
// The following line registers your plugin.
|
||||||
converse.plugins.add('myplugin', {
|
converse.plugins.add("<%= name %>", {
|
||||||
|
|
||||||
initialize: function () {
|
/* Optional dependencies are other plugins which might be
|
||||||
// Converse.js's plugin mechanism will call the initialize
|
* overridden or relied upon, and therefore need to be loaded before
|
||||||
// method on any plugin (if it exists) as soon as the plugin has
|
* this plugin. They are called "optional" because they might not be
|
||||||
// been loaded.
|
* available, in which case any overrides applicable to them will be
|
||||||
|
* ignored.
|
||||||
|
*
|
||||||
|
* NB: These plugins need to have already been loaded via require.js.
|
||||||
|
*
|
||||||
|
* It's possible to make optional dependencies non-optional.
|
||||||
|
* If the setting "strict_plugin_dependencies" is set to true,
|
||||||
|
* an error will be raised if the plugin is not found.
|
||||||
|
*/
|
||||||
|
'optional_dependencies': [],
|
||||||
|
|
||||||
|
/* Converse.js's plugin mechanism will call the initialize
|
||||||
|
* method on any plugin (if it exists) as soon as the plugin has
|
||||||
|
* been loaded.
|
||||||
|
*/
|
||||||
|
'initialize': function () {
|
||||||
|
/* Inside this method, you have access to the private
|
||||||
|
* `_converse` object.
|
||||||
|
*/
|
||||||
var _converse = this._converse;
|
var _converse = this._converse;
|
||||||
|
_converse.log("The <%= name %> plugin is being initialized");
|
||||||
|
|
||||||
// Inside this method, you have access to the closured
|
/* From the `_converse` object you can get any configuration
|
||||||
// _converse object, from which you can get any configuration
|
* options that the user might have passed in via
|
||||||
// options that the user might have passed in via
|
* `converse.initialize`. These values are stored in the
|
||||||
// converse.initialize. These values are stored in the
|
* "user_settings" attribute.
|
||||||
// "user_settings" attribute.
|
*
|
||||||
|
* You can also specify new configuration settings for this
|
||||||
// We can also specify new configuration settings for this
|
* plugin, or override the default values of existing
|
||||||
// plugin, or override the default values of existing
|
* configuration settings. This is done like so:
|
||||||
// configuration settings. This is done like so:
|
*/
|
||||||
|
|
||||||
_converse.api.settings.update({
|
_converse.api.settings.update({
|
||||||
'initialize_message': 'Initialized', // New configuration setting
|
'initialize_message': 'Initializing <%= name %>!'
|
||||||
'auto_subscribe': true, // New default value for an
|
|
||||||
// existing "core" configuration setting
|
|
||||||
});
|
});
|
||||||
|
|
||||||
// The user can then pass in values for the configuration
|
/* The user can then pass in values for the configuration
|
||||||
// settings when `converse.initialize` gets called.
|
* settings when `converse.initialize` gets called.
|
||||||
// For example:
|
* For example:
|
||||||
//
|
*
|
||||||
// converse.initialize({
|
* converse.initialize({
|
||||||
// "initialize_message": "My plugin has been initialized"
|
* "initialize_message": "My plugin has been initialized"
|
||||||
// });
|
* });
|
||||||
//
|
*
|
||||||
// And the configuration setting is then available via the
|
* And the configuration setting is then available via the
|
||||||
// `user_settings` attribute:
|
* `user_settings` attribute:
|
||||||
|
*/
|
||||||
|
alert(this._converse.user_settings.initialize_message);
|
||||||
|
|
||||||
// alert(this._converse.user_settings.initialize_message);
|
/* Besides `_converse.api.settings.update`, there is also a
|
||||||
|
* `_converse.api.promises.add` method, which allows you to
|
||||||
// Besides `_converse.api.settings.update`, there is also a
|
* add new promises that your plugin is obligated to fulfill.
|
||||||
// `_converse.api.promises.add` method, which allows you to
|
*
|
||||||
// add new promises that your plugin is obligated to fulfill.
|
* This method takes a string or a list of strings which
|
||||||
|
* represent the promise names:
|
||||||
// This method takes a string or a list of strings which
|
*
|
||||||
// represent the promise names.
|
* _converse.api.promises.add('myPromise');
|
||||||
|
*
|
||||||
_converse.api.promises.add('operationCompleted');
|
* Your plugin should then, when appropriate, resolve the
|
||||||
|
* promise by calling `_converse.api.emit`, which will also
|
||||||
// Your plugin should then, when appropriate, resolve the
|
* emit an event with the same name as the promise.
|
||||||
// promise by calling `_converse.api.emit`, which will also
|
* For example:
|
||||||
// emit an event with the same name as the promise.
|
*
|
||||||
// For example:
|
* _converse.api.emit('operationCompleted');
|
||||||
// _converse.api.emit('operationCompleted');
|
*
|
||||||
//
|
* Other plugins can then either listen for the event
|
||||||
// Other plugins can then either listen for the event
|
* `operationCompleted` like so:
|
||||||
// `operationCompleted` like so:
|
*
|
||||||
// `_converse.api.listen.on('operationCompleted', function { ... });`
|
* _converse.api.listen.on('operationCompleted', function { ... });
|
||||||
//
|
*
|
||||||
// or they can wait for the promise to be fulfilled like so:
|
* or they can wait for the promise to be fulfilled like so:
|
||||||
// `_converse.api.waitUntil('operationCompleted', function { ... });`
|
*
|
||||||
|
* _converse.api.waitUntil('operationCompleted', function { ... });
|
||||||
|
*/
|
||||||
},
|
},
|
||||||
|
|
||||||
// Optional dependencies are other plugins which might be
|
/* If you want to override some function or a Backbone model or
|
||||||
// overridden or relied upon, and therefore need to be loaded before
|
* view defined elsewhere in converse.js, then you do that under
|
||||||
// this plugin. They are called "optional" because they might not be
|
* the "overrides" namespace.
|
||||||
// available, in which case any overrides applicable to them will be
|
*/
|
||||||
// ignored.
|
'overrides': {
|
||||||
|
/* For example, the private *_converse* object has a
|
||||||
// It's possible however to make optional dependencies non-optional.
|
* method "onConnected". You can override that method as follows:
|
||||||
// If the setting "strict_plugin_dependencies" is set to true,
|
*/
|
||||||
// an error will be raised if the plugin is not found.
|
'onConnected': function () {
|
||||||
//
|
|
||||||
// NB: These plugins need to have already been loaded via require.js.
|
|
||||||
|
|
||||||
optional_dependencies: [],
|
|
||||||
|
|
||||||
overrides: {
|
|
||||||
// If you want to override some function or a Backbone model or
|
|
||||||
// view defined elsewhere in converse.js, then you do that under
|
|
||||||
// this "overrides" namespace.
|
|
||||||
|
|
||||||
// For example, the inner protected *_converse* object has a
|
|
||||||
// method "onConnected". You can override that method as follows:
|
|
||||||
onConnected: function () {
|
|
||||||
// Overrides the onConnected method in converse.js
|
// Overrides the onConnected method in converse.js
|
||||||
|
|
||||||
// Top-level functions in "overrides" are bound to the
|
// Top-level functions in "overrides" are bound to the
|
||||||
// inner "_converse" object.
|
// inner "_converse" object.
|
||||||
var _converse = this;
|
var _converse = this;
|
||||||
|
|
||||||
// Your custom code comes here.
|
// Your custom code can come here ...
|
||||||
// ...
|
|
||||||
|
|
||||||
// You can access the original function being overridden
|
// You can access the original function being overridden
|
||||||
// via the __super__ attribute.
|
// via the __super__ attribute.
|
||||||
// Make sure to pass on the arguments supplied to this
|
// Make sure to pass on the arguments supplied to this
|
||||||
// function and also to apply the proper "this" object.
|
// function and also to apply the proper "this" object.
|
||||||
_converse.__super__.onConnected.apply(this, arguments);
|
_converse.__super__.onConnected.apply(this, arguments);
|
||||||
|
|
||||||
|
// Your custom code can come here ...
|
||||||
},
|
},
|
||||||
|
|
||||||
XMPPStatus: {
|
/* Override converse.js's XMPPStatus Backbone model so that we can override the
|
||||||
// Override converse.js's XMPPStatus Backbone model so that we can override the
|
* function that sends out the presence stanza.
|
||||||
// function that sends out the presence stanza.
|
*/
|
||||||
sendPresence: function (type, status_message, jid) {
|
'XMPPStatus': {
|
||||||
|
'sendPresence': function (type, status_message, jid) {
|
||||||
// The "_converse" object is available via the __super__
|
// The "_converse" object is available via the __super__
|
||||||
// attribute.
|
// attribute.
|
||||||
var _converse = this.__super__._converse;
|
var _converse = this.__super__._converse;
|
||||||
|
|
||||||
// Custom code can come here
|
// Custom code can come here ...
|
||||||
// ...
|
|
||||||
|
|
||||||
// You can call the original overridden method, by
|
// You can call the original overridden method, by
|
||||||
// accessing it via the __super__ attribute.
|
// accessing it via the __super__ attribute.
|
||||||
// When calling it, you need to apply the proper
|
// When calling it, you need to apply the proper
|
||||||
// context as reference by the "this" variable.
|
// context as reference by the "this" variable.
|
||||||
this.__super__.sendPresence.apply(this, arguments);
|
this.__super__.sendPresence.apply(this, arguments);
|
||||||
|
|
||||||
|
// Custom code can come here ...
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
Loading…
Reference in New Issue
Block a user