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 @@ +.. _`events-API`: + Events emitted by converse.js ============================= diff --git a/docs/source/plugin_development.rst b/docs/source/plugin_development.rst index dbca58926..1930e9709 100644 --- a/docs/source/plugin_development.rst +++ b/docs/source/plugin_development.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); } - }, + } } }); }));