Add undocumented events and setting. Link to OMEMO docs

* `connectionInitialized` and `converse-loaded` events
* allow_login` setting
This commit is contained in:
JC Brand 2019-02-25 14:18:05 +01:00
parent 59c43a23f0
commit 50168061ad
6 changed files with 61 additions and 4 deletions

View File

@ -154,6 +154,13 @@ Allow users to resize chats by dragging the edges. The min-height and min-width
CSS properties set on a chatboxes (specifically on the ``#converse.js .chatbox > .box-flyout`` element)
will be honored, IF they are set in pixels.
allow_logout
------------
* Default: ``true``
Determines whether the user is allowed to log out. If set to ``false``, there will be no logout button.
allow_muc
---------

View File

@ -100,10 +100,12 @@ Converse relies on the following dependencies:
allows existing attributes, functions and objects on Converse to be
overridden inside plugins.
.. _`dependency-libsignal`:
Libsignal
---------
Optionally, if you want OMEMO encryption, you need to load `libsignal
If you want OMEMO encryption, you need to load `libsignal
<https://github.com/signalapp/libsignal-protocol-javascript>`_ separately in
your page.

View File

@ -19,6 +19,7 @@ The core events, which are also promises are:
* `cachedRoster`_
* `chatBoxesFetched`_
* `connectionInitialized`_
* `controlboxInitialized`_ (only via the `converse-controlbox` plugin)
* `pluginsInitialized`_
* `roomsPanelRendered`_ (only via the `converse-muc` plugin)
@ -34,8 +35,33 @@ For more info on how to use (or add promises), you can read the
Below we will now list all events and also specify whether they are available
as promises.
List of global events (and promises)
------------------------------------
Global events
-------------
With global events, we mean events triggered in the global context, i.e. on the
`window` object in browsers.
converse-loaded
---------------
Once Converse.js has loaded, it'll dispatch a custom event with the name
``converse-loaded``.
You can listen for this event in your scripts and thereby be informed as soon
as converse.js has been loaded, which would mean it's safe to call
``converse.initialize``.
For example:
.. code-block:: javascript
window.addEventListener('converse-loaded', () => {
converse.initialize();
});
List protected of events (and promises)
----------------------------------------
Hooking into events that Converse.js emits is a great way to extend or
customize its functionality.
@ -161,6 +187,12 @@ After connection has been established and converse.js has got all its ducks in a
``_converse.api.listen.on('connected', function () { ... });``
connectionInitialized
~~~~~~~~~~~~~~~~~~~~~
Called once the ``Strophe.Connection`` constructor has been initialized, which
will be responsible for managing the connection to the XMPP server.
contactRequest
~~~~~~~~~~~~~~

View File

@ -25,10 +25,16 @@ The file server needs to be configured for `Cross-Origin resource sharing <https
``Access-Control-Allow-Origin`` header which includes the domain hosting
Converse.
.. _`feature-omemo`:
End to end message encryption (`XEP-0384 OMEMO <https://xmpp.org/extensions/xep-0363.html>`_)
=============================================================================================
.. note::
Converse.js (as of version 4.1.2) does NOT support encryption or decryption
of uploaded files. Files will be uploaded WITHOUT ENCRYPTION, even when
OMEMO is enabled.
Converse supports OMEMO encryption based on the
`Signal Protocol <https://github.com/signalapp/libsignal-protocol-javascript>`_.

View File

@ -104,6 +104,11 @@ your website, where users authenticate once in your website and are then
automatically logged in to the XMPP server as well. For more info on how this
can be achieved, read: :ref:`session-support`.
For end-to-end encryption via OMEMO, you'll need to load `libsignal-protocol.js
<https://github.com/signalapp/libsignal-protocol-javascript>`_ separately in
your page. Take a look at the section on :ref:`libsignal <dependency-libsignal>` and the
:ref:`security considerations around OMEMO <feature-omemo>`.
Perhaps you want to create your own custom build of Converse? Then head over
to the :doc:`builds` section, or more generally the :doc:`development <development>`
documentation.

View File

@ -15,7 +15,12 @@ At the very least you'll need Converse and an :ref:`XMPP server` with
:ref:`websocket-section` or :ref:`BOSH-section` enabled. That's definitely
enough to simply demo Converse or to do development work on it.
However, if you want to more fully integrate it into a website
For end-to-end encryption via OMEMO, you'll need to load `libsignal-protocol.js
<https://github.com/signalapp/libsignal-protocol-javascript>`_ separately in
your page. Take a look at the section on :ref:`libsignal <dependency-libsignal>` and the
:ref:`security considerations around OMEMO <feature-omemo>`.
If you want to more fully integrate it into a website
then you'll likely need to set up more services and components.
The diagram below shows a fairly common setup for a website or intranet: