Update the documentation.

- Fix event listener code examples
- Mention the preferability of using versions in the CDN

docs/source/configuration.rst

@@ -1063,8 +1063,17 @@ loaded), then an error will be raised.
 
 Otherwise a message will simply be logged and the override instruction ignored.
 
-This allows plugins to have "soft" dependencies which aren't declared as
+The Converse.js plugins architecture can have an ``optional_dependencies``
-as dependencies.
+plugin attribute. This enables you to specify an array of optional, or
+"soft", dependencies. Converse.js (more specifically,
+`pluggable.js <https://jcbrand.github.io/pluggable.js/>`_) will try to first
+load the optional dependencies before executing the plugin's overrides and
+calling its ``initialize`` method.
+
+If ``strict_plugin_dependencies`` is set to ``false`` it won't raise an error
+if the optional dependencies aren't found. If set to ``true`` these optional
+dependencies are treated as normal non-optional ones, which means that an error
+will be raised.
 
 synchronize_availability
 ------------------------

docs/source/events.rst

@@ -17,86 +17,94 @@ Events emitted by converse.js
 Event Types
 -----------
 
-Here are the different events that are emitted:
+Hooking into events that Converse.js emits is a great way to extend or
+customize its functionality.
+
+From version 3.0.0 and up, it's only possible to register event handlers inside
+a plugin, by using the closured ``_converse`` object. When writing a plugin,
+remember that it will also have to be whitelisted, before it will be loaded.
+Refer to the :ref:`whitelisted_plugins` setting.
+
+Here follows the different events that are emitted:
 
 cachedRoster
 ~~~~~~~~~~~~
 
 The contacts roster has been retrieved from the local cache (`sessionStorage`).
 
-``converse.listen.on('cachedRoster', function (event, items) { ... });``
+``_converse.on('cachedRoster', function (event, items) { ... });``
 
-See also the `roster` event further down.
+See also the `roster`_ event further down.
 
 callButtonClicked
 ~~~~~~~~~~~~~~~~~
 
 When a call button (i.e. with class .toggle-call) on a chat box has been clicked.
 
-``converse.listen.on('callButtonClicked', function (event, connection, model) { ... });``
+``_converse.on('callButtonClicked', function (event, connection, model) { ... });``
 
 chatBoxInitialized
 ~~~~~~~~~~~~~~~~~~
 
 When a chat box has been initialized. Relevant to converse-chatview.js plugin.
 
-``converse.listen.on('chatBoxInitialized', function (event, chatbox) { ... });``
+``_converse.on('chatBoxInitialized', function (event, chatbox) { ... });``
 
 chatBoxOpened
 ~~~~~~~~~~~~~
 
 When a chat box has been opened. Relevant to converse-chatview.js plugin.
 
-``converse.listen.on('chatBoxOpened', function (event, chatbox) { ... });``
+``_converse.on('chatBoxOpened', function (event, chatbox) { ... });``
 
 chatRoomOpened
 ~~~~~~~~~~~~~~
 
 When a chat room has been opened. Relevant to converse-chatview.js plugin.
 
-``converse.listen.on('chatRoomOpened', function (event, chatbox) { ... });``
+``_converse.on('chatRoomOpened', function (event, chatbox) { ... });``
 
 chatBoxClosed
 ~~~~~~~~~~~~~
 
 When a chat box has been closed. Relevant to converse-chatview.js plugin.
 
-``converse.listen.on('chatBoxClosed', function (event, chatbox) { ... });``
+``_converse.on('chatBoxClosed', function (event, chatbox) { ... });``
 
 chatBoxFocused
 ~~~~~~~~~~~~~~
 
 When the focus has been moved to a chat box. Relevant to converse-chatview.js plugin.
 
-``converse.listen.on('chatBoxFocused', function (event, chatbox) { ... });``
+``_converse.on('chatBoxFocused', function (event, chatbox) { ... });``
 
 chatBoxToggled
 ~~~~~~~~~~~~~~
 
 When a chat box has been minimized or maximized. Relevant to converse-chatview.js plugin.
 
-``converse.listen.on('chatBoxToggled', function (event, chatbox) { ... });``
+``_converse.on('chatBoxToggled', function (event, chatbox) { ... });``
 
 connected
 ~~~~~~~~~
 
 After connection has been established and converse.js has got all its ducks in a row.
 
-``converse.listen.on('connected', function (event) { ... });``
+``_converse.on('connected', function (event) { ... });``
 
 contactRequest
 ~~~~~~~~~~~~~~
 
 Someone has requested to subscribe to your presence (i.e. to be your contact).
 
-``converse.listen.on('contactRequest', function (event, user_data) { ... });``
+``_converse.on('contactRequest', function (event, user_data) { ... });``
 
 contactRemoved
 ~~~~~~~~~~~~~~
 
 The user has removed a contact.
 
-``converse.listen.on('contactRemoved', function (event, data) { ... });``
+``_converse.on('contactRemoved', function (event, data) { ... });``
 
 
 contactStatusChanged
@@ -104,28 +112,28 @@ contactStatusChanged
 
 When a chat buddy's chat status has changed.
 
-``converse.listen.on('contactStatusChanged', function (event, buddy) { ... });``
+``_converse.on('contactStatusChanged', function (event, buddy) { ... });``
 
 contactStatusMessageChanged
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 When a chat buddy's custom status message has changed.
 
-``converse.listen.on('contactStatusMessageChanged', function (event, data) { ... });``
+``_converse.on('contactStatusMessageChanged', function (event, data) { ... });``
 
 disconnected
 ~~~~~~~~~~~~
 
 After converse.js has disconnected from the XMPP server.
 
-``converse.listen.on('disconnected', function (event) { ... });``
+``_converse.on('disconnected', function (event) { ... });``
 
 initialized
 ~~~~~~~~~~~
 
 Once converse.js has been initialized.
 
