From 990aefc6cba714dcf1c8b7a16bb12e5db235cb67 Mon Sep 17 00:00:00 2001 From: JC Brand Date: Tue, 19 Jul 2022 10:35:45 +0200 Subject: [PATCH] docs: Discourage usage of overrides and add hook to example plugin --- docs/source/development.rst | 2 +- docs/source/plugin_development.rst | 161 +++++++++++++---------------- 2 files changed, 73 insertions(+), 90 deletions(-) diff --git a/docs/source/development.rst b/docs/source/development.rst index dd23596e7..a73d92929 100644 --- a/docs/source/development.rst +++ b/docs/source/development.rst @@ -23,7 +23,7 @@ to fix a bug or to add new functionality. .. toctree:: :maxdepth: 2 - setup_dev_environment + setup_dev_environment plugin_development api/index testing diff --git a/docs/source/plugin_development.rst b/docs/source/plugin_development.rst index d2bb6c028..a6feae307 100644 --- a/docs/source/plugin_development.rst +++ b/docs/source/plugin_development.rst @@ -16,7 +16,7 @@ and is itself composed out of plugins. There are only a few files that are included in the default build of Converse which aren't plugins. -An important one is `converse-core.js `_, +An important one is `core.js `_, which is responsible for bootstrapping the plugin architecture, setting up and maintaining the connection to the XMPP server and declaring the public (`window.converse `_) and protected (`_converse.api `_) APIs. @@ -180,11 +180,59 @@ The code for it could look something like this: These dependencies are closured so that they don't pollute the global namespace, that's why you need to access them in such a way inside the module. -Overrides ---------- +Overriding templates +-------------------- + +Converse uses `lit-html `_ +templates and templates are imported as separate files. + +It's possible to configure your module bundler (e.g. Webpack) in such as way that a +different file is loaded when a template is imported. + +This allows you to create your own templates that are used instead of the ones +that would have originally been imported. + +With Webpack (which Converse uses internally), you can specify an +``alias`` for the template you want to override. This alias then points to your +own custom template. + +For example, in your webpack config file, you could add the following to the +``config`` object that gets exported: + +.. code-block:: javascript + + resolve: { + extensions: ['.js'], + modules: [ + path.join(__dirname, 'node_modules'), + path.join(__dirname, 'node_modules/converse.js/src') + ], + alias: { + 'plugins/profile/templates/profile.js$': path.resolve(__dirname, 'templates/custom-profile.js') + } + } + +This will override the template that gets imported at the path ``plugins/profile/templates/profile.js`` +with your own template at the path ``templates/custom-profile.js`` (relative to your webpack config file). + + +Object and class Overrides +-------------------------- + +.. note:: Using the `overrides` feature from pluggable.js is discouraged. It's + much better to use events, promises and `hooks`_ to modify the behaviour of + Converse. + + The pluggable.js `overrides` will only work on objects and classes that are + set as attributes on the `_converse` object, which doesn't apply to many + newer classes and objects, such as the web components. For these clasess, + overrides won't work at all. + + This section is left here for completeness, because in some special cases + overrides are still used. Plugins can override core code or code from other plugins. You can specify -overrides in the object passed to ``converse.plugins.add``. +overrides in the object passed to ``converse.plugins.add``. In an override you can still call the overridden function, by calling ``this.__super__.methodName.apply(this, arguments);`` where ``methodName`` is @@ -242,7 +290,7 @@ monkey patching which pollutes the call stack and can make your code fragile and prone to bugs when Converse gets updated. Too much use of ``overrides`` is therefore a "code smell" which should ideally be avoided. -A better approach is to listen to the events emitted by Converse, and to add +A better approach is to use the events and `hooks`_ emitted by Converse, and to add your code in event handlers. This is however not always possible, in which case the overrides are a powerful tool. @@ -260,40 +308,6 @@ For example: Object.assign(_converse.ChatBoxView.prototype, { doSomething }); -Overriding a template -~~~~~~~~~~~~~~~~~~~~~ - -Converse uses `lit-html `_ -templates. - -It's not possible to override a template with the plugin's ``overrides`` -feature, instead you should configure a new path to your own template via your -module bundler. - -For example, with Webpack (which Converse uses internall), you can specify an -``alias`` for the template you want to override. This alias then points to your -own custom template. - -For example, in your webpack config file, you could add the following to the -``config`` object that gets exported: - -.. code-block:: javascript - - resolve: { - extensions: ['.js'], - modules: [ - path.join(__dirname, 'node_modules'), - path.join(__dirname, 'node_modules/converse.js/src') - ], - alias: { - 'plugins/profile/templates/profile.js$': path.resolve(__dirname, 'templates/custom-profile.js') - } - } - -This will override the template that gets imported at the path ``plugins/profile/templates/profile.js`` -with your own template at the path ``templates/custom-profile.js`` (relative to -your webpack config file). - .. _`dependencies`: @@ -515,8 +529,8 @@ The `Actions `_. @@ -590,8 +604,8 @@ generated by `generator-conversejs { + buttons.push(html` + + `); + return buttons; + }); } });