|
@@ -212,60 +212,59 @@ A better approach is to listen to the events emitted by Converse.js, and to add
|
|
your code in event handlers. This is however not always possible, in which case
|
|
your code in event handlers. This is however not always possible, in which case
|
|
the overrides are a powerful tool.
|
|
the overrides are a powerful tool.
|
|
|
|
|
|
-.. _`optional_dependencies`:
|
|
|
|
|
|
+.. _`dependencies`:
|
|
|
|
|
|
-Optional plugin dependencies
|
|
|
|
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
+Plugin dependencies
|
|
|
|
+~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
When using ``overrides``, the code that you want to override (which is either
|
|
When using ``overrides``, the code that you want to override (which is either
|
|
-in ``converse-core`` or in other plugins), needs to be loaded already by the
|
|
|
|
-type the ``overrides`` object is being parsed.
|
|
|
|
|
|
+in ``converse-core`` or in other plugins), needs to be parsed already by the
|
|
|
|
+time your ``overrides`` are being parsed.
|
|
|
|
|
|
-So it's important to include overridden plugins in the AMD ``define`` statement
|
|
|
|
-at the top of the plugin module.
|
|
|
|
|
|
+Additionally, when you register event or promise handlers in your plugin for
|
|
|
|
+events/promises that fire in other plugins, then you want those plugins to have
|
|
|
|
+been loaded before your plugin gets loaded.
|
|
|
|
|
|
-However, sometimes you want to override parts of another plugin if it exists, but you
|
|
|
|
-don't want anything to break if it doesn't exist (for example when using a
|
|
|
|
-custom build which excludes that plugin). An example is the
|
|
|
|
-`converse-dragresize <https://github.com/jcbrand/converse.js/blob/master/src/converse-dragresize.js>`_
|
|
|
|
|
|
+To resolve this problem we have the ``dependencies`` Array attribute.
|
|
|
|
+With this you can specify those dependencies which need to be loaded before
|
|
|
|
+your plugin is loaded.
|
|
|
|
+
|
|
|
|
+In some cases, you might want to depend on another plugin if it's available,
|
|
|
|
+but don't care when it's not available.
|
|
|
|
+An example is the `converse-dragresize <https://github.com/jcbrand/converse.js/blob/master/src/converse-dragresize.js>`_
|
|
plugin, which will add drag-resize handles to the headlines box (which shows
|
|
plugin, which will add drag-resize handles to the headlines box (which shows
|
|
-messages of type ``headline``) but doesn't care if that particular plugin isn't
|
|
|
|
-actually loaded.
|
|
|
|
|
|
+messages of type ``headline``) but doesn't care when that particular plugin is
|
|
|
|
+not available.
|
|
|
|
+
|
|
|
|
+If the :ref:`strict_plugin_dependencies` setting is set to ``false`` (which is
|
|
|
|
+its default value), then no error will be raised if the plugin is not found.
|
|
|
|
|
|
In this case, you can't specify the plugin as a dependency in the ``define``
|
|
In this case, you can't specify the plugin as a dependency in the ``define``
|
|
statement at the top of the plugin, since it might not always be available,
|
|
statement at the top of the plugin, since it might not always be available,
|
|
which would cause ``require.js`` to throw an error.
|
|
which would cause ``require.js`` to throw an error.
|
|
|
|
|
|
-To resolve this problem we have the ``optional_dependencies`` Array attribute.
|
|
|
|
-With this you can specify those dependencies which need to be loaded before
|
|
|
|
-your plugin, if they exist. If they don't exist, they won't be ignored.
|
|
|
|
-
|
|
|
|
-If the setting :ref:`strict_plugin_dependencies` is set to true,
|
|
|
|
-an error will be raised if the plugin is not found, thereby making them
|
|
|
|
-non-optional.
|
|
|
|
-
|
|
|
|
Extending converse.js's configuration settings
|
|
Extending converse.js's configuration settings
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
-Converse.js comes with various :ref:`configuration-settings`_ that can be used to
|
|
|
|
|
|
+Converse.js comes with various :ref:`configuration-settings` that can be used to
|
|
modify its functionality and behavior.
|
|
modify its functionality and behavior.
|
|
|
|
|
|
All configuration settings have default values which can be overridden when
|
|
All configuration settings have default values which can be overridden when
|
|
-`converse.initialize` (see :ref:`initialize`_) gets called.
|
|
|
|
|
|
+`converse.initialize` (see :ref:`initialize`) gets called.
|
|
|
|
|
|
Plugins often need their own additional configuration settings and you can add
|
|
Plugins often need their own additional configuration settings and you can add
|
|
these settings with the `_converse.api.settings.update` method (see
|
|
these settings with the `_converse.api.settings.update` method (see
|
|
-:ref:`settings-update`_).
|
|
|
|
|
|
+:ref:`settings-update`).
|
|
|
|
|
|
Exposing promises
|
|
Exposing promises
|
|
~~~~~~~~~~~~~~~~~
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
-Converse.js has a ``waitUntil`` API method (see :ref:`waituntil-grouping`_)
|
|
|
|
|
|
+Converse.js has a ``waitUntil`` API method (see :ref:`waituntil-grouping`)
|
|
which allows you to wait for various promises to resolve before executing a
|
|
which allows you to wait for various promises to resolve before executing a
|
|
piece of code.
|
|
piece of code.
|
|
|
|
|
|
You can add new promises for your plugin by calling
|
|
You can add new promises for your plugin by calling
|
|
-``_converse.api.promises.add`` (see :ref:`promises-grouping`_).
|
|
|
|
|
|
+``_converse.api.promises.add`` (see :ref:`promises-grouping`).
|
|
|
|
|
|
Generally, your plugin will then also be responsible for making sure these
|
|
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
|
|
promises are resolved. You do this by calling ``_converse.api.emit``, which not
|
|
@@ -398,7 +397,7 @@ generated by `generator-conversejs <https://github.com/jcbrand/generator-convers
|
|
* If the setting "strict_plugin_dependencies" is set to true,
|
|
* If the setting "strict_plugin_dependencies" is set to true,
|
|
* an error will be raised if the plugin is not found.
|
|
* an error will be raised if the plugin is not found.
|
|
*/
|
|
*/
|
|
- 'optional_dependencies': [],
|
|
|
|
|
|
+ 'dependencies': [],
|
|
|
|
|
|
/* Converse.js's plugin mechanism will call the initialize
|
|
/* Converse.js's plugin mechanism will call the initialize
|
|
* method on any plugin (if it exists) as soon as the plugin has
|
|
* method on any plugin (if it exists) as soon as the plugin has
|