+
+
+
+
+
diff --git a/docs/CHANGES.md b/docs/CHANGES.md
index 5e665b561..301370e65 100755
--- a/docs/CHANGES.md
+++ b/docs/CHANGES.md
@@ -4,21 +4,29 @@
- Case insensitive matching of moderation commands. [jcbrand]
- Add `/subject` as alias to `/topic` [jcbrand]
- `allow_chat_pending_contacts` now defaults to `true` [jcbrand]
-- *Breaking change*: Callbacks for `converse.on` now no longer receive an event
- object as first parameter. [jcbrand]
+- *Breaking change*: Callbacks for `converse.on` now no longer receive an
+ event object as first parameter. [jcbrand]
- Use lodash instead of underscore.js [jcbrand]
- Improved roster filter UX. [jcbrand]
- Render the login form again upon authfail. [jcbrand]
-- New promises API: [waitUntil](https://conversejs.org/docs/html/developer_api.html#waituntil) [jcbrand]
+- New promises API: [waitUntil](https://conversejs.org/docs/html/developer_api.html#waituntil)
+ [jcbrand]
- New configuration setting:
[show_chatstate_notifications](https://conversejs.org/docs/html/configuration.html#show-chatstate-notifications)
[jcbrand]
+- New configuration setting:
+ [whitelisted_plugins](https://conversejs.org/docs/html/configuration.html#whitelisted-plugins)
+ [jcbrand]
+- New configuration setting:
+ [blacklisted_plugins](https://conversejs.org/docs/html/configuration.html#blacklisted-plugins)
+ [jcbrand]
- The API now no longer returns wrapped chatboxes (or rooms) but instead a
Backbone.View object. This means the API of the returned object has changed.
You're still able to do everything from before but now also much more.
[jcbrand]
- Allow JIDs not on the roster to be invited to a chatroom. [jcbrand]
-- Bugfix. 'TypeError: this.sendConfiguration(...).then is not a function' when an instant room is created. [jcbrand]
+- Bugfix. 'TypeError: this.sendConfiguration(...).then is not a function' when
+ an instant room is created. [jcbrand]
- Ensure consistent behavior from `show_controlbox_by_default` [jcbrand]
- #694 The `notification_option` wasn't being used consistently. [jcbrand]
- #770 Allow setting contact attrs on chats.open [Ape]
diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst
index 1badb3bf1..c37b364db 100644
--- a/docs/source/configuration.rst
+++ b/docs/source/configuration.rst
@@ -330,7 +330,7 @@ You can either specify a simple list of room JIDs, in which case your nickname
will be taken from your JID, or you can specify a list of maps, where each map
specifies the room's JID and the nickname that should be used.
-For example:
+For example::
`[{'jid': 'room@example.org', 'nick': 'WizardKing69' }]`
@@ -411,7 +411,9 @@ accepts, refer to the
As an example, suppose you want to restrict the supported SASL authentication
mechanisms, then you'd pass in the ``mechanisms`` as a ``connection_options``
-``key:value`` pair::
+``key:value`` pair:
+
+.. code-block:: javascript
converse.initialize({
connection_options: {
@@ -582,7 +584,8 @@ state. The only defined states are:
* dnd -- The entity or resource is busy (dnd = "Do Not Disturb").
* xa -- The entity or resource is away for an extended period (xa = "eXtended Away").
-Read the [relevant section in the XMPP spec](https://xmpp.org/rfcs/rfc6121.html#presence-syntax-children-show) for more info.
+Read the `relevant section in the XMPP spec `_
+for more info.
What used to happen in converse.js when the `offline` state was chosen, is
that a presence stanza with a `type` of `unavailable` was sent out.
@@ -1068,7 +1071,9 @@ Allows you to show or hide buttons on the chat boxes' toolbars.
* *call*:
Provides a button with a picture of a telephone on it.
- When the call button is pressed, it will emit an event that can be used by a third-party library to initiate a call.::
+ When the call button is pressed, it will emit an event that can be used by a third-party library to initiate a call.
+
+ .. code-block:: javascript
converse.listen.on('callButtonClicked', function(data) {
console.log('Strophe connection is', data.connection);
@@ -1109,6 +1114,107 @@ support.
.. note::
Converse.js does not yet support "keepalive" with websockets.
+blacklisted_plugins
+-------------------
+
+* Default: ``[]``
+
+A list of plugin names that are blacklisted and will therefore not be
+initialized once ``converse.initialize`` is called, even if the same plugin is
+whitelisted.
+
+From Converse.js 3.0 onwards most of the API is available only to plugins and
+all plugins need to be whitelisted first.
+
+The usecase for blacklisting is generally to disable removed core plugins
+(which are automatically whitelisted) to prevent other (potentially malicious)
+plugins from registering themselves under those names.
+
+The core, and by default whitelisted, plugins are::
+
+ converse-bookmarks
+ converse-chatview
+ converse-controlbox
+ converse-core
+ converse-dragresize
+ converse-headline
+ converse-mam
+ converse-minimize
+ converse-muc
+ converse-notification
+ converse-otr
+ converse-ping
+ converse-register
+ converse-rosterview
+ converse-vcard
+
+An example from `the embedded room demo `_
+
+.. code-block:: javascript
+
+ require(['converse-core', 'converse-muc-embedded'], function (converse) {
+ converse.initialize({
+ // other settings removed for brevity
+ blacklisted_plugins: [
+ 'converse-controlbox',
+ 'converse-dragresize',
+ 'converse-minimize',
+ 'converse-vcard'
+ ],
+ });
+ });
+
+
+whitelisted_plugins
+-------------------
+
+* Default: ``[]``
+
+A list of plugin names that are whitelisted and will therefore be
+initialized once ``converse.initialize`` is called.
+
+From Converse.js 3.0 onwards most of the API is available only to plugins and
+all plugins need to be whitelisted first.
+
+This is done to prevent malicious scripts from using the API to trick users or
+to read their conversations.
+
+By default all the core plugins are already whitelisted.
+
+These are::
+
+ converse-bookmarks
+ converse-chatview
+ converse-controlbox
+ converse-core
+ converse-dragresize
+ converse-headline
+ converse-mam
+ converse-minimize
+ converse-muc
+ converse-notification
+ converse-otr
+ converse-ping
+ converse-register
+ converse-rosterview
+ converse-vcard
+
+If you are using a custom build which excludes some core plugins, then you
+should blacklist them so that malicious scripts can't register their own
+plugins under those names. See `blacklisted_plugins`_ for more info.
+
+An example from `the embedded room demo `_
+
+.. code-block:: javascript
+
+ require(['converse-core', 'converse-muc-embedded'], function (converse) {
+ converse.initialize({
+ // other settings removed for brevity
+ whitelisted_plugins: ['converse-muc-embedded']
+ });
+ });
+
+
xhr_custom_status
-----------------