Update the documentation.
- Fix event listener code examples - Mention the preferability of using versions in the CDN
This commit is contained in:
parent
7ededd2379
commit
853c765f0d
@ -1063,8 +1063,17 @@ loaded), then an error will be raised.
|
|||||||
|
|
||||||
Otherwise a message will simply be logged and the override instruction ignored.
|
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
|
synchronize_availability
|
||||||
------------------------
|
------------------------
|
||||||
|
@ -17,86 +17,94 @@ Events emitted by converse.js
|
|||||||
Event Types
|
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
|
cachedRoster
|
||||||
~~~~~~~~~~~~
|
~~~~~~~~~~~~
|
||||||
|
|
||||||
The contacts roster has been retrieved from the local cache (`sessionStorage`).
|
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
|
callButtonClicked
|
||||||
~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
When a call button (i.e. with class .toggle-call) on a chat box has been clicked.
|
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
|
chatBoxInitialized
|
||||||
~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
When a chat box has been initialized. Relevant to converse-chatview.js plugin.
|
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
|
chatBoxOpened
|
||||||
~~~~~~~~~~~~~
|
~~~~~~~~~~~~~
|
||||||
|
|
||||||
When a chat box has been opened. Relevant to converse-chatview.js plugin.
|
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
|
chatRoomOpened
|
||||||
~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~
|
||||||
|
|
||||||
When a chat room has been opened. Relevant to converse-chatview.js plugin.
|
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
|
chatBoxClosed
|
||||||
~~~~~~~~~~~~~
|
~~~~~~~~~~~~~
|
||||||
|
|
||||||
When a chat box has been closed. Relevant to converse-chatview.js plugin.
|
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
|
chatBoxFocused
|
||||||
~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~
|
||||||
|
|
||||||
When the focus has been moved to a chat box. Relevant to converse-chatview.js plugin.
|
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
|
chatBoxToggled
|
||||||
~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~
|
||||||
|
|
||||||
When a chat box has been minimized or maximized. Relevant to converse-chatview.js plugin.
|
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
|
connected
|
||||||
~~~~~~~~~
|
~~~~~~~~~
|
||||||
|
|
||||||
After connection has been established and converse.js has got all its ducks in a row.
|
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
|
contactRequest
|
||||||
~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~
|
||||||
|
|
||||||
Someone has requested to subscribe to your presence (i.e. to be your contact).
|
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
|
contactRemoved
|
||||||
~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~
|
||||||
|
|
||||||
The user has removed a contact.
|
The user has removed a contact.
|
||||||
|
|
||||||
``converse.listen.on('contactRemoved', function (event, data) { ... });``
|
``_converse.on('contactRemoved', function (event, data) { ... });``
|
||||||
|
|
||||||
|
|
||||||
contactStatusChanged
|
contactStatusChanged
|
||||||
@ -104,28 +112,28 @@ contactStatusChanged
|
|||||||
|
|
||||||
When a chat buddy's chat status has changed.
|
When a chat buddy's chat status has changed.
|
||||||
|
|
||||||
``converse.listen.on('contactStatusChanged', function (event, buddy) { ... });``
|
``_converse.on('contactStatusChanged', function (event, buddy) { ... });``
|
||||||
|
|
||||||
contactStatusMessageChanged
|
contactStatusMessageChanged
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
When a chat buddy's custom status message has changed.
|
When a chat buddy's custom status message has changed.
|
||||||
|
|
||||||
``converse.listen.on('contactStatusMessageChanged', function (event, data) { ... });``
|
``_converse.on('contactStatusMessageChanged', function (event, data) { ... });``
|
||||||
|
|
||||||
disconnected
|
disconnected
|
||||||
~~~~~~~~~~~~
|
~~~~~~~~~~~~
|
||||||
|
|
||||||
After converse.js has disconnected from the XMPP server.
|
After converse.js has disconnected from the XMPP server.
|
||||||
|
|
||||||
``converse.listen.on('disconnected', function (event) { ... });``
|
``_converse.on('disconnected', function (event) { ... });``
|
||||||
|
|
||||||
initialized
|
initialized
|
||||||
~~~~~~~~~~~
|
~~~~~~~~~~~
|
||||||
|
|
||||||
Once converse.js has been initialized.
|
Once converse.js has been initialized.
|
||||||
|
|
||||||
``converse.listen.on('initialized', function (event) { ... });``
|
``_converse.on('initialized', function (event) { ... });``
|
||||||
|
|
||||||
See also `pluginsInitialized`_.
|
See also `pluginsInitialized`_.
|
||||||
|
|
||||||
@ -134,21 +142,21 @@ logout
|
|||||||
|
|
||||||
The user has logged out.
|
The user has logged out.
|
||||||
|
|
||||||
``converse.listen.on('logout', function (event) { ... });``
|
``_converse.on('logout', function (event) { ... });``
|
||||||
|
|
||||||
messageSend
|
messageSend
|
||||||
~~~~~~~~~~~
|
~~~~~~~~~~~
|
||||||
|
|
||||||
When a message will be sent out.
|
When a message will be sent out.
|
||||||
|
|
||||||
``converse.listen.on('messageSend', function (event, messageText) { ... });``
|
``_converse.on('messageSend', function (event, messageText) { ... });``
|
||||||
|
|
||||||
noResumeableSession
|
noResumeableSession
|
||||||
~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
When keepalive=true but there aren't any stored prebind tokens.
|
When keepalive=true but there aren't any stored prebind tokens.
|
||||||
|
|
||||||
``converse.listen.on('noResumeableSession', function (event) { ... });``
|
``_converse.on('noResumeableSession', function (event) { ... });``
|
||||||
|
|
||||||
pluginsInitialized
|
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
|
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>`.
|
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
|
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
|
Any Strophe stanza handlers (as registered via `converse.listen.stanza`) will
|
||||||
have to be registered anew.
|
have to be registered anew.
|
||||||
|
|
||||||
``converse.listen.on('reconnected', function (event) { ... });``
|
``_converse.on('reconnected', function (event) { ... });``
|
||||||
|
|
||||||
roomInviteSent
|
roomInviteSent
|
||||||
~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~
|
||||||
|
|
||||||
After the user has sent out a direct invitation, to a roster contact, asking them to join a room.
|
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
|
roomInviteReceived
|
||||||
~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
After the user has sent out a direct invitation, to a roster contact, asking them to join a room.
|
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
|
roster
|
||||||
~~~~~~
|
~~~~~~
|
||||||
|
|
||||||
When the roster has been received from the XMPP server.
|
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
|
See also the `cachedRoster` event further up, which gets called instead of
|
||||||
`roster` if its already in `sessionStorage`.
|
`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)
|
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
|
rosterReadyAfterReconnection
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
@ -240,25 +248,25 @@ statusInitialized
|
|||||||
|
|
||||||
When own chat status has been initialized.
|
When own chat status has been initialized.
|
||||||
|
|
||||||
``converse.listen.on('statusInitialized', function (event, status) { ... });``
|
``_converse.on('statusInitialized', function (event, status) { ... });``
|
||||||
|
|
||||||
statusChanged
|
statusChanged
|
||||||
~~~~~~~~~~~~~
|
~~~~~~~~~~~~~
|
||||||
|
|
||||||
When own chat status has changed.
|
When own chat status has changed.
|
||||||
|
|
||||||
``converse.listen.on('statusChanged', function (event, status) { ... });``
|
``_converse.on('statusChanged', function (event, status) { ... });``
|
||||||
|
|
||||||
statusMessageChanged
|
statusMessageChanged
|
||||||
~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
When own custom status message has changed.
|
When own custom status message has changed.
|
||||||
|
|
||||||
``converse.listen.on('statusMessageChanged', function (event, message) { ... });``
|
``_converse.on('statusMessageChanged', function (event, message) { ... });``
|
||||||
|
|
||||||
serviceDiscovered
|
serviceDiscovered
|
||||||
~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
When converse.js has learned of a service provided by the XMPP server. See XEP-0030.
|
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) { ... });``
|
||||||
|
@ -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:
|
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
|
.. code-block:: html
|
||||||
|
|
||||||
<link rel="stylesheet" type="text/css" media="screen" href="https://cdn.conversejs.org/css/converse.min.css">
|
<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>
|
<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
|
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.
|
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
|
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>
|
<script>
|
||||||
converse.initialize({
|
converse.initialize({
|
||||||
|
Loading…
Reference in New Issue
Block a user