Various documentation improvements.
This commit is contained in:
parent
7389e1e058
commit
6de6d526b0
@ -63,13 +63,10 @@ Languages increase the size of the Converse.js significantly.
|
|||||||
If you only need one, or a subset of the available languages, it's better to
|
If you only need one, or a subset of the available languages, it's better to
|
||||||
make a custom build which includes only those languages that you need.
|
make a custom build which includes only those languages that you need.
|
||||||
|
|
||||||
Chat Rooms
|
Moderating chat rooms
|
||||||
==========
|
=====================
|
||||||
|
|
||||||
Commands
|
Here are the different commands that may be used to moderate a chat room:
|
||||||
--------
|
|
||||||
|
|
||||||
Here are the different commands that may be used in a chat room:
|
|
||||||
|
|
||||||
+------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+
|
+------------+----------------------------------------------------------------------------------------------+---------------------------------------------------------------+
|
||||||
| Event Type | When is it triggered? | Example (substitue $nickname with an actual user's nickname) |
|
| Event Type | When is it triggered? | Example (substitue $nickname with an actual user's nickname) |
|
||||||
|
@ -22,7 +22,7 @@ its plugin architecture.
|
|||||||
|
|
||||||
To understand how this plugin architecture works, please read the
|
To understand how this plugin architecture works, please read the
|
||||||
`pluggable.js documentation <https://jcbrand.github.io/pluggable.js/>`_
|
`pluggable.js documentation <https://jcbrand.github.io/pluggable.js/>`_
|
||||||
and to grok its inner workins, please refer to the `annotated source code
|
and to understand its inner workins, please refer to the `annotated source code
|
||||||
<https://jcbrand.github.io/pluggable.js/docs/pluggable.html>`_.
|
<https://jcbrand.github.io/pluggable.js/docs/pluggable.html>`_.
|
||||||
|
|
||||||
You register a converse.js plugin as follows:
|
You register a converse.js plugin as follows:
|
||||||
@ -30,7 +30,15 @@ You register a converse.js plugin as follows:
|
|||||||
.. code-block:: javascript
|
.. code-block:: javascript
|
||||||
|
|
||||||
converse.plugins.add('myplugin', {
|
converse.plugins.add('myplugin', {
|
||||||
// Your plugin code goes in here
|
|
||||||
|
initialize: function () {
|
||||||
|
// This method gets called once converse.initialize has been called
|
||||||
|
// and the plugin itself has been loaded.
|
||||||
|
|
||||||
|
// Inside this method, you have access to the closured
|
||||||
|
// _converse object as an attribute on "this".
|
||||||
|
// E.g. this._converse
|
||||||
|
},
|
||||||
});
|
});
|
||||||
|
|
||||||
Security and access to the inner workings
|
Security and access to the inner workings
|
||||||
@ -47,13 +55,29 @@ Within a plugin, you will have access to this internal
|
|||||||
`"closured" <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Closures>`_
|
`"closured" <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Closures>`_
|
||||||
``_converse`` object, which is normally not exposed in the global variable scope.
|
``_converse`` object, which is normally not exposed in the global variable scope.
|
||||||
|
|
||||||
We inner ``_converse`` object is made private in order to safely hide and
|
The inner ``_converse`` object is made private in order to safely hide and
|
||||||
encapsulate sensitive information and methods which should not be exposed
|
encapsulate sensitive information and methods which should not be exposed
|
||||||
to any 3rd-party scripts that might be running in the same page.
|
to any 3rd-party scripts that might be running in the same page.
|
||||||
|
|
||||||
An example plugin
|
An example plugin
|
||||||
-----------------
|
-----------------
|
||||||
|
|
||||||
|
In the example below, you can see how to access 3rd party libraries (such
|
||||||
|
moment, underscore and jQuery) via the ``converse.env`` map.
|
||||||
|
|
||||||
|
There is an ``initialize`` method as you've seen in the example above, and then
|
||||||
|
also an ``overrides`` map, which can be used to override functions, objects or
|
||||||
|
Backbone views and models of Converse.js.
|
||||||
|
|
||||||
|
Use the ``overrides`` functionality with caution. It basically resorts to
|
||||||
|
monkey patching which pollutes the call stack and can make your code fragile
|
||||||
|
and prone to bugs when Converse.js 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.js, and to add
|
||||||
|
your code in event handlers. This is however not always possible, in which case
|
||||||
|
the overrides are a powerful tool.
|
||||||
|
|
||||||
.. code-block:: javascript
|
.. code-block:: javascript
|
||||||
|
|
||||||
(function (root, factory) {
|
(function (root, factory) {
|
||||||
|
@ -2,9 +2,15 @@
|
|||||||
|
|
||||||
<div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/quickstart.rst">Edit me on GitHub</a></div>
|
<div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/quickstart.rst">Edit me on GitHub</a></div>
|
||||||
|
|
||||||
=========================================
|
==========
|
||||||
Quickstart (to get a demo up and running)
|
Quickstart
|
||||||
=========================================
|
==========
|
||||||
|
|
||||||
|
Getting a demo up and running
|
||||||
|
=============================
|
||||||
|
|
||||||
|
Use the content delivery network
|
||||||
|
--------------------------------
|
||||||
|
|
||||||
Converse.js has a `CDN <https://en.wikipedia.org/wiki/Content_delivery_network>`_, provided by `KeyCDN <http://keycdn.com/>`_,
|
Converse.js has a `CDN <https://en.wikipedia.org/wiki/Content_delivery_network>`_, provided by `KeyCDN <http://keycdn.com/>`_,
|
||||||
which hosts its Javascript and CSS files.
|
which hosts its Javascript and CSS files.
|
||||||
@ -14,7 +20,7 @@ The latest versions of these files are available at these URLs:
|
|||||||
* https://cdn.conversejs.org/dist/converse.min.js
|
* https://cdn.conversejs.org/dist/converse.min.js
|
||||||
* https://cdn.conversejs.org/css/converse.min.css
|
* https://cdn.conversejs.org/css/converse.min.css
|
||||||
|
|
||||||
For a specific version of the files, you can put the version in the URL, as so:
|
To load a specific version of Converse.js you can put the version in the URL, like so:
|
||||||
|
|
||||||
* https://cdn.conversejs.org/1.0.3/dist/converse.min.js
|
* https://cdn.conversejs.org/1.0.3/dist/converse.min.js
|
||||||
* https://cdn.conversejs.org/1.0.3/css/converse.min.css
|
* https://cdn.conversejs.org/1.0.3/css/converse.min.css
|
||||||
@ -26,12 +32,14 @@ You can include these two URLs inside the *<head>* element of your website via t
|
|||||||
<link rel="stylesheet" type="text/css" media="screen" href="https://cdn.conversejs.org/css/converse.min.css">
|
<link rel="stylesheet" type="text/css" media="screen" href="https://cdn.conversejs.org/css/converse.min.css">
|
||||||
<script src="https://cdn.conversejs.org/dist/converse.min.js"></script>
|
<script src="https://cdn.conversejs.org/dist/converse.min.js"></script>
|
||||||
|
|
||||||
You need to initialize Converse.js with configuration settings according to your requirements.
|
Initializing Converse.js
|
||||||
|
------------------------
|
||||||
|
|
||||||
Please refer to the :ref:`configuration-variables` section for info on all the available configuration settings.
|
You'll then need to initialize Converse.js with configuration settings relevant to your requirements.
|
||||||
|
Refer to the :ref:`configuration-variables` section for info on all the available configuration settings.
|
||||||
|
|
||||||
To configure and initialize Converse.js, put the following inline Javascript code at the
|
To quickly get started, you can put the following Javascript code at the
|
||||||
bottom of your page (after the closing *</body>* element).
|
bottom of your page (after the closing *</body>* element):
|
||||||
|
|
||||||
.. code-block:: javascript
|
.. code-block:: javascript
|
||||||
|
|
||||||
@ -39,9 +47,7 @@ bottom of your page (after the closing *</body>* element).
|
|||||||
require(['converse'], function (converse) {
|
require(['converse'], function (converse) {
|
||||||
converse.initialize({
|
converse.initialize({
|
||||||
bosh_service_url: 'https://bind.conversejs.org', // Please use this connection manager only for testing purposes
|
bosh_service_url: 'https://bind.conversejs.org', // Please use this connection manager only for testing purposes
|
||||||
i18n: locales.en, // Refer to ./locale/locales.js to see which locales are supported
|
|
||||||
show_controlbox_by_default: true,
|
show_controlbox_by_default: true,
|
||||||
roster_groups: true
|
|
||||||
});
|
});
|
||||||
});
|
});
|
||||||
</script>
|
</script>
|
||||||
@ -49,14 +55,51 @@ bottom of your page (after the closing *</body>* element).
|
|||||||
The `index.html <https://github.com/jcbrand/converse.js/blob/master/index.html>`_ file inside the
|
The `index.html <https://github.com/jcbrand/converse.js/blob/master/index.html>`_ file inside the
|
||||||
Converse.js repository may serve as a nice usable example.
|
Converse.js repository may serve as a nice usable example.
|
||||||
|
|
||||||
These minified `.js` and `.css` files provide the same demo-like functionality as is available
|
Alternative builds of Converse.js
|
||||||
|
=================================
|
||||||
|
|
||||||
|
The minified ``.js`` and ``.css`` files provide the same functionality as is available
|
||||||
on the `conversejs.org <http://conversejs.org>`_ website. Useful for testing or demoing.
|
on the `conversejs.org <http://conversejs.org>`_ website. Useful for testing or demoing.
|
||||||
|
|
||||||
You'll most likely want to implement some kind of persistent single-session solution for
|
Alternative builds are however also available via the CDN.
|
||||||
your website, where users authenticate once in your website and then stay
|
|
||||||
logged in to their XMPP session upon the next page reload.
|
|
||||||
|
|
||||||
For more info on this, read: :ref:`session-support`.
|
Mobile build
|
||||||
|
------------
|
||||||
|
|
||||||
|
Besides the default build mentioned above, there is a build intended for mobile
|
||||||
|
websites, called ``converse-mobile.min.js``.
|
||||||
|
Take a look at the ``mobile.html`` file in the Converse.js repository
|
||||||
|
for an example of this build being used. There's an additional CSS file called
|
||||||
|
``mobile.min.css`` which should be used with the mobile build.
|
||||||
|
|
||||||
|
When you load `conversejs.org <https://conversejs.org>`_ with a mobile device
|
||||||
|
then the mobile Javascript build and its CSS will be used.
|
||||||
|
|
||||||
|
Excluding 3rd party dependencies
|
||||||
|
--------------------------------
|
||||||
|
|
||||||
|
Then there is also a build that contains no 3rd party dependencies, called
|
||||||
|
``converse-no-dependencies.min.js`` and which is used in the ``non_amd.html``
|
||||||
|
page in the repository.
|
||||||
|
|
||||||
|
Excluding only jQuery
|
||||||
|
---------------------
|
||||||
|
|
||||||
|
Lastly there is a build called ``converse.nojquery.min.js`` which excludes only
|
||||||
|
jQuery but still includes all other 3rd party dependencies.
|
||||||
|
|
||||||
|
Where to go from here?
|
||||||
|
======================
|
||||||
|
|
||||||
|
You might want to implement some kind of persistent single-session solution for
|
||||||
|
your website, where users authenticate once in your website and are then
|
||||||
|
automatically logged in to the XMPP server as well. For more info on how this
|
||||||
|
can be achieved, read: :ref:`session-support`.
|
||||||
|
|
||||||
|
Perhaps you want to create your own custom build of Converse.js? Then head over
|
||||||
|
to the :doc:`builds` section, or more generally the :doc:`development`
|
||||||
|
documentation.
|
||||||
|
|
||||||
|
Do you want to know how to theme Converse.js? Then read the :doc:`theming`
|
||||||
|
documentation.
|
||||||
|
|
||||||
You might also want to have more fine-grained control of what gets included in
|
|
||||||
the minified Javascript file. Read :doc:`builds` for more info on how to do that.
|
|
||||||
|
@ -2,6 +2,8 @@
|
|||||||
|
|
||||||
<div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/theming.rst">Edit me on GitHub</a></div>
|
<div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/theming.rst">Edit me on GitHub</a></div>
|
||||||
|
|
||||||
|
.. _theming:
|
||||||
|
|
||||||
=======
|
=======
|
||||||
Theming
|
Theming
|
||||||
=======
|
=======
|
||||||
|
Loading…
Reference in New Issue
Block a user