578 lines
23 KiB
ReStructuredText
578 lines
23 KiB
ReStructuredText
.. raw:: html
|
|
|
|
<div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/theming.rst">Edit me on GitHub</a></div>
|
|
|
|
.. _`writing-a-plugin`:
|
|
|
|
Writing a plugin
|
|
================
|
|
|
|
Introduction
|
|
------------
|
|
|
|
Converse exposes a plugin architecture through which developers can modify
|
|
and extend its functionality.
|
|
|
|
Using plugins is good engineering practice, and using them is the *only* recommended
|
|
way of changing Converse or adding new features to it.
|
|
|
|
In particular, plugins have the following advantages:
|
|
|
|
The main benefit of plugins is their *isolation of concerns* (and features).
|
|
From this benefit flows various 2nd degree advantages, such as the ability to
|
|
make smaller production builds (by excluding unused plugins) and an easier
|
|
upgrade path by avoiding touching Converse's internals.
|
|
|
|
Each plugin comes in its own file, and Converse's plugin architecture,
|
|
called `pluggable.js <https://github.com/jcbrand/pluggable.js/>`_, provides you
|
|
with the ability to "hook in" to the core code and other plugins.
|
|
|
|
Converse itself is composed out of plugins and uses pluggable.js. Take a look at the
|
|
`src <https://github.com/jcbrand/converse.js/tree/master/src>`_ directory. All
|
|
the files that follow the pattern `converse-*.js` are plugins.
|
|
|
|
Plugins (by way of Pluggable.js) enable developers to extend and override existing objects,
|
|
functions and the `Backbone <http://backbonejs.org/>`_ models and views that make up
|
|
Converse.
|
|
|
|
Besides that, in plugins you can also write new Backbone (or other) models and views,
|
|
in order to add a new functionality.
|
|
|
|
To more deeply understand how this plugin architecture works, please read the
|
|
`pluggable.js documentation <https://jcbrand.github.io/pluggable.js/>`_
|
|
and to understand its inner workings, please refer to the `annotated source code
|
|
<https://jcbrand.github.io/pluggable.js/docs/pluggable.html>`_.
|
|
|
|
.. note:: **Trying out a plugin in JSFiddle**
|
|
|
|
Because Converse consists only of JavaScript, HTML and CSS (with no backend
|
|
code required like PHP, Python or Ruby) it runs fine in JSFiddle.
|
|
|
|
Here's a Fiddle with a Converse plugin that calls ``alert`` once it gets
|
|
initialized and also when a chat message gets rendered: https://jsfiddle.net/4drfaok0/15/
|
|
|
|
|
|
.. note:: **Generating a plugin with Yeoman**
|
|
|
|
The rest of this document explains how to write a plugin for Converse and
|
|
ends with a documented example of a plugin.
|
|
|
|
There is a `Yeoman <http://yeoman.io/>`_ code generator, called
|
|
`generator-conversejs <https://github.com/jcbrand/generator-conversejs>`_, which
|
|
you can use to generate plugin scaffolding/boilerplate that serves as a
|
|
starting point and basis for writing your plugin.
|
|
|
|
Please refer to the `generator-conversejs <https://github.com/jcbrand/generator-conversejs>`_
|
|
README for information on how to use it.
|
|
|
|
Registering a plugin
|
|
--------------------
|
|
|
|
Plugins need to be registered (and whitelisted) before they can be loaded and
|
|
initialized.
|
|
|
|
You register a Converse plugin by calling ``converse.plugins.add``.
|
|
|
|
The plugin itself is a JavaScript object which usually has at least an
|
|
``initialize`` method, which gets called at the end of the
|
|
``converse.initialize`` method which is the top-level method that gets called
|
|
by the website to configure and initialize Converse itself.
|
|
|
|
Here's an example code snippet:
|
|
|
|
.. code-block:: javascript
|
|
|
|
converse.plugins.add('myplugin', {
|
|
|
|
initialize: function () {
|
|
// This method gets called once converse.initialize has been called
|
|
// and the plugin itself has been loaded.
|
|
|
|
// Inside this method, you have access to the closured
|
|
// _converse object as an attribute on "this".
|
|
// E.g. this._converse
|
|
},
|
|
});
|
|
|
|
.. note:: It's important that `converse.plugins.add` is called **before**
|
|
`converse.initialize` is called. Otherwise the plugin will never get
|
|
registered and never get called.
|
|
|
|
Whitelisting of plugins
|
|
-----------------------
|
|
|
|
As of Converse 3.0.0 and higher, plugins need to be whitelisted before they
|
|
can be used. This is because plugins have access to a powerful API. For
|
|
example, they can read all messages and send messages on the user's behalf.
|
|
|
|
To avoid malicious plugins being registered (i.e. by malware infected
|
|
advertising networks) we now require whitelisting.
|
|
|
|
To whitelist a plugin simply means to specify :ref:`whitelisted_plugins` when
|
|
you call ``converse.initialize``.
|
|
|
|
If you're adding a "core" plugin, which means a plugin that will be
|
|
included in the default, open-source version of Converse, then you'll
|
|
instead whitelist the plugin by adding its name to the `core_plugins` array in
|
|
`./src/headless/converse-core.js <https://github.com/jcbrand/converse.js/blob/master/src/headless/converse-core.js>`_.
|
|
or the `WHITELISTED_PLUGINS` array in `./src/converse.js <https://github.com/jcbrand/converse.js/blob/master/src/converse.js>`_.
|
|
|
|
Where you add it depends on whether your plugin is part of the headless build
|
|
(which means it doesn't contain any view code) or not.
|
|
|
|
Security and access to the inner workings
|
|
-----------------------------------------
|
|
|
|
The globally available ``converse`` object, which exposes the API methods, such
|
|
as ``initialize`` and ``plugins.add``, is a wrapper that encloses and protects
|
|
a sensitive inner object, named ``_converse`` (not the underscore prefix).
|
|
|
|
This inner ``_converse`` object contains all the Backbone models and views,
|
|
as well as various other attributes and functions.
|
|
|
|
Within a plugin, you will have access to this internal
|
|
`"closured" <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Closures>`_
|
|
``_converse`` object, which is normally not exposed in the global variable scope.
|
|
|
|
The inner ``_converse`` object is made private in order to safely hide and
|
|
encapsulate sensitive information and methods which should not be exposed
|
|
to any 3rd-party scripts that might be running in the same page.
|
|
|
|
|
|
Accessing 3rd party libraries
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Immediately inside the module shown above you can access 3rd party libraries (such
|
|
dayjs and lodash) via the ``converse.env`` map.
|
|
|
|
The code for it could look something like this:
|
|
|
|
.. code-block:: javascript
|
|
|
|
// Commonly used utilities and variables can be found under the "env"
|
|
// namespace of the "converse" global.
|
|
const { Backbone, Promise, Strophe, dayjs, sizzle, _, $build, $iq, $msg, $pres } = converse.env;
|
|
|
|
These dependencies are closured so that they don't pollute the global
|
|
namespace, that's why you need to access them in such a way inside the module.
|
|
|
|
Overrides
|
|
---------
|
|
|
|
Plugins can override core code or code from other plugins. You can specify
|
|
overrides in the object passed to ``converse.plugins.add``.
|
|
|
|
In an override you can still call the overridden function, by calling
|
|
``this.__super__.methodName.apply(this, arguments);`` where ``methodName`` is
|
|
the name of the function or method you're overriding.
|
|
|
|
The following code snippet provides an example of two different overrides:
|
|
|
|
.. code-block:: javascript
|
|
|
|
overrides: {
|
|
/* The *_converse* object has a method "onConnected".
|
|
* You can override that method as follows:
|
|
*/
|
|
onConnected: function () {
|
|
// Overrides the onConnected method in Converse
|
|
|
|
// Top-level functions in "overrides" are bound to the
|
|
// inner "_converse" object.
|
|
const _converse = this;
|
|
|
|
// Your custom code can come here ...
|
|
|
|
// You can access the original function being overridden
|
|
// via the __super__ attribute.
|
|
// Make sure to pass on the arguments supplied to this
|
|
// function and also to apply the proper "this" object.
|
|
_converse.__super__.onConnected.apply(this, arguments);
|
|
|
|
// Your custom code can come here ...
|
|
},
|
|
|
|
/* On the XMPPStatus Backbone model is a method sendPresence.
|
|
* We can override is as follows:
|
|
*/
|
|
XMPPStatus: {
|
|
sendPresence: function (type, status_message, jid) {
|
|
// The "_converse" object is available via the __super__
|
|
// attribute.
|
|
const _converse = this.__super__._converse;
|
|
|
|
// Custom code can come here ...
|
|
|
|
// You can call the original overridden method, by
|
|
// accessing it via the __super__ attribute.
|
|
// When calling it, you need to apply the proper
|
|
// context as reference by the "this" variable.
|
|
this.__super__.sendPresence.apply(this, arguments);
|
|
}
|
|
}
|
|
}
|
|
|
|
|
|
Use the ``overrides`` feature with caution. It basically resorts to
|
|
monkey patching which pollutes the call stack and can make your code fragile
|
|
and prone to bugs when Converse gets updated. Too much use of ``overrides``
|
|
is therefore a "code smell" which should ideally be avoided.
|
|
|
|
A better approach is to listen to the events emitted by Converse, and to add
|
|
your code in event handlers. This is however not always possible, in which case
|
|
the overrides are a powerful tool.
|
|
|
|
Also, while it's possible to add new methods to classes via the ``overrides``
|
|
feature, it's better and more explicit to use composition with
|
|
``Object.assign``.
|
|
|
|
For example:
|
|
|
|
.. code-block:: javascript
|
|
|
|
function doSomething () {
|
|
// Your code comes here
|
|
}
|
|
Object.assign(_converse.ChatBoxView.prototype, { doSomething });
|
|
|
|
|
|
Overriding a template
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Converse uses various templates, loaded with lodash, to generate its HTML.
|
|
|
|
It's not possible to override a template with the plugin's ``overrides``
|
|
feature, instead you should configure a new path to your own template via your
|
|
module bundler.
|
|
|
|
For example, with Webpack (which Converse uses internall), you can specify an
|
|
``alias`` for the template you want to override. This alias then points to your
|
|
own custom template.
|
|
|
|
For example, in your webpack config file, you could add the following to the
|
|
``config`` object that gets exported:
|
|
|
|
.. code-block:: javascript
|
|
|
|
module: {
|
|
{
|
|
test: /templates\/.*\.(html|svg)$/,
|
|
use: [{
|
|
loader: 'lodash-template-webpack-loader',
|
|
options: {
|
|
escape: /\{\{\{([\s\S]+?)\}\}\}/g,
|
|
evaluate: /\{\[([\s\S]+?)\]\}/g,
|
|
interpolate: /\{\{([\s\S]+?)\}\}/g,
|
|
// By default, template places the values from your data in the
|
|
// local scope via the with statement. However, you can specify
|
|
// a single variable name with the variable setting. This can
|
|
// significantly improve the speed at which a template is able
|
|
// to render.
|
|
variable: 'o',
|
|
prependFilenameComment: __dirname
|
|
}
|
|
}]
|
|
}
|
|
},
|
|
resolve: {
|
|
extensions: ['.js'],
|
|
modules: [
|
|
path.join(__dirname, 'node_modules'),
|
|
path.join(__dirname, 'node_modules/converse.js/src')
|
|
],
|
|
alias: {
|
|
'templates/profile_view.html$': path.resolve(__dirname, 'templates/profile_view.html')
|
|
}
|
|
}
|
|
|
|
|
|
You'll need to install ``lodash-template-webpack-loader``.
|
|
|
|
Currently Converse uses a fork of `lodash-template-webpack-loader <https://github.com/jcbrand/lodash-template-webpack-loader>`_.
|
|
|
|
To install it, you can add ``"lodash-template-webpack-loader": "jcbrand/lodash-template-webpack-loader"``
|
|
to your package.json's ``devDependencies``.
|
|
|
|
|
|
.. _`dependencies`:
|
|
|
|
Plugin dependencies
|
|
-------------------
|
|
|
|
When using ``overrides``, the code that you want to override (which is either
|
|
in ``converse-core`` or in other plugins), needs to be parsed already by the
|
|
time your ``overrides`` are being parsed.
|
|
|
|
Additionally, when you register event or promise handlers in your plugin for
|
|
events/promises that fire in other plugins, then you want those plugins to have
|
|
been loaded before your plugin gets loaded.
|
|
|
|
To resolve this problem we have the ``dependencies`` Array attribute.
|
|
With this you can specify those dependencies which need to be loaded before
|
|
your plugin is loaded.
|
|
|
|
In some cases, you might want to depend on another plugin if it's available,
|
|
but don't care when it's not available.
|
|
An example is the `converse-dragresize <https://github.com/jcbrand/converse.js/blob/master/src/converse-dragresize.js>`_
|
|
plugin, which will add drag-resize handles to the headlines box (which shows
|
|
messages of type ``headline``) but doesn't care when that particular plugin is
|
|
not available.
|
|
|
|
If the :ref:`strict_plugin_dependencies` setting is set to ``false`` (which is
|
|
its default value), then no error will be raised if the plugin is not found.
|
|
|
|
In this case, you can't specify the plugin as a dependency in the ``define``
|
|
statement at the top of the plugin, since it might not always be available,
|
|
which would cause ``require.js`` to throw an error.
|
|
|
|
Extending Converse's configuration settings
|
|
----------------------------------------------
|
|
|
|
Converse comes with various :ref:`configuration-settings` that can be used to
|
|
modify its functionality and behavior.
|
|
|
|
All configuration settings have default values which can be overridden when
|
|
`converse.initialize` (see `converse.initialize </docs/html/api/converse.html#.initialize>`_)
|
|
gets called.
|
|
|
|
Plugins often need their own additional configuration settings and you can add
|
|
these settings with the `_converse.api.settings.update </docs/html/api/-_converse.api.settings.html#.update>`_
|
|
method.
|
|
|
|
Exposing promises
|
|
-----------------
|
|
|
|
Converse has a `waitUntil </docs/html/api/-_converse.api.html#.waitUntil>`_ API method
|
|
which allows you to wait for various promises to resolve before executing a
|
|
piece of code.
|
|
|
|
You can add new promises for your plugin by calling
|
|
`_converse.api.promises.add </docs/html/api/-_converse.api.promises.html#.add>`_.
|
|
|
|
Generally, your plugin will then also be responsible for making sure these
|
|
promises are resolved. You do this by calling
|
|
`_converse.api.trigger </docs/html/api/-_converse.api.html#.trigger>`_, which not
|
|
only resolves the plugin but will also emit an event with the same name.
|
|
|
|
Dealing with asynchronicity
|
|
---------------------------
|
|
|
|
Due to the asynchronous nature of XMPP, many subroutines in Converse execute
|
|
at different times and not necessarily in the same order.
|
|
|
|
In many cases, when you want to execute a piece of code in a plugin, you first
|
|
want to make sure that the supporting data-structures that your code might rely
|
|
on have been created and populated with data.
|
|
|
|
There are two ways of waiting for the right time before executing your code.
|
|
You can either listen for certain events, or you can wait for promises to
|
|
resolve.
|
|
|
|
For example, when you want to query the message archive between you and a
|
|
friend, you would call ``this._converse.api.archive.query({'with': 'friend@example.org'});``
|
|
|
|
However, simply calling this immediately in the ``initialize`` method of your plugin will
|
|
not work, since the user is not logged in yet.
|
|
|
|
In this case, you should first listen for the ``connection`` event, and then do your query, like so:
|
|
|
|
.. code-block:: javascript
|
|
|
|
converse.plugins.add('myplugin', {
|
|
initialize: function () {
|
|
const _converse = this._converse;
|
|
|
|
_converse.api.listen.on('connected', function () {
|
|
_converse.api.archive.query({'with': 'admin2@localhost'});
|
|
});
|
|
}
|
|
});
|
|
|
|
Another example is in the ``Bookmarks`` plugin (in
|
|
`src/converse-bookmarks.js <https://github.com/jcbrand/converse.js/blob/6c3aa34c23d97d679823a64376418cd0f40a8b94/src/converse-bookmarks.js#L528>`_).
|
|
Before bookmarks can be fetched and shown to the user, we first have to wait until
|
|
the `"Rooms"` panel of the ``ControlBox`` has been rendered and inserted into
|
|
the DOM. Otherwise we have no place to show the bookmarks yet.
|
|
|
|
Therefore, there are the following lines of code in the ``initialize`` method of
|
|
`converse-bookmarks.js <https://github.com/jcbrand/converse.js/blob/6c3aa34c23d97d679823a64376418cd0f40a8b94/src/converse-bookmarks.js#L528>`_:
|
|
|
|
.. code-block:: javascript
|
|
|
|
Promise.all([
|
|
_converse.api.waitUntil('chatBoxesFetched'),
|
|
_converse.api.waitUntil('roomsPanelRendered')
|
|
]).then(initBookmarks);
|
|
|
|
What this means, is that the plugin will wait until the ``chatBoxesFetched``
|
|
and ``roomsPanelRendered`` promises have been resolved before it calls the
|
|
``initBookmarks`` method (which is defined inside the plugin).
|
|
|
|
This way, we know that we have everything in place and set up correctly before
|
|
fetching the bookmarks.
|
|
|
|
As yet another example, there is also the following code in the ``initialize``
|
|
method of the plugin:
|
|
|
|
.. code-block:: javascript
|
|
|
|
_converse.api.listen.on('chatBoxOpened', function renderMinimizeButton (view) {
|
|
// Inserts a "minimize" button in the chatview's header
|
|
|
|
// Implementation code removed for brevity
|
|
// ...
|
|
});
|
|
|
|
In this case, the plugin waits for the ``chatBoxOpened`` event, before it then
|
|
calls ``renderMinimizeButton``, which adds a new button to the chatbox (which
|
|
enables you to minimize it).
|
|
|
|
Finding the right promises and/or events to listen to, can be a bit
|
|
challenging, and sometimes it might be necessary to create new events or
|
|
promises.
|
|
|
|
Please refer to the `API documentation </docs/html/api/http://localhost:8008/docs/html/api/>`_
|
|
for an overview of what's available to you. If you need new events or promises, then
|
|
`please open an issue or make a pull request on Github <https://github.com/jcbrand/converse.js>`_
|
|
|
|
A full example plugin
|
|
---------------------
|
|
|
|
Below follows a documented example of a plugin. This is the same code that gets
|
|
generated by `generator-conversejs <https://github.com/jcbrand/generator-conversejs>`_.
|
|
|
|
.. code-block:: javascript
|
|
|
|
import converse from "@converse/headless/converse-core";
|
|
|
|
// Commonly used utilities and variables can be found under the "env"
|
|
// namespace of the "converse" global.
|
|
const { Backbone, Promise, Strophe, dayjs, sizzle, _, $build, $iq, $msg, $pres } = converse.env;
|
|
|
|
// The following line registers your plugin.
|
|
converse.plugins.add("myplugin", {
|
|
|
|
/* Dependencies are other plugins which might be
|
|
* overridden or relied upon, and therefore need to be loaded before
|
|
* this plugin. They are "optional" because they might not be
|
|
* available, in which case any overrides applicable to them will be
|
|
* ignored.
|
|
*
|
|
* NB: These plugins need to have already been imported or loaded,
|
|
* either in your plugin or somewhere else.
|
|
*
|
|
* It's possible to make these dependencies "non-optional".
|
|
* If the setting "strict_plugin_dependencies" is set to true,
|
|
* an error will be raised if the plugin is not found.
|
|
*/
|
|
dependencies: [],
|
|
|
|
/* Converse'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.
|
|
*/
|
|
const _converse = this._converse;
|
|
_converse.log("The \"myplugin\" plugin is being initialized");
|
|
|
|
/* From the `_converse` object you can get any configuration
|
|
* options that the user might have passed in via
|
|
* `converse.initialize`.
|
|
*
|
|
* You can also specify new configuration settings for this
|
|
* plugin, or override the default values of existing
|
|
* configuration settings. This is done like so:
|
|
*/
|
|
_converse.api.settings.update({
|
|
'initialize_message': 'Initializing myplugin!'
|
|
});
|
|
|
|
/* The user can then pass in values for the configuration
|
|
* settings when `converse.initialize` gets called.
|
|
* For example:
|
|
*
|
|
* converse.initialize({
|
|
* "initialize_message": "My plugin has been initialized"
|
|
* });
|
|
*/
|
|
alert(this._converse.initialize_message);
|
|
|
|
/* Besides `_converse.api.settings.update`, there is also a
|
|
* `_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:
|
|
*
|
|
* _converse.api.promises.add('myPromise');
|
|
*
|
|
* Your plugin should then, when appropriate, resolve the
|
|
* promise by calling `_converse.api.emit`, which will also
|
|
* emit an event with the same name as the promise.
|
|
* For example:
|
|
*
|
|
* _converse.api.trigger('operationCompleted');
|
|
*
|
|
* Other plugins can then either listen for the event
|
|
* `operationCompleted` like so:
|
|
*
|
|
* _converse.api.listen.on('operationCompleted', function { ... });
|
|
*
|
|
* or they can wait for the promise to be fulfilled like so:
|
|
*
|
|
* _converse.api.waitUntil('operationCompleted', function { ... });
|
|
*/
|
|
},
|
|
|
|
/* If you want to override some function or a Backbone model or
|
|
* view defined elsewhere in Converse, then you do that under
|
|
* the "overrides" namespace.
|
|
*/
|
|
overrides: {
|
|
/* For example, the private *_converse* object has a
|
|
* method "onConnected". You can override that method as follows:
|
|
*/
|
|
onConnected: function () {
|
|
// Overrides the onConnected method in Converse
|
|
|
|
// Top-level functions in "overrides" are bound to the
|
|
// inner "_converse" object.
|
|
const _converse = this;
|
|
|
|
// Your custom code can come here ...
|
|
|
|
// You can access the original function being overridden
|
|
// via the __super__ attribute.
|
|
// Make sure to pass on the arguments supplied to this
|
|
// function and also to apply the proper "this" object.
|
|
_converse.__super__.onConnected.apply(this, arguments);
|
|
|
|
// Your custom code can come here ...
|
|
},
|
|
|
|
/* Override Converse's XMPPStatus Backbone model so that we can override the
|
|
* function that sends out the presence stanza.
|
|
*/
|
|
XMPPStatus: {
|
|
sendPresence: function (type, status_message, jid) {
|
|
// The "_converse" object is available via the __super__
|
|
// attribute.
|
|
const _converse = this.__super__._converse;
|
|
|
|
// Custom code can come here ...
|
|
|
|
// You can call the original overridden method, by
|
|
// accessing it via the __super__ attribute.
|
|
// When calling it, you need to apply the proper
|
|
// context as reference by the "this" variable.
|
|
this.__super__.sendPresence.apply(this, arguments);
|
|
|
|
// Custom code can come here ...
|
|
}
|
|
}
|
|
}
|
|
});
|