Add undocumented events and setting. Link to OMEMO docs

* `connectionInitialized` and `converse-loaded` events
* allow_login` setting

docs/source/configuration.rst

@@ -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
 ---------
 

docs/source/dependencies.rst

@@ -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.
 

docs/source/events.rst

@@ -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
 ~~~~~~~~~~~~~~
 

docs/source/features.rst

@@ -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>`_.
 

docs/source/quickstart.rst

@@ -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.

docs/source/setup.rst

@@ -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: