.. raw:: html
.. _`writing-a-plugin`:
Writing a converse.js 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 grok 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', {
// Your plugin code goes in here
});
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.
We 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.
An example plugin
-----------------
.. code-block:: javascript
(function (root, factory) {
if (typeof define === 'function' && define.amd) {
// AMD. Register as a module called "myplugin"
define("myplugin", ["converse"], factory);
} else {
// 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