diff --git a/docs/source/dependencies.rst b/docs/source/dependencies.rst
deleted file mode 100644
index 3bece906b..000000000
--- a/docs/source/dependencies.rst
+++ /dev/null
@@ -1,124 +0,0 @@
-Developer guidelines
-====================
-
-If you want to work with the non-minified Javascript and CSS files you'll soon
-notice that there are references to missing *components* and *node_modules* directories.
-Please follow the instructions below to create these directories and fetch Converse's
-3rd-party dependencies.
-
-.. note::
- Windows environment: We recommend installing the required tools using `Chocolatey `_
- You will need Node.js (nodejs.install), Git (git.install) and optionally to build using Makefile, GNU Make (make)
- If you have trouble setting up a development environment on Windows,
- please read `this post `_
- in the mailing list.:
-
-Installing the development and front-end dependencies
------------------------------------------------------
-
-We use development tools (`Grunt `_ and `Bower `_)
-which depend on Node.js and npm (the Node package manager).
-
-If you don't have Node.js installed, you can download and install the latest
-version `here `_.
-
-Also make sure you have ``Git`` installed. `Details `_.
-
-.. note::
- Windows users should use Chocolatey as recommended above.
-
-.. note::
- Debian & Ubuntu users : apt-get install git npm nodejs-legacy
-
-Once you have *Node.js* and *git* installed, run the following command inside the Converse.js
-directory:
-
-::
-
- make dev
-
-On Windows you need to specify Makefile.win to be used by running: ::
-
- make -f Makefile.win dev
-
-Or alternatively, if you don't have GNU Make:
-
-::
-
- npm install
- bower update
-
-This will first install the Node.js development tools (like Grunt and Bower)
-as well as Converse.js's front-end dependencies.
-
-The front-end dependencies are those javascript files on which
-Converse.js directly depends and which will be loaded in the browser.
-
-To see the dependencies, take a look at whats under the *devDependencies* key in
- `package.json `_.
-
-.. note::
- After running ```make dev```, you should now have new directories *components*
- and *node_modules*, which contain all the front-end dependencies of Converse.js.
- If these directory does NOT exist, something must have gone wrong.
- Double-check the output of ```make dev``` to see if there are any errors
- listed. For support, you can write to the mailing list: conversejs@librelist.com
-
-Loading converse.js and its dependencies
-----------------------------------------
-
-With AMD and require.js (recommended)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Converse.js uses `require.js `_ to asynchronously load dependencies.
-
-If you want to develop or customize converse.js, you'll want to load the
-non-minified javascript files.
-
-Add the following two lines to the ** section of your webpage:
-
-.. code-block:: html
-
-
-
-
-require.js will then let the main.js file be parsed (because of the *data-main*
-attribute on the *script* tag), which will in turn cause converse.js to be
-parsed.
-
-Without AMD and require.js
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Converse.js can also be used without require.js. If you for some reason prefer
-to use it this way, please refer to
-`non_amd.html `_
-for an example of how and in what order all the Javascript files that converse.js
-depends on need to be loaded.
-
-
-Before submitting a pull request
---------------------------------
-
-Please follow the usual github workflow. Create your own local fork of this repository,
-make your changes and then submit a pull request.
-
-Follow the programming style guide
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Please read the `style guide `_ and make sure that your code follows it.
-
-Add tests for your bugfix or feature
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Add a test for any bug fixed or feature added. We use Jasmine
-for testing.
-
-Take a look at `tests.html `_
-and the `spec files `_
-to see how tests are implemented.
-
-Check that the tests pass
-~~~~~~~~~~~~~~~~~~~~~~~~~
-Check that all tests complete sucessfully.
-
-Run ``make check`` in your terminal or open `tests.html `_
-in your browser.
diff --git a/docs/source/developer_api.rst b/docs/source/developer_api.rst
index 2b1beffb0..a6f71ba27 100644
--- a/docs/source/developer_api.rst
+++ b/docs/source/developer_api.rst
@@ -1,7 +1,8 @@
.. raw:: html
-
+
+=============================
The converse.js developer API
=============================
@@ -21,8 +22,8 @@ The converse.js developer API
The Converse.js API is broken up into different logical "groupings" (for
example ``converse.plugins`` or ``converse.contacts``).
-The one exception, is ``converse.initialize``, which is not a grouping, but a
-single method.
+There are some exceptions to this, like ``converse.initialize``, which aren't
+groupings but single methods.
The groupings logically group methods, such as standardised accessors and
mutators::
@@ -34,29 +35,35 @@ mutators::
So for example, to get a contact, you would do the following::
- converse.contacts.get('jid@example.com');
+ _converse.contacts.get('jid@example.com');
To get multiple contacts, just pass in an array of jids::
- converse.contacts.get(['jid1@example.com', 'jid2@example.com']);
+ _converse.contacts.get(['jid1@example.com', 'jid2@example.com']);
To get all contacts, simply call ``get`` without any jids::
- converse.contacts.get();
+ _converse.contacts.get();
-**Here follows now a breakdown of all API groupings and methods**:
+Public API methods
+==================
+Publich API methods are those methods that are accessible on the global
+``window.converse`` object. They are public, because any Javascript in the page
+can call them. Public methods therefore don't expose any sensitive or closured
+data. To do that, you'll need to create a plugin, which has access to the
+private API method.
initialize
----------
.. note:: This method is the one exception of a method which is not logically grouped as explained above.
-Initializes converse.js. This method must always be called when using
-converse.js.
+Publich API method which initializes converse.js.
+This method must always be called when using converse.js.
-The `initialize` method takes a map (also called a hash or dictionary) of :ref:`configuration-variables`.
+The `initialize` method takes a map of :ref:`configuration-variables`.
Example:
@@ -77,6 +84,63 @@ Example:
roster_groups: true
});
+The **plugin** grouping
+------------------------
+
+Exposes methods for adding and removing plugins. You'll need to write a plugin
+if you want to have access to the private API methods defined further down below.
+
+For more information on plugins, read the section :ref:`writing-a-plugin`.
+
+add
+~~~
+
+Registers a new plugin.
+
+.. code-block:: javascript
+
+ var plugin = {
+ initialize: function () {
+ // method on any plugin (if it exists) as soon as the plugin has
+ // been loaded.
+
+ // Inside this method, you have access to the closured
+ // _converse object, which contains the core logic and data
+ // structures of converse.js
+ }
+ }
+ converse.plugins.add('myplugin', plugin);
+
+remove
+~~~~~~
+
+Removes a plugin from the registry.
+
+.. code-block:: javascript
+
+ converse.plugins.remove('myplugin');
+
+
+Private API methods
+===================
+
+The private API methods are only accessible via the closured ``_converse``
+object, which is only available to plugins.
+
+These methods are kept private (i.e. not global) because they may return
+sensitive data which should be kept off-limits to other 3rd-party scripts
+that might be running in the page.
+
+.. note:: The example code snippets shown below are a bit contrived. I've added
+ the minimum plugin boilerplace around the actual example, to show that
+ these API methods can only be called inside a plugin where the
+ ``_converse`` object is available. However, sometimes other considerations
+ need to be made as well. For example, for certain API methods it is
+ necessary to first wait until the data has been received from the XMPP
+ server (or from the browser's sessionStorage cache). Due to
+ time-constriaints these limitations are ignored in the examples below. For
+ a fuller picture, refer to the section :ref:`events-API` as well.
+
send
----
@@ -86,12 +150,18 @@ For example, to send a message stanza:
.. code-block:: javascript
- var msg = converse.env.$msg({
- from: 'juliet@example.com/balcony',
- to:'romeo@example.net',
- type:'chat'
+ converse.plugins.add('myplugin', {
+ initialize: function () {
+
+ var msg = converse.env.$msg({
+ from: 'juliet@example.com/balcony',
+ to:'romeo@example.net',
+ type:'chat'
+ });
+ this._converse.send(msg);
+
+ }
});
- converse.send(msg);
The **archive** grouping
@@ -131,15 +201,21 @@ the returned messages.
.. code-block:: javascript
- var errback = function (iq) {
- // The query was not successful, perhaps inform the user?
- // The IQ stanza returned by the XMPP server is passed in, so that you
- // may inspect it and determine what the problem was.
- }
- var callback = function (messages) {
- // Do something with the messages, like showing them in your webpage.
- }
- converse.archive.query(callback, errback))
+ converse.plugins.add('myplugin', {
+ initialize: function () {
+
+ var errback = function (iq) {
+ // The query was not successful, perhaps inform the user?
+ // The IQ stanza returned by the XMPP server is passed in, so that you
+ // may inspect it and determine what the problem was.
+ }
+ var callback = function (messages) {
+ // Do something with the messages, like showing them in your webpage.
+ }
+ this._converse.archive.query(callback, errback))
+
+ }
+ });
**Waiting until server support has been determined**
@@ -160,9 +236,16 @@ For example:
.. code-block:: javascript
- converse.listen.on('serviceDiscovered', function (feature) {
- if (feature.get('var') === converse.env.Strophe.NS.MAM) {
- converse.archive.query()
+ converse.plugins.add('myplugin', {
+ initialize: function () {
+
+ var _converse = this._converse;
+ _converse.listen.on('serviceDiscovered', function (feature) {
+ if (feature.get('var') === converse.env.Strophe.NS.MAM) {
+ _converse.archive.query()
+ }
+ });
+
}
});
@@ -174,11 +257,18 @@ room under the ``with`` key.
.. code-block:: javascript
- // For a particular user
- converse.archive.query({'with': 'john@doe.net'}, callback, errback);)
- // For a particular room
- converse.archive.query({'with': 'discuss@conference.doglovers.net'}, callback, errback);)
+ converse.plugins.add('myplugin', {
+ initialize: function () {
+
+ // For a particular user
+ this._converse.archive.query({'with': 'john@doe.net'}, callback, errback);)
+
+ // For a particular room
+ this._converse.archive.query({'with': 'discuss@conference.doglovers.net'}, callback, errback);)
+
+ }
+ });
**Requesting all archived messages before or after a certain date**
@@ -189,12 +279,18 @@ formatted date strings, or Javascript Date objects.
.. code-block:: javascript
- var options = {
- 'with': 'john@doe.net',
- 'start': '2010-06-07T00:00:00Z',
- 'end': '2010-07-07T13:23:54Z'
- };
- converse.archive.query(options, callback, errback);
+ converse.plugins.add('myplugin', {
+ initialize: function () {
+
+ var options = {
+ 'with': 'john@doe.net',
+ 'start': '2010-06-07T00:00:00Z',
+ 'end': '2010-07-07T13:23:54Z'
+ };
+ this._converse.archive.query(options, callback, errback);
+
+ }
+ });
**Limiting the amount of messages returned**
@@ -204,9 +300,14 @@ By default, the messages are returned from oldest to newest.
.. code-block:: javascript
- // Return maximum 10 archived messages
- converse.archive.query({'with': 'john@doe.net', 'max':10}, callback, errback);
+ converse.plugins.add('myplugin', {
+ initialize: function () {
+ // Return maximum 10 archived messages
+ this._converse.archive.query({'with': 'john@doe.net', 'max':10}, callback, errback);
+
+ }
+ });
**Paging forwards through a set of archived messages**
@@ -225,14 +326,21 @@ to limit your results.
.. code-block:: javascript
- var callback = function (messages, rsm) {
- // Do something with the messages, like showing them in your webpage.
- // ...
- // You can now use the returned "rsm" object, to fetch the next batch of messages:
- converse.archive.query(rsm.next(10), callback, errback))
+ converse.plugins.add('myplugin', {
+ initialize: function () {
- }
- converse.archive.query({'with': 'john@doe.net', 'max':10}, callback, errback);
+ var _converse = this._converse;
+ var callback = function (messages, rsm) {
+ // Do something with the messages, like showing them in your webpage.
+ // ...
+ // You can now use the returned "rsm" object, to fetch the next batch of messages:
+ _converse.archive.query(rsm.next(10), callback, errback))
+
+ }
+ _converse.archive.query({'with': 'john@doe.net', 'max':10}, callback, errback);
+
+ }
+ });
**Paging backwards through a set of archived messages**
@@ -243,15 +351,22 @@ message, pass in the ``before`` parameter with an empty string value ``''``.
.. code-block:: javascript
- converse.archive.query({'before': '', 'max':5}, function (message, rsm) {
- // Do something with the messages, like showing them in your webpage.
- // ...
- // You can now use the returned "rsm" object, to fetch the previous batch of messages:
- rsm.previous(5); // Call previous method, to update the object's parameters,
- // passing in a limit value of 5.
- // Now we query again, to get the previous batch.
- converse.archive.query(rsm, callback, errback);
- }
+ converse.plugins.add('myplugin', {
+ initialize: function () {
+
+ var _converse = this._converse;
+ _converse.archive.query({'before': '', 'max':5}, function (message, rsm) {
+ // Do something with the messages, like showing them in your webpage.
+ // ...
+ // You can now use the returned "rsm" object, to fetch the previous batch of messages:
+ rsm.previous(5); // Call previous method, to update the object's parameters,
+ // passing in a limit value of 5.
+ // Now we query again, to get the previous batch.
+ _converse.archive.query(rsm, callback, errback);
+ }
+
+ }
+ });
The **connection** grouping
---------------------------
@@ -282,8 +397,13 @@ Return's the current user's full JID (Jabber ID).
.. code-block:: javascript
- converse.user.jid()
- // Returns for example jc@opkode.com/conversejs-351236
+ converse.plugins.add('myplugin', {
+ initialize: function () {
+
+ alert(this._converse.user.jid());
+
+ }
+ });
login
~~~~~
@@ -292,9 +412,15 @@ Logs the user in. This method can accept a map with the credentials, like this:
.. code-block:: javascript
- converse.user.login({
- 'jid': 'dummy@example.com',
- 'password': 'secret'
+ converse.plugins.add('myplugin', {
+ initialize: function () {
+
+ this._converse.user.login({
+ 'jid': 'dummy@example.com',
+ 'password': 'secret'
+ });
+
+ }
});
or it can be called without any parameters, in which case converse.js will try
@@ -308,7 +434,13 @@ Log the user out of the current XMPP session.
.. code-block:: javascript
- converse.user.logout();
+ converse.plugins.add('myplugin', {
+ initialize: function () {
+
+ this._converse.user.logout();
+
+ }
+ });
The **status** sub-grouping
@@ -323,7 +455,13 @@ Return the current user's availability status:
.. code-block:: javascript
- converse.user.status.get(); // Returns for example "dnd"
+ converse.plugins.add('myplugin', {
+ initialize: function () {
+
+ alert(this._converse.user.status.get()); // For example "dnd"
+
+ }
+ });
set
^^^
@@ -341,7 +479,13 @@ For example:
.. code-block:: javascript
- converse.user.status.set('dnd');
+ converse.plugins.add('myplugin', {
+ initialize: function () {
+
+ this._converse.user.status.set('dnd');
+
+ }
+ });
Because the user's availability is often set together with a custom status
message, this method also allows you to pass in a status message as a
@@ -349,7 +493,13 @@ second parameter:
.. code-block:: javascript
- converse.user.status.set('dnd', 'In a meeting');
+ converse.plugins.add('myplugin', {
+ initialize: function () {
+
+ this._converse.user.status.set('dnd', 'In a meeting');
+
+ }
+ });
The **message** sub-grouping
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -359,9 +509,15 @@ retrieving the user's custom status message.
.. code-block:: javascript
- converse.user.status.message.set('In a meeting');
+ converse.plugins.add('myplugin', {
+ initialize: function () {
- converse.user.status.message.get(); // Returns "In a meeting"
+ this._converse.user.status.message.set('In a meeting');
+ // Returns "In a meeting"
+ return this._converse.user.status.message.get();
+
+ }
+ });
The **contacts** grouping
@@ -376,19 +532,48 @@ To get a single roster contact, call the method with the contact's JID (Jabber I
.. code-block:: javascript
- converse.contacts.get('buddy@example.com')
+ converse.plugins.add('myplugin', {
+ initialize: function () {
+
+ var _converse = this._converse;
+ _converse.on('rosterContactsFetched', function () {
+ var contact = _converse.contacts.get('buddy@example.com')
+ });
+
+ }
+ });
To get multiple contacts, pass in an array of JIDs:
.. code-block:: javascript
- converse.contacts.get(['buddy1@example.com', 'buddy2@example.com'])
+ converse.plugins.add('myplugin', {
+ initialize: function () {
+
+ var _converse = this._converse;
+ _converse.on('rosterContactsFetched', function () {
+ var contacts = _converse.contacts.get(
+ ['buddy1@example.com', 'buddy2@example.com']
+ )
+ });
+
+ }
+ });
To return all contacts, simply call ``get`` without any parameters:
.. code-block:: javascript
- converse.contacts.get()
+ converse.plugins.add('myplugin', {
+ initialize: function () {
+
+ var _converse = this._converse;
+ _converse.on('rosterContactsFetched', function () {
+ var contacts = _converse.contacts.get();
+ });
+
+ }
+ });
The returned roster contact objects have these attributes:
@@ -436,13 +621,13 @@ Provide the JID of the contact you want to add:
.. code-block:: javascript
- converse.contacts.add('buddy@example.com')
+ _converse.contacts.add('buddy@example.com')
You may also provide the fullname. If not present, we use the jid as fullname:
.. code-block:: javascript
- converse.contacts.add('buddy@example.com', 'Buddy')
+ _converse.contacts.add('buddy@example.com', 'Buddy')
The **chats** grouping
----------------------
@@ -459,17 +644,17 @@ with in that chat box:
.. code-block:: javascript
- converse.chats.get('buddy@example.com')
+ _converse.chats.get('buddy@example.com')
To return an array of chat boxes, provide an array of JIDs:
.. code-block:: javascript
- converse.chats.get(['buddy1@example.com', 'buddy2@example.com'])
+ _converse.chats.get(['buddy1@example.com', 'buddy2@example.com'])
To return all open chat boxes, call the method without any JIDs::
- converse.chats.get()
+ _converse.chats.get()
open
~~~~
@@ -480,13 +665,25 @@ To open a single chat box, provide the JID of the contact:
.. code-block:: javascript
- converse.chats.open('buddy@example.com')
+ converse.plugins.add('myplugin', {
+ initialize: function () {
+
+ this._converse.chats.open('buddy@example.com')
+
+ }
+ });
To return an array of chat boxes, provide an array of JIDs:
.. code-block:: javascript
- converse.chats.open(['buddy1@example.com', 'buddy2@example.com'])
+ converse.plugins.add('myplugin', {
+ initialize: function () {
+
+ this._converse.chats.open(['buddy1@example.com', 'buddy2@example.com'])
+
+ }
+ });
*The returned chat box object contains the following methods:*
@@ -541,9 +738,20 @@ It takes 3 parameters:
.. code-block:: javascript
- var nick = 'dread-pirate-roberts';
- var create_if_not_found = true;
- converse.rooms.open('group@muc.example.com', {'nick': nick}, create_if_not_found)
+ converse.plugins.add('myplugin', {
+ initialize: function () {
+
+ var nick = 'dread-pirate-roberts';
+ var create_if_not_found = true;
+ this._converse.rooms.open(
+ 'group@muc.example.com',
+ {'nick': nick},
+ create_if_not_found
+ )
+
+ }
+ });
+
open
~~~~
@@ -561,19 +769,37 @@ To open a single multi user chat box, provide the JID of the room:
.. code-block:: javascript
- converse.rooms.open('group@muc.example.com')
+ converse.plugins.add('myplugin', {
+ initialize: function () {
+
+ this._converse.rooms.open('group@muc.example.com')
+
+ }
+ });
To return an array of rooms, provide an array of room JIDs:
.. code-block:: javascript
- converse.rooms.open(['group1@muc.example.com', 'group2@muc.example.com'])
+ converse.plugins.add('myplugin', {
+ initialize: function () {
+
+ this._converse.rooms.open(['group1@muc.example.com', 'group2@muc.example.com'])
+
+ }
+ });
To setup a custom nickname when joining the room, provide the optional nick argument:
.. code-block:: javascript
- converse.rooms.open('group@muc.example.com', {'nick': 'mycustomnick'})
+ converse.plugins.add('myplugin', {
+ initialize: function () {
+
+ this._converse.rooms.open('group@muc.example.com', {'nick': 'mycustomnick'})
+
+ }
+ });
Room attributes that may be passed in:
@@ -594,21 +820,28 @@ For example, opening a room with a specific default configuration:
.. code-block:: javascript
- converse.rooms.open(
- 'myroom@conference.example.org',
- { 'nick': 'coolguy69',
- 'auto_configure': true,
- 'roomconfig': {
- 'changesubject': false,
- 'membersonly': true,
- 'persistentroom': true,
- 'publicroom': true,
- 'roomdesc': 'Comfy room for hanging out',
- 'whois': 'anyone'
- }
- },
- true
- );
+ converse.plugins.add('myplugin', {
+ initialize: function () {
+
+ this._converse.rooms.open(
+ 'myroom@conference.example.org',
+ { 'nick': 'coolguy69',
+ 'auto_configure': true,
+ 'roomconfig': {
+ 'changesubject': false,
+ 'membersonly': true,
+ 'persistentroom': true,
+ 'publicroom': true,
+ 'roomdesc': 'Comfy room for hanging out',
+ 'whois': 'anyone'
+ }
+ },
+ true
+ );
+
+ }
+ });
+
.. note:: `multi-list` configuration values are not yet supported.
@@ -631,7 +864,14 @@ Returns the value of a configuration settings. For example:
.. code-block:: javascript
- converse.settings.get("play_sounds"); // default value returned would be false;
+ converse.plugins.add('myplugin', {
+ initialize: function () {
+
+ // default value would be false;
+ alert(this._converse.settings.get("play_sounds"));
+
+ }
+ });
set(key, value) or set(object)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -640,15 +880,27 @@ Set one or many configuration settings. For example:
.. code-block:: javascript
- converse.settings.set("play_sounds", true);
+ converse.plugins.add('myplugin', {
+ initialize: function () {
+
+ this._converse.settings.set("play_sounds", true);
+
+ }
+ });
or :
.. code-block:: javascript
- converse.settings.set({
- "play_sounds", true,
- "hide_offline_users" true
+ converse.plugins.add('myplugin', {
+ initialize: function () {
+
+ this._converse.settings.set({
+ "play_sounds", true,
+ "hide_offline_users" true
+ });
+
+ }
});
Note, this is not an alternative to calling ``converse.initialize``, which still needs
@@ -667,7 +919,13 @@ Example:
.. code-block:: javascript
- converse.tokens.get('rid')
+ converse.plugins.add('myplugin', {
+ initialize: function () {
+
+ alert(this._converse.tokens.get('rid'));
+
+ }
+ });
.. _`listen-grouping`:
@@ -696,7 +954,7 @@ grouping:
.. code-block:: javascript
- converse.listen.on('message', function (messageXML) { ... });
+ _converse.listen.on('message', function (messageXML) { ... });
* **once(eventName, callback, [context])**:
@@ -713,7 +971,7 @@ grouping:
.. code-block:: javascript
- converse.listen.once('message', function (messageXML) { ... });
+ _converse.listen.once('message', function (messageXML) { ... });
* **not(eventName, callback)**
@@ -728,5 +986,5 @@ grouping:
.. code-block:: javascript
- converse.listen.not('message', function (messageXML) { ... });
+ _converse.listen.not('message', function (messageXML) { ... });
diff --git a/docs/source/events.rst b/docs/source/events.rst
index a43d1ef07..1d211960f 100644
--- a/docs/source/events.rst
+++ b/docs/source/events.rst
@@ -2,6 +2,8 @@
+.. _`writing-a-plugin`:
+
Writing a converse.js plugin
============================
@@ -36,17 +38,18 @@ 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.
+a sensitive inner object, named ``_converse`` (not the underscore prefix).
-This inner object contains all the Backbone models and views, as well as
-various other attributes and functions.
+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
-hiding of this inner object is due to the fact that it contains sensitive information,
-such as the user's JID and password (if they logged in manually). You should
-therefore make sure NOT to expose this object globally.
+``_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
-----------------
@@ -63,70 +66,57 @@ An example plugin
// appears after the one from converse.js.
factory(converse);
}
- }(this, function (converse_api) {
+ }(this, function (converse) {
// Commonly used utilities and variables can be found under the "env"
- // namespace of converse_api
-
- // Strophe methods for building stanzas
- var Strophe = converse_api.env.Strophe,
- $iq = converse_api.env.$iq,
- $msg = converse_api.env.$msg,
- $pres = converse_api.env.$pres,
- $build = converse_api.env.$build,
- b64_sha1 = converse_api.env.b64_sha1;
-
- // Other frequently used utilities
- var $ = converse_api.env.jQuery,
- _ = converse_api.env._,
- moment = converse_api.env.moment;
-
+ // namespace of the "converse" global.
+ var Strophe = converse.env.Strophe,
+ $iq = converse.env.$iq,
+ $msg = converse.env.$msg,
+ $pres = converse.env.$pres,
+ $build = converse.env.$build,
+ b64_sha1 = converse.env.b64_sha1;
+ $ = converse.env.jQuery,
+ _ = converse.env._,
+ moment = converse.env.moment;
// The following line registers your plugin.
- converse_api.plugins.add('myplugin', {
+ converse.plugins.add('myplugin', {
initialize: function () {
// Converse.js's plugin mechanism will call the initialize
// method on any plugin (if it exists) as soon as the plugin has
// been loaded.
- // Inside this method, you have access to the protected "inner"
- // converse object, from which you can get any configuration
+ // Inside this method, you have access to the closured
+ // _converse object, from which you can get any configuration
// options that the user might have passed in via
// converse.initialize. These values are stored in the
// "user_settings" attribute.
- // Let's assume the user might in a custom setting, like so:
+ // Let's assume the user might pass in a custom setting, like so:
+ //
// converse.initialize({
// "initialize_message": "My plugin has been initialized"
// });
//
// Then we can alert that message, like so:
- alert(this.converse.user_settings.initialize_message);
- },
-
- myFunction: function () {
- // This is a function which does not override anything in
- // converse.js itself, but in which you still have access to
- // the protected "inner" converse object.
- var converse = this.converse;
- // Custom code comes here
- // ...
+ alert(this._converse.user_settings.initialize_message);
},
overrides: {
// If you want to override some function or a Backbone model or
- // view defined inside converse, then you do that under this
- // "overrides" namespace.
+ // view defined elsewhere in converse.js, then you do that under
+ // this "overrides" namespace.
- // For example, the inner protected *converse* object has a
+ // 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
// Top-level functions in "overrides" are bound to the
- // inner "converse" object.
- var converse = this;
+ // inner "_converse" object.
+ var _converse = this;
// Your custom code comes here.
// ...
@@ -135,16 +125,16 @@ An example plugin
// via the __super__ attribute.
// Make sure to pass on the arguments supplied to this
// function and also to apply the proper "this" object.
- this.__super__.onConnected.apply(this, arguments);
+ _converse.__super__.onConnected.apply(this, arguments);
},
XMPPStatus: {
// Override converse.js's XMPPStatus Backbone model so that we can override the
// function that sends out the presence stanza.
sendPresence: function (type, status_message, jid) {
- // The "converse" object is available via the __super__
+ // The "_converse" object is available via the __super__
// attribute.
- var converse = this.__super__.converse;
+ var _converse = this.__super__.converse;
// Custom code can come here
// ...
@@ -155,7 +145,7 @@ An example plugin
// context as reference by the "this" variable.
this.__super__.sendPresence.apply(this, arguments);
}
- },
+ }
}
});
}));