瀏覽代碼

Various documentation improvements.

JC Brand 8 年之前
父節點
當前提交
6de6d526b0
共有 4 個文件被更改,包括 92 次插入26 次删除
  1. 3 6
      docs/source/features.rst
  2. 27 3
      docs/source/plugin_development.rst
  3. 60 17
      docs/source/quickstart.rst
  4. 2 0
      docs/source/theming.rst

+ 3 - 6
docs/source/features.rst

@@ -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 in a chat room:
+Here are the different commands that may be used to moderate 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)  |

+ 27 - 3
docs/source/plugin_development.rst

@@ -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) {

+ 60 - 17
docs/source/quickstart.rst

@@ -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
-bottom of your page (after the closing *</body>* element).
+To quickly get started, you can put the following Javascript code at the
+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
-your website, where users authenticate once in your website and then stay
-logged in to their XMPP session upon the next page reload.
+Alternative builds are however also available via the CDN.
+
+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.
 
 
-For more info on this, read: :ref:`session-support`.
+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 - 0
docs/source/theming.rst

@@ -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
 =======
 =======