Use newest pluggable.js.

`optional_dependencies` is now called `dependencies`
This commit is contained in:
JC Brand 2018-01-10 12:59:45 +00:00
parent 4f227b467b
commit c22aff9b13
11 changed files with 46 additions and 45 deletions

View File

@ -1233,17 +1233,19 @@ loaded), then an error will be raised.
Otherwise a message will simply be logged and the override instruction ignored.
The Converse.js plugins architecture can have an :ref:`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
The Converse.js plugins architecture can have an :ref:`dependencies`
plugin attribute. This enables you to specify an array of other plugins which
this one depends on.
Converse.js (more specifically, `pluggable.js <https://jcbrand.github.io/pluggable.js/>`_)
will first load these 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.
This is especially important if you register event handlers in your plugin for
events that fire in other plugins. In this case, you want to specify those
other plugins as dependencies.
If ``strict_plugin_dependencies`` is set to ``false``, an error won't be raised
if the optional dependencies aren't found.
synchronize_availability
------------------------

View File

@ -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
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
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
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``
statement at the top of the plugin, since it might not always be available,
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
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
these settings with the `_converse.api.settings.update` method (see
:ref:`settings-update`_).
:ref:`settings-update`).
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
piece of code.
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
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,
* an error will be raised if the plugin is not found.
*/
'optional_dependencies': [],
'dependencies': [],
/* Converse.js's plugin mechanism will call the initialize
* method on any plugin (if it exists) as soon as the plugin has

View File

@ -58,7 +58,7 @@
"moment": "~2.18.1",
"npm": "^4.1.1",
"otr": "0.2.16",
"pluggable.js": "1.0.1",
"pluggable.js": "git+https://github.com/jcbrand/pluggable.js.git",
"po2json": "^0.4.4",
"requirejs": "2.3.5",
"run-headless-chromium": "^0.1.1",

View File

@ -33,7 +33,7 @@
converse.plugins.add('converse-bookmarks', {
optional_dependencies: ["converse-chatboxes", "converse-muc"],
dependencies: ["converse-chatboxes", "converse-muc"],
overrides: {
// Overrides mentioned here will be picked up by converse.js's

View File

@ -60,7 +60,7 @@
*
* NB: These plugins need to have already been loaded via require.js.
*/
optional_dependencies: ["converse-chatboxes"],
dependencies: ["converse-chatboxes"],
overrides: {
// Overrides mentioned here will be picked up by converse.js's

View File

@ -41,7 +41,7 @@
*
* NB: These plugins need to have already been loaded via require.js.
*/
optional_dependencies: ["converse-headline"],
dependencies: ["converse-headline"],
enabled (_converse) {
return _converse.view_mode == 'overlayed';

View File

@ -39,7 +39,7 @@
converse.plugins.add('converse-mam', {
optional_dependencies: ['converse-chatview', 'converse-muc'],
dependencies: ['converse-chatview', 'converse-muc'],
overrides: {
// Overrides mentioned here will be picked up by converse.js's

View File

@ -39,7 +39,7 @@
*
* NB: These plugins need to have already been loaded via require.js.
*/
optional_dependencies: ["converse-controlbox", "converse-muc"],
dependencies: ["converse-controlbox", "converse-muc"],
enabled (_converse) {
return _converse.view_mode == 'overlayed';

View File

@ -131,7 +131,7 @@
*
* NB: These plugins need to have already been loaded via require.js.
*/
optional_dependencies: ["converse-controlbox", "converse-chatview"],
dependencies: ["converse-controlbox", "converse-chatview"],
overrides: {
// Overrides mentioned here will be picked up by converse.js's

View File

@ -34,7 +34,7 @@
*
* NB: These plugins need to have already been loaded via require.js.
*/
optional_dependencies: ["converse-controlbox", "converse-muc", "converse-bookmarks"],
dependencies: ["converse-controlbox", "converse-muc", "converse-bookmarks"],
initialize () {
/* The initialize function gets called as soon as the plugin is

View File

@ -37,7 +37,7 @@
// an error will be raised if the plugin is not found.
//
// NB: These plugins need to have already been loaded via require.js.
optional_dependencies: ['converse-muc', 'converse-controlbox', 'converse-rosterview'],
dependencies: ['converse-muc', 'converse-controlbox', 'converse-rosterview'],
enabled (_converse) {
return _.includes(['mobile', 'fullscreen'], _converse.view_mode);