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

Update the documentation.

Browse Source 
- Fix event listener code examples
- Mention the preferability of using versions in the CDN
This commit is contained in:
JC Brand 2017-04-18 19:24:49 +02:00
parent 7ededd2379
commit 853c765f0d
3 changed files with 59 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
docs/source/configuration.rst
View File

@ -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
as dependencies.
The Converse.js plugins architecture can have an ``optional_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
------------------------

68
docs/source/events.rst
View File

@ -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) { ... });``

16
docs/source/quickstart.rst
View File

@ -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/1.0.3/css/converse.min.css
* https://cdn.conversejs.org/3.0.3/dist/converse.min.js
* 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):
.. code-block:: javascript
bottom of your page (after the closing *</body>* element)::
<script>
converse.initialize({