Browse Source

Update plugin docs. Show fiddle example

JC Brand 8 năm trước cách đây
mục cha
commit
4ebc00282c
3 tập tin đã thay đổi với 35 bổ sung3 xóa
  1. 1 1
      docs/CHANGES.md
  2. 2 0
      docs/source/configuration.rst
  3. 32 2
      docs/source/plugin_development.rst

+ 1 - 1
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]

+ 2 - 0
docs/source/configuration.rst

@@ -1196,6 +1196,8 @@ An example from `the embedded room demo <https://conversejs.org/demo/embedded.ht
     });
 
 
+.. _`whitelisted_plugins`:
+
 whitelisted_plugins
 -------------------
 

+ 32 - 2
docs/source/plugin_development.rst

@@ -25,6 +25,17 @@ To understand how this plugin architecture works, please read the
 and to understand its inner workins, please refer to the `annotated source code
 <https://jcbrand.github.io/pluggable.js/docs/pluggable.html>`_.
 
+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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~