.. raw:: html
.. _`writing-a-plugin`:
Writing a plugin
================
.. contents:: Table of Contents
:depth: 2
:local:
Introduction
------------
Converse.js is exposes a plugin architecture which allows developers to modify
and extend its functionality.
Specifically, plugins enable developers to extend and override existing objects,
functions and `Backbone `_ 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 `_ and
`Group chats `_ are implemented
as plugins, thereby showing their power and flexibility.
Converse.js uses `pluggable.js `_ as
its plugin architecture.
To more deeply understand how this plugin architecture works, please read the
`pluggable.js documentation `_
and to understand its inner workins, please refer to the `annotated source code
`_.
Playing with a Converse.js plugin in JSFiddle
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Because Converse.js consists only of JavaScript, HTML and CSS (with no backend
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
--------------------
You register a converse.js plugin as follows:
.. 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.js 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``.
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" `_
``_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.
Loading a plugin module
-----------------------
Converse.js uses the UMD (Universal Modules Definition) as its module syntax.
This makes modules loadable via `require.js`, `webpack` or other module
loaders, but also includable as old-school `