Skip to content

C
converse.js
Commit 1050650c authored by JC Brand's avatar JC Brand
Browse files
Options

Update documentation

parent 1125940e
Hide whitespace changes
Inline Side-by-side
Showing with 403 additions and 277 deletions
docs/source/configuration.rst
View file @ 1050650c
...@@ -995,7 +995,7 @@ This allows plugins to have "soft" dependencies which aren't declared as ...@@ -995,7 +995,7 @@ This allows plugins to have "soft" dependencies which aren't declared as
as dependencies. as dependencies.
synchronize_availability synchronize_availability
-------------------- ------------------------
* Default: ``true`` * Default: ``true``
......
docs/source/dependencies.rst deleted 100644 → 0
View file @ 1125940e
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 <https://chocolatey.org/>`_
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 <http://librelist.com/browser//conversejs/2014/11/5/openfire-converse-and-visual-studio-questions/#b28387e7f8f126693b11598a8acbe810>`_
in the mailing list.:
Installing the development and front-end dependencies
-----------------------------------------------------
We use development tools (`Grunt <http://gruntjs.com>`_ and `Bower <http://bower.io>`_)
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 <https://nodejs.org/download>`_.
Also make sure you have ``Git`` installed. `Details <http://git-scm.com/book/en/Getting-Started-Installing-Git>`_.
.. 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 <https://github.com/jcbrand/converse.js/blob/master/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 <http://requirejs.org>`_ 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 *<head>* section of your webpage:
.. code-block:: html
<link rel="stylesheet" type="text/css" media="screen" href="converse.css">
<script data-main="main" src="components/requirejs/require.js"></script>
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 <https://github.com/jcbrand/converse.js/blob/master/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 </docs/html/style_guide.html>`_ 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 <https://github.com/jcbrand/converse.js/blob/master/tests.html>`_
and the `spec files <https://github.com/jcbrand/converse.js/blob/master/tests.html>`_
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 <https://github.com/jcbrand/converse.js/blob/master/tests.html>`_
in your browser.
docs/source/developer_api.rst
View file @ 1050650c
.. raw:: html .. 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> <div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/theming.rst">Edit me on GitHub</a></div>
=============================
The converse.js developer API The converse.js developer API
============================= =============================
...@@ -21,8 +22,8 @@ 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 The Converse.js API is broken up into different logical "groupings" (for
example ``converse.plugins`` or ``converse.contacts``). example ``converse.plugins`` or ``converse.contacts``).
The one exception, is ``converse.initialize``, which is not a grouping, but a There are some exceptions to this, like ``converse.initialize``, which aren't
single method. groupings but single methods.
The groupings logically group methods, such as standardised accessors and The groupings logically group methods, such as standardised accessors and
mutators:: mutators::
...@@ -34,29 +35,35 @@ mutators:: ...@@ -34,29 +35,35 @@ mutators::
So for example, to get a contact, you would do the following:: 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:: 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:: 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 initialize
---------- ----------
.. note:: This method is the one exception of a method which is not logically grouped as explained above. .. 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 Publich API method which initializes converse.js.
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: Example:
...@@ -77,6 +84,63 @@ Example: ...@@ -77,6 +84,63 @@ Example:
roster_groups: true 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 send
---- ----
...@@ -86,12 +150,18 @@ For example, to send a message stanza: ...@@ -86,12 +150,18 @@ For example, to send a message stanza:
.. code-block:: javascript .. code-block:: javascript
var msg = converse.env.$msg({ converse.plugins.add('myplugin', {
from: 'juliet@example.com/balcony', initialize: function () {
to:'romeo@example.net',
type:'chat' 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 The **archive** grouping
...@@ -131,15 +201,21 @@ the returned messages. ...@@ -131,15 +201,21 @@ the returned messages.
.. code-block:: javascript .. code-block:: javascript
var errback = function (iq) { converse.plugins.add('myplugin', {
// The query was not successful, perhaps inform the user? initialize: function () {
// The IQ stanza returned by the XMPP server is passed in, so that you
// may inspect it and determine what the problem was. var errback = function (iq) {
} // The query was not successful, perhaps inform the user?
var callback = function (messages) { // The IQ stanza returned by the XMPP server is passed in, so that you
// Do something with the messages, like showing them in your webpage. // may inspect it and determine what the problem was.
} }
converse.archive.query(callback, errback)) 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** **Waiting until server support has been determined**
...@@ -160,9 +236,16 @@ For example: ...@@ -160,9 +236,16 @@ For example:
.. code-block:: javascript .. code-block:: javascript
converse.listen.on('serviceDiscovered', function (feature) { converse.plugins.add('myplugin', {
if (feature.get('var') === converse.env.Strophe.NS.MAM) { initialize: function () {
converse.archive.query()
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. ...@@ -174,11 +257,18 @@ room under the ``with`` key.
.. code-block:: javascript .. code-block:: javascript
// For a particular user
converse.archive.query({'with': 'john@doe.net'}, callback, errback);)
// For a particular room converse.plugins.add('myplugin', {
converse.archive.query({'with': 'discuss@conference.doglovers.net'}, callback, errback);) 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** **Requesting all archived messages before or after a certain date**
...@@ -189,12 +279,18 @@ formatted date strings, or Javascript Date objects. ...@@ -189,12 +279,18 @@ formatted date strings, or Javascript Date objects.
.. code-block:: javascript .. code-block:: javascript
var options = { converse.plugins.add('myplugin', {
'with': 'john@doe.net', initialize: function () {
'start': '2010-06-07T00:00:00Z',
'end': '2010-07-07T13:23:54Z' var options = {
}; 'with': 'john@doe.net',
converse.archive.query(options, callback, errback); '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** **Limiting the amount of messages returned**
...@@ -204,9 +300,14 @@ By default, the messages are returned from oldest to newest. ...@@ -204,9 +300,14 @@ By default, the messages are returned from oldest to newest.
.. code-block:: javascript .. code-block:: javascript
// Return maximum 10 archived messages converse.plugins.add('myplugin', {
converse.archive.query({'with': 'john@doe.net', 'max':10}, callback, errback); 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** **Paging forwards through a set of archived messages**
...@@ -225,14 +326,21 @@ to limit your results. ...@@ -225,14 +326,21 @@ to limit your results.
.. code-block:: javascript .. code-block:: javascript
var callback = function (messages, rsm) { converse.plugins.add('myplugin', {
// Do something with the messages, like showing them in your webpage. initialize: function () {
// ...
// You can now use the returned "rsm" object, to fetch the next batch of messages:
converse.archive.query(rsm.next(10), callback, errback))
} var _converse = this._converse;
converse.archive.query({'with': 'john@doe.net', 'max':10}, callback, errback); 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** **Paging backwards through a set of archived messages**
...@@ -243,15 +351,22 @@ message, pass in the ``before`` parameter with an empty string value ``''``. ...@@ -243,15 +351,22 @@ message, pass in the ``before`` parameter with an empty string value ``''``.
.. code-block:: javascript .. code-block:: javascript
converse.archive.query({'before': '', 'max':5}, function (message, rsm) { converse.plugins.add('myplugin', {
// Do something with the messages, like showing them in your webpage. initialize: function () {
// ...
// You can now use the returned "rsm" object, to fetch the previous batch of messages: var _converse = this._converse;
rsm.previous(5); // Call previous method, to update the object's parameters, _converse.archive.query({'before': '', 'max':5}, function (message, rsm) {
// passing in a limit value of 5. // Do something with the messages, like showing them in your webpage.
// Now we query again, to get the previous batch. // ...
converse.archive.query(rsm, callback, errback); // 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 The **connection** grouping
--------------------------- ---------------------------
...@@ -282,8 +397,13 @@ Return's the current user's full JID (Jabber ID). ...@@ -282,8 +397,13 @@ Return's the current user's full JID (Jabber ID).
.. code-block:: javascript .. code-block:: javascript
converse.user.jid() converse.plugins.add('myplugin', {
// Returns for example jc@opkode.com/conversejs-351236 initialize: function () {
alert(this._converse.user.jid());
}
});
login login
~~~~~ ~~~~~
...@@ -292,9 +412,15 @@ Logs the user in. This method can accept a map with the credentials, like this: ...@@ -292,9 +412,15 @@ Logs the user in. This method can accept a map with the credentials, like this:
.. code-block:: javascript .. code-block:: javascript
converse.user.login({ converse.plugins.add('myplugin', {
'jid': 'dummy@example.com', initialize: function () {
'password': 'secret'
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 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. ...@@ -308,7 +434,13 @@ Log the user out of the current XMPP session.
.. code-block:: javascript .. code-block:: javascript
converse.user.logout(); converse.plugins.add('myplugin', {
initialize: function () {
this._converse.user.logout();
}
});
The **status** sub-grouping The **status** sub-grouping
...@@ -323,7 +455,13 @@ Return the current user's availability status: ...@@ -323,7 +455,13 @@ Return the current user's availability status:
.. code-block:: javascript .. 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 set
^^^ ^^^
...@@ -341,7 +479,13 @@ For example: ...@@ -341,7 +479,13 @@ For example:
.. code-block:: javascript .. 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 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 message, this method also allows you to pass in a status message as a
...@@ -349,7 +493,13 @@ second parameter: ...@@ -349,7 +493,13 @@ second parameter:
.. code-block:: javascript .. 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 The **message** sub-grouping
^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
...@@ -359,9 +509,15 @@ retrieving the user's custom status message. ...@@ -359,9 +509,15 @@ retrieving the user's custom status message.
.. code-block:: javascript .. code-block:: javascript
converse.user.status.message.set('In a meeting'); converse.plugins.add('myplugin', {
initialize: function () {
this._converse.user.status.message.set('In a meeting');
// Returns "In a meeting"
return this._converse.user.status.message.get();
converse.user.status.message.get(); // Returns "In a meeting" }
});
The **contacts** grouping The **contacts** grouping
...@@ -376,19 +532,48 @@ To get a single roster contact, call the method with the contact's JID (Jabber I ...@@ -376,19 +532,48 @@ To get a single roster contact, call the method with the contact's JID (Jabber I
.. code-block:: javascript .. 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: To get multiple contacts, pass in an array of JIDs:
.. code-block:: javascript .. 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: To return all contacts, simply call ``get`` without any parameters:
.. code-block:: javascript .. 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: The returned roster contact objects have these attributes:
...@@ -436,13 +621,13 @@ Provide the JID of the contact you want to add: ...@@ -436,13 +621,13 @@ Provide the JID of the contact you want to add:
.. code-block:: javascript .. 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: You may also provide the fullname. If not present, we use the jid as fullname:
.. code-block:: javascript .. code-block:: javascript
converse.contacts.add('buddy@example.com', 'Buddy') _converse.contacts.add('buddy@example.com', 'Buddy')
The **chats** grouping The **chats** grouping
---------------------- ----------------------
...@@ -459,17 +644,17 @@ with in that chat box: ...@@ -459,17 +644,17 @@ with in that chat box:
.. code-block:: javascript .. 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: To return an array of chat boxes, provide an array of JIDs:
.. code-block:: javascript .. 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:: To return all open chat boxes, call the method without any JIDs::
converse.chats.get() _converse.chats.get()
open open
~~~~ ~~~~
...@@ -480,13 +665,25 @@ To open a single chat box, provide the JID of the contact: ...@@ -480,13 +665,25 @@ To open a single chat box, provide the JID of the contact:
.. code-block:: javascript .. 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: To return an array of chat boxes, provide an array of JIDs:
.. code-block:: javascript .. 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:* *The returned chat box object contains the following methods:*
...@@ -541,9 +738,20 @@ It takes 3 parameters: ...@@ -541,9 +738,20 @@ It takes 3 parameters:
.. code-block:: javascript .. code-block:: javascript
var nick = 'dread-pirate-roberts'; converse.plugins.add('myplugin', {
var create_if_not_found = true; initialize: function () {
converse.rooms.open('group@muc.example.com', {'nick': nick}, create_if_not_found)
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 open
~~~~ ~~~~
...@@ -561,19 +769,37 @@ To open a single multi user chat box, provide the JID of the room: ...@@ -561,19 +769,37 @@ To open a single multi user chat box, provide the JID of the room:
.. code-block:: javascript .. 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: To return an array of rooms, provide an array of room JIDs:
.. code-block:: javascript .. 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: To setup a custom nickname when joining the room, provide the optional nick argument:
.. code-block:: javascript .. 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: Room attributes that may be passed in:
...@@ -594,21 +820,28 @@ For example, opening a room with a specific default configuration: ...@@ -594,21 +820,28 @@ For example, opening a room with a specific default configuration:
.. code-block:: javascript .. code-block:: javascript
converse.rooms.open( converse.plugins.add('myplugin', {
'myroom@conference.example.org', initialize: function () {
{ 'nick': 'coolguy69',
'auto_configure': true, this._converse.rooms.open(
'roomconfig': { 'myroom@conference.example.org',
'changesubject': false, { 'nick': 'coolguy69',
'membersonly': true, 'auto_configure': true,
'persistentroom': true, 'roomconfig': {
'publicroom': true, 'changesubject': false,
'roomdesc': 'Comfy room for hanging out', 'membersonly': true,
'whois': 'anyone' 'persistentroom': true,
} 'publicroom': true,
}, 'roomdesc': 'Comfy room for hanging out',
true 'whois': 'anyone'
); }
},
true
);
}
});
.. note:: `multi-list` configuration values are not yet supported. .. note:: `multi-list` configuration values are not yet supported.
...@@ -631,7 +864,14 @@ Returns the value of a configuration settings. For example: ...@@ -631,7 +864,14 @@ Returns the value of a configuration settings. For example:
.. code-block:: javascript .. 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) set(key, value) or set(object)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
...@@ -640,15 +880,27 @@ Set one or many configuration settings. For example: ...@@ -640,15 +880,27 @@ Set one or many configuration settings. For example:
.. code-block:: javascript .. code-block:: javascript
converse.settings.set("play_sounds", true); converse.plugins.add('myplugin', {
initialize: function () {
this._converse.settings.set("play_sounds", true);
}
});
or : or :
.. code-block:: javascript .. code-block:: javascript
converse.settings.set({ converse.plugins.add('myplugin', {
"play_sounds", true, initialize: function () {
"hide_offline_users" true
this._converse.settings.set({
"play_sounds", true,
"hide_offline_users" true
});
}
}); });
Note, this is not an alternative to calling ``converse.initialize``, which still needs Note, this is not an alternative to calling ``converse.initialize``, which still needs
...@@ -667,7 +919,13 @@ Example: ...@@ -667,7 +919,13 @@ Example:
.. code-block:: javascript .. code-block:: javascript
converse.tokens.get('rid') converse.plugins.add('myplugin', {
initialize: function () {
alert(this._converse.tokens.get('rid'));
}
});
.. _`listen-grouping`: .. _`listen-grouping`:
...@@ -696,7 +954,7 @@ grouping: ...@@ -696,7 +954,7 @@ grouping:
.. code-block:: javascript .. code-block:: javascript
converse.listen.on('message', function (messageXML) { ... }); _converse.listen.on('message', function (messageXML) { ... });
* **once(eventName, callback, [context])**: * **once(eventName, callback, [context])**:
...@@ -713,7 +971,7 @@ grouping: ...@@ -713,7 +971,7 @@ grouping:
.. code-block:: javascript .. code-block:: javascript
converse.listen.once('message', function (messageXML) { ... }); _converse.listen.once('message', function (messageXML) { ... });
* **not(eventName, callback)** * **not(eventName, callback)**
...@@ -728,5 +986,5 @@ grouping: ...@@ -728,5 +986,5 @@ grouping:
.. code-block:: javascript .. code-block:: javascript
converse.listen.not('message', function (messageXML) { ... }); _converse.listen.not('message', function (messageXML) { ... });
docs/source/events.rst
View file @ 1050650c
...@@ -2,6 +2,8 @@ ...@@ -2,6 +2,8 @@
<div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/theming.rst">Edit me on GitHub</a></div> <div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/theming.rst">Edit me on GitHub</a></div>
.. _`events-API`:
Events emitted by converse.js Events emitted by converse.js
============================= =============================
......
docs/source/plugin_development.rst
View file @ 1050650c
...@@ -2,6 +2,8 @@ ...@@ -2,6 +2,8 @@
<div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/theming.rst">Edit me on GitHub</a></div> <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 converse.js plugin Writing a converse.js plugin
============================ ============================
...@@ -36,17 +38,18 @@ Security and access to the inner workings ...@@ -36,17 +38,18 @@ Security and access to the inner workings
The globally available ``converse`` object, which exposes the API methods, such The globally available ``converse`` object, which exposes the API methods, such
as ``initialize`` and ``plugins.add``, is a wrapper that encloses and protects 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 This inner ``_converse`` object contains all the Backbone models and views,
various other attributes and functions. as well as various other attributes and functions.
Within a plugin, you will have access to this internal Within a plugin, you will have access to this internal
`"closured" <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Closures>`_ `"closured" <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Closures>`_
converse object, which is normally not exposed in the global variable scope. The ``_converse`` object, which is normally not exposed in the global variable scope.
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 We inner ``_converse`` object is made private in order to safely hide and
therefore make sure NOT to expose this object globally. 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 An example plugin
----------------- -----------------
...@@ -63,70 +66,57 @@ An example plugin ...@@ -63,70 +66,57 @@ An example plugin
// appears after the one from converse.js. // appears after the one from converse.js.
factory(converse); factory(converse);
} }
}(this, function (converse_api) { }(this, function (converse) {
// Commonly used utilities and variables can be found under the "env" // Commonly used utilities and variables can be found under the "env"
// namespace of converse_api // namespace of the "converse" global.
var Strophe = converse.env.Strophe,
// Strophe methods for building stanzas $iq = converse.env.$iq,
var Strophe = converse_api.env.Strophe, $msg = converse.env.$msg,
$iq = converse_api.env.$iq, $pres = converse.env.$pres,
$msg = converse_api.env.$msg, $build = converse.env.$build,
$pres = converse_api.env.$pres, b64_sha1 = converse.env.b64_sha1;
$build = converse_api.env.$build, $ = converse.env.jQuery,
b64_sha1 = converse_api.env.b64_sha1; _ = converse.env._,
moment = converse.env.moment;
// Other frequently used utilities
var $ = converse_api.env.jQuery,
_ = converse_api.env._,
moment = converse_api.env.moment;
// The following line registers your plugin. // The following line registers your plugin.
converse_api.plugins.add('myplugin', { converse.plugins.add('myplugin', {
initialize: function () { initialize: function () {
// Converse.js's plugin mechanism will call the initialize // Converse.js's plugin mechanism will call the initialize
// method on any plugin (if it exists) as soon as the plugin has // method on any plugin (if it exists) as soon as the plugin has
// been loaded. // been loaded.
// Inside this method, you have access to the protected "inner" // Inside this method, you have access to the closured
// converse object, from which you can get any configuration // _converse object, from which you can get any configuration
// options that the user might have passed in via // options that the user might have passed in via
// converse.initialize. These values are stored in the // converse.initialize. These values are stored in the
// "user_settings" attribute. // "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({ // converse.initialize({
// "initialize_message": "My plugin has been initialized" // "initialize_message": "My plugin has been initialized"
// }); // });
// //
// Then we can alert that message, like so: // Then we can alert that message, like so:
alert(this.converse.user_settings.initialize_message); 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
// ...
}, },
overrides: { overrides: {
// If you want to override some function or a Backbone model or // If you want to override some function or a Backbone model or
// view defined inside converse, then you do that under this // view defined elsewhere in converse.js, then you do that under
// "overrides" namespace. // 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: // method "onConnected". You can override that method as follows:
onConnected: function () { onConnected: function () {
// Overrides the onConnected method in converse.js // Overrides the onConnected method in converse.js
// Top-level functions in "overrides" are bound to the // Top-level functions in "overrides" are bound to the
// inner "converse" object. // inner "_converse" object.
var converse = this; var _converse = this;
// Your custom code comes here. // Your custom code comes here.
// ... // ...
...@@ -135,16 +125,16 @@ An example plugin ...@@ -135,16 +125,16 @@ An example plugin
// via the __super__ attribute. // via the __super__ attribute.
// Make sure to pass on the arguments supplied to this // Make sure to pass on the arguments supplied to this
// function and also to apply the proper "this" object. // function and also to apply the proper "this" object.
this.__super__.onConnected.apply(this, arguments); _converse.__super__.onConnected.apply(this, arguments);
}, },
XMPPStatus: { XMPPStatus: {
// Override converse.js's XMPPStatus Backbone model so that we can override the // Override converse.js's XMPPStatus Backbone model so that we can override the
// function that sends out the presence stanza. // function that sends out the presence stanza.
sendPresence: function (type, status_message, jid) { sendPresence: function (type, status_message, jid) {
// The "converse" object is available via the __super__ // The "_converse" object is available via the __super__
// attribute. // attribute.
var converse = this.__super__.converse; var _converse = this.__super__.converse;
// Custom code can come here // Custom code can come here
// ... // ...
...@@ -155,7 +145,7 @@ An example plugin ...@@ -155,7 +145,7 @@ An example plugin
// context as reference by the "this" variable. // context as reference by the "this" variable.
this.__super__.sendPresence.apply(this, arguments); this.__super__.sendPresence.apply(this, arguments);
} }
}, }
} }
}); });
})); }));
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7