Procházet zdrojové kódy

Use newest pluggable.js.

`optional_dependencies` is now called `dependencies`
JC Brand před 7 roky
rodič
revize
c22aff9b13

+ 11 - 9
docs/source/configuration.rst

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

+ 26 - 27
docs/source/plugin_development.rst

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

+ 1 - 1
package.json

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

+ 1 - 1
src/converse-bookmarks.js

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

+ 1 - 1
src/converse-chatview.js

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

+ 1 - 1
src/converse-dragresize.js

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

+ 1 - 1
src/converse-mam.js

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

+ 1 - 1
src/converse-minimize.js

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

+ 1 - 1
src/converse-muc.js

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

+ 1 - 1
src/converse-roomslist.js

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

+ 1 - 1
src/converse-singleton.js

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