From 4ebc00282c0cafc82c4deed0f2597cd007dcb3da Mon Sep 17 00:00:00 2001 From: JC Brand Date: Thu, 9 Mar 2017 14:01:31 +0000 Subject: [PATCH] Update plugin docs. Show fiddle example --- docs/CHANGES.md | 2 +- docs/source/configuration.rst | 2 ++ docs/source/plugin_development.rst | 34 ++++++++++++++++++++++++++++-- 3 files changed, 35 insertions(+), 3 deletions(-) diff --git a/docs/CHANGES.md b/docs/CHANGES.md index a34a3c795..a13bf9c5b 100755 --- a/docs/CHANGES.md +++ b/docs/CHANGES.md @@ -2,6 +2,7 @@ ## 3.0.1 (Unreleased) +- #585 Duplicate contact created due to JID case sensivity [saganshul] - #628 Fixes the bug in displaying chat status during private chat. [saganshul] - #806 The `_converse.listen` API event listeners aren't triggered. [jcbrand] - #807 Error: Plugin "converse-dragresize" tried to override HeadlinesBoxView but it's not found. [jcbrand] @@ -70,7 +71,6 @@ New configuration setting: [muc_show_join_leave](https://conversejs.org/docs/html/configuration.html#muc-show-join-leave) - #366 Show the chat room occupant's JID in the tooltip (if you're allowed to see it). [jcbrand] -- #585 Fixes the duplication bug due to case sensivity in adding contacts [saganshul] - #610, #785 Add presence priority handling [w3host, jcbrand] - #620 `auto_away` shouldn't change the user's status if it's set to `dnd`. [jcbrand] - #694 The `notification_option` wasn't being used consistently. [jcbrand] diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index 71beeb91d..aaeb19758 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -1196,6 +1196,8 @@ An example from `the embedded room demo `_. +Below you'll find an example plugin. Because convers.js is only Javascript, +HTML and CSS (with no backend code required like PHP, Python or Ruby) it runs +fine in JSFiddle. + +Here's an Fiddle with a plugin that calls `alert` when the plugin gets +initialized and when a message gets rendered: https://jsfiddle.net/4drfaok0/15/ + + +Registering a plugin +-------------------- + You register a converse.js plugin as follows: .. code-block:: javascript @@ -41,6 +52,24 @@ You register a converse.js plugin as follows: }, }); +.. note:: It's important that `converse.plugins.add` is called **before** + `converse.initialize` is called. Otherwise the plugin will never get + registered and never get called. + + +Whitelisting of plugins +----------------------- + +As of converse.js 3.0.0 and higher, plugins need to be whitelisted before they +can be used. This is because plugins have access to a powerful API. For +example, they can read all messages and send messages on the user's behalf. + +To avoid malicious plugins being registered (i.e. by malware infected +advertising networks) we now require whitelisting. + +To whitelist a plugin simply means to specify :ref:`whitelisted_plugins` when +you call ``converse.initialize``. + Security and access to the inner workings ----------------------------------------- @@ -59,8 +88,8 @@ The inner ``_converse`` object is made private in order to safely hide and encapsulate sensitive information and methods which should not be exposed to any 3rd-party scripts that might be running in the same page. -Loading a plugin ------------------ +Loading a plugin module +----------------------- Converse.js uses the UMD (Universal Modules Definition) as its module syntax. This makes modules loadable via `require.js`, `webpack` or other module @@ -97,6 +126,7 @@ Here's an example of the plugin shown above wrapped inside a UMD module: }); + Accessing 3rd party libraries ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~