Add doc section on dealing with asynchronicity in plugins

docs/source/plugin_development.rst

@@ -35,7 +35,7 @@ and to understand its inner workins, please refer to the `annotated source code
     Because Converse.js consists only of JavaScript, HTML and CSS (with no backend
     code required like PHP, Python or Ruby) it runs fine in JSFiddle.
 
-    Here's a Fiddle with a Converse.js plugin that calls `alert` once it gets
+    Here's a Fiddle with a Converse.js plugin that calls ``alert`` once it gets
     initialized and also when a chat message gets rendered: https://jsfiddle.net/4drfaok0/15/
 
 
@@ -254,9 +254,73 @@ Generally, your plugin will then also be responsible for making sure these
 promises are resolved. You do this by calling ``_converse.api.emit``, which not
 only resolves the plugin but will also emit an event with the same name.
 
+Dealing with asynchronicity
+---------------------------
+
+Due to the asynchronous nature of XMPP, many subroutines in Converse.js execute
+at different times and not necessarily in the same order.
+
+In many cases, when you want to execute a piece of code in a plugin, you first
+want to make sure that the supporting data-structures that your code might rely
+on have been created and populated with data.
+
+There are two ways of waiting for the right time before executing your code.
+You can either listen for certain events, or you can wait for promises to
+resolve.
+
+For example, in the ``Bookmarks`` plugin (in
+`src/converse-bookmarks.js <https://github.com/jcbrand/converse.js/blob/6c3aa34c23d97d679823a64376418cd0f40a8b94/src/converse-bookmarks.js#L528>`_),
+before bookmarks can be fetched and shown to the user, we first have to wait until
+the `"Rooms"` panel of the ``ControlBox`` has been rendered and inserted into
+the DOM. Otherwise we have no place to show the bookmarks yet.
+
+Therefore, there are the following lines of code in the ``initialize`` method of
+`converse-bookmarks.js <https://github.com/jcbrand/converse.js/blob/6c3aa34c23d97d679823a64376418cd0f40a8b94/src/converse-bookmarks.js#L528>`_:
+
+.. code-block:: javascript
+
+    Promise.all([
+        _converse.api.waitUntil('chatBoxesFetched'),
+        _converse.api.waitUntil('roomsPanelRendered')
+    ]).then(initBookmarks);
+
+What this means, is that the plugin will wait until the ``chatBoxesFetched``
+and ``roomsPanelRendered`` promises have been resolved before it calls the
+``initBookmarks`` method (which is defined inside the plugin).
+
+This way, we know that we have everything in place and set up correctly before
+fetching the bookmarks.
+
+As another example, there is also the following code in the ``initialize``
+method of the plugin:
+
+.. code-block:: javascript
+
+    _converse.on('chatBoxOpened', function renderMinimizeButton (view) {
+        // Inserts a "minimize" button in the chatview's header
+
+        // Implementation code removed for brevity
+        // ...
+    });
+
+In this case, the plugin waits for the ``chatBoxOpened`` event, before it then
+calls ``renderMinimizeButton``, which adds a new button to the chat box (which
+enables you to minimize it).
+
+Finding the right promises and/or events to listen to, can be a bit
+challenging, and sometimes it might be necessary to create new events or
+promises.
+
+Please refer to the :ref:`events-API` section of the documentation for an
+overview of what's available to you. If you need new events or promises, then
+`please open an issue or make a pull request on Github <https://github.com/jcbrand/converse.js>`_
+
 A full example plugin
 ---------------------
 
+Below follows a documented example of a plugin. This is the same code that gets
+generated by `generator-conversejs <https://github.com/jcbrand/generator-conversejs>`_.
+
 .. code-block:: javascript
 
     (function (root, factory) {