-``converse.listen.on('initialized', function (event) { ... });``
+``_converse.on('initialized', function (event) { ... });``
 
 See also `pluginsInitialized`_.
 
@@ -134,21 +142,21 @@ logout
 
 The user has logged out.
 
-``converse.listen.on('logout', function (event) { ... });``
+``_converse.on('logout', function (event) { ... });``
 
 messageSend
 ~~~~~~~~~~~
 
 When a message will be sent out.
 
-``converse.listen.on('messageSend', function (event, messageText) { ... });``
+``_converse.on('messageSend', function (event, messageText) { ... });``
 
 noResumeableSession
 ~~~~~~~~~~~~~~~~~~~
 
 When keepalive=true but there aren't any stored prebind tokens.
 
-``converse.listen.on('noResumeableSession', function (event) { ... });``
+``_converse.on('noResumeableSession', function (event) { ... });``
 
 pluginsInitialized
 ~~~~~~~~~~~~~~~~~~
@@ -159,7 +167,7 @@ plugins. In that case, you need to first wait until all plugins have been
 initialized, so that their overrides are active. One example where this is used
 is in `converse-notifications.js <https://github.com/jcbrand/converse.js/blob/master/src/converse-notification.js>`.
 
-``converse.listen.on('pluginsInitialized', function (event) { ... });``
+``_converse.on('pluginsInitialized', function (event) { ... });``
 
 reconnecting
 ~~~~~~~~~~~~
@@ -174,28 +182,28 @@ After the connection has dropped and converse.js has reconnected.
 Any Strophe stanza handlers (as registered via `converse.listen.stanza`) will
 have to be registered anew.
 
-``converse.listen.on('reconnected', function (event) { ... });``
+``_converse.on('reconnected', function (event) { ... });``
 
 roomInviteSent
 ~~~~~~~~~~~~~~
 
 After the user has sent out a direct invitation, to a roster contact, asking them to join a room.
 
-``converse.listen.on('roomInvite', function (event, data) { ... });``
+``_converse.on('roomInvite', function (event, data) { ... });``
 
 roomInviteReceived
 ~~~~~~~~~~~~~~~~~~
 
 After the user has sent out a direct invitation, to a roster contact, asking them to join a room.
 
-``converse.listen.on('roomInvite', function (event, data) { ... });``
+``_converse.on('roomInvite', function (event, data) { ... });``
 
 roster
 ~~~~~~
 
 When the roster has been received from the XMPP server.
 
-``converse.listen.on('roster', function (event, items) { ... });``
+``_converse.on('roster', function (event, items) { ... });``
 
 See also the `cachedRoster` event further up, which gets called instead of
 `roster` if its already in `sessionStorage`.
@@ -226,7 +234,7 @@ rosterPush
 
 When the roster receives a push event from server. (i.e. New entry in your buddy list)
 
-``converse.listen.on('rosterPush', function (event, items) { ... });``
+``_converse.on('rosterPush', function (event, items) { ... });``
 
 rosterReadyAfterReconnection
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -240,25 +248,25 @@ statusInitialized
 
 When own chat status has been initialized.
 
-``converse.listen.on('statusInitialized', function (event, status) { ... });``
+``_converse.on('statusInitialized', function (event, status) { ... });``
 
 statusChanged
 ~~~~~~~~~~~~~
 
 When own chat status has changed.
 
-``converse.listen.on('statusChanged', function (event, status) { ... });``
+``_converse.on('statusChanged', function (event, status) { ... });``
 
 statusMessageChanged
 ~~~~~~~~~~~~~~~~~~~~
 
 When own custom status message has changed.
 
-``converse.listen.on('statusMessageChanged', function (event, message) { ... });``
+``_converse.on('statusMessageChanged', function (event, message) { ... });``
 
 serviceDiscovered
 ~~~~~~~~~~~~~~~~~
 
 When converse.js has learned of a service provided by the XMPP server. See XEP-0030.
 
-``converse.listen.on('serviceDiscovered', function (event, service) { ... });``
+``_converse.on('serviceDiscovered', function (event, service) { ... });``

docs/source/quickstart.rst

@@ -22,16 +22,22 @@ The latest versions of these files are available at these URLs:
 
 To load a specific version of Converse.js you can put the version in the URL, like so:
 
-* https://cdn.conversejs.org/1.0.3/dist/converse.min.js
+* https://cdn.conversejs.org/3.0.3/dist/converse.min.js
-* https://cdn.conversejs.org/1.0.3/css/converse.min.css
+* https://cdn.conversejs.org/3.0.3/css/converse.min.css
 
-You can include these two URLs inside the *<head>* element of your website via the *script* and *link* tags:
+You can include these two URLs inside the *<head>* element of your website
+via the *script* and *link* tags:
 
 .. code-block:: html
 
     <link rel="stylesheet" type="text/css" media="screen" href="https://cdn.conversejs.org/css/converse.min.css">
     <script src="https://cdn.conversejs.org/dist/converse.min.js"></script>
 
+.. note:: Instead of always loading the latest version of Converse.js via the
+    CDN, it's generally better to load a specific version (preferably the
+    latest one), to avoid breakage when new backwards-incompatible versions are
+    released.
+
 Initializing Converse.js
 ------------------------
 
@@ -39,9 +45,7 @@ You'll then need to initialize Converse.js with configuration settings relevant
 Refer to the :ref:`configuration-variables` section for info on all the available configuration settings.
 
 To quickly get started, you can put the following Javascript code at the
-bottom of your page (after the closing *</body>* element):
+bottom of your page (after the closing *</body>* element)::
-
-.. code-block:: javascript
 
     <script>
         converse.initialize({