.. raw:: html
.. _`writing-a-plugin`:
Writing a plugin
================
.. contents:: Table of Contents
:depth: 2
:local:
Introduction
------------
Developers are able to extend and override the objects, functions and the
Backbone models and views that make up converse.js by means of writing plugins.
Converse.js uses `pluggable.js `_ as
its plugin architecture.
To 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
`_.
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
},
});
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
-----------------
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 `