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.
|
||||
|
||||
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
|
||||
------------------------
|
||||
|
@ -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) { ... });``
|
||||
|
@ -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({
|
||||
|
Loading…
Reference in New Issue
Block a user