Chapril/xmpp.chapril.org-conversejs
Chapril/xmpp.chapril.org-conversejs
24
0
Fork 0
Code Issues Pull Requests Projects Releases Activity

Update documentation

Browse Source
This commit is contained in:
JC Brand 2016-12-20 09:31:11 +00:00
parent b7b9711296
commit 55dbbede8a
4 changed files with 402 additions and 276 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

124
docs/source/dependencies.rst
View File

@ -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 <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.

470
docs/source/developer_api.rst
View File

@ -1,7 +1,8 @@
.. 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>
=============================
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) { ... });

2
docs/source/events.rst
View File

@ -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>
.. _`events-API`:
Events emitted by converse.js
=============================

82
docs/source/plugin_development.rst
View File

@ -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>
.. _`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" <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Closures>`_
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);
}
},
}
}
});
}));