Merge remote-tracking branch 'origin/master'

docs/source/builds.rst

@@ -47,7 +47,7 @@ This command does the following:
 
 * Also, the CSS files in the ``./css`` directory will be minified.
 
-The Javascript build files are contained in the ``./dist`` directory:
+The JavaScript build files are contained in the ``./dist`` directory:
 
 .. code-block:: bash
 

docs/source/configuration.rst

@@ -261,7 +261,7 @@ If ``authentication`` is set to ``anonymous``, then you will also need to provid
 server's domain via the `jid`_ setting.
 
 This is a useful setting if you'd like to create a custom login form in your
-website. You'll need to write some Javascript to accept that custom form's
+website. You'll need to write some JavaScript to accept that custom form's
 login credentials, then you can pass those credentials (``jid`` and
 ``password``) to ``converse.initialize`` to start converse.js and log the user
 into their XMPP account.
@@ -1341,7 +1341,7 @@ xhr_custom_status
 * Default:  ``false``
 
 .. note::
-    XHR stands for XMLHTTPRequest, and is meant here in the AJAX sense (Asynchronous Javascript and XML).
+    XHR stands for XMLHTTPRequest, and is meant here in the AJAX sense (Asynchronous JavaScript and XML).
 
 This option will let converse.js make an AJAX POST with your changed custom chat status to a
 remote server.
@@ -1350,7 +1350,7 @@ xhr_custom_status_url
 ---------------------
 
 .. note::
-    XHR stands for XMLHTTPRequest, and is meant here in the AJAX sense (Asynchronous Javascript and XML).
+    XHR stands for XMLHTTPRequest, and is meant here in the AJAX sense (Asynchronous JavaScript and XML).
 
 * Default:  Empty string
 
@@ -1367,7 +1367,7 @@ xhr_user_search
 * Default:  ``false``
 
 .. note::
-    XHR stands for XMLHTTPRequest, and is meant here in the AJAX sense (Asynchronous Javascript and XML).
+    XHR stands for XMLHTTPRequest, and is meant here in the AJAX sense (Asynchronous JavaScript and XML).
 
 There are two ways to add users.
 
@@ -1392,7 +1392,7 @@ xhr_user_search_url
 -------------------
 
 .. note::
-    XHR stands for XMLHTTPRequest, and is meant here in the AJAX sense (Asynchronous Javascript and XML).
+    XHR stands for XMLHTTPRequest, and is meant here in the AJAX sense (Asynchronous JavaScript and XML).
 
 * Default:  Empty string
 

docs/source/developer_api.rst

@@ -50,7 +50,7 @@ Public API methods
 ==================
 
 Publich API methods are those methods that are accessible on the global
-``window.converse`` object. They are public, because any Javascript in the page
+``window.converse`` object. They are public, because any JavaScript in the page
 can call them. Public methods therefore don't expose any sensitive or closured
 data. To do that, you'll need to create a plugin, which has access to the
 private API method.
@@ -325,7 +325,7 @@ room under the  ``with`` key.
 
 The ``start`` and ``end`` parameters are used to query for messages
 within a certain timeframe. The passed in date values may either be ISO8601
-formatted date strings, or Javascript Date objects.
+formatted date strings, or JavaScript Date objects.
 
 .. code-block:: javascript
 
@@ -1070,7 +1070,7 @@ Example:
 The **listen** grouping
 -----------------------
 
-Converse.js emits events to which you can subscribe from your own Javascript.
+Converse.js emits events to which you can subscribe from your own JavaScript.
 
 Concerning events, the following methods are available under the "listen"
 grouping:

docs/source/developer_guidelines.rst

@@ -9,7 +9,7 @@ Developer guidelines
    :depth: 2
    :local:
 
-If you want to work with the non-minified Javascript and CSS files you'll soon
+If you want to work with the non-minified JavaScript and CSS files you'll soon
 notice that there are references to a missing *node_modules* directory.
 Please follow the instructions below to create these directories and fetch Converse's
 3rd-party dependencies.
@@ -97,7 +97,7 @@ Without AMD and require.js
 Converse.js can also be used without require.js. If you for some reason prefer
 to use it this way, please refer to
 `non_amd.html <https://github.com/jcbrand/converse.js/blob/master/non_amd.html>`_
-for an example of how and in what order all the Javascript files that converse.js
+for an example of how and in what order all the JavaScript files that converse.js
 depends on need to be loaded.
 
 Brief description of converse.js's dependencies

docs/source/features.rst

@@ -21,7 +21,7 @@ The OTR protocol not only **encrypts your messages**, it provides ways to
 **plausible deniability** and **perfect forward secrecy** by generating
 new encryption keys for each conversation.
 
-In its current state, Javascript cryptography is fraught with dangers and
+In its current state, JavaScript cryptography is fraught with dangers and
 challenges that make it impossible to reach the same standard of security that
 is available with native "desktop" software.
 
@@ -29,8 +29,8 @@ This is due to its runtime malleability, the way it is "installed" (e.g.
 served) and the browser's lack of cryptographic primitives needed to implement
 secure crypto.
 
-For harsh but fairly valid criticism of Javascript cryptography, read:
+For harsh but fairly valid criticism of JavaScript cryptography, read:
-`Javascript Cryptography Considered Harmful <http://www.matasano.com/articles/javascript-cryptography/>`_.
+`JavaScript Cryptography Considered Harmful <http://www.matasano.com/articles/javascript-cryptography/>`_.
 
 To get an idea on how this applies to OTR support in Converse.js, please read
 `my thoughts on it <https://opkode.com/media/blog/2013/11/11/conversejs-otr-support>`_.

docs/source/index.rst

@@ -23,7 +23,7 @@ Introduction
 ============
 
 Converse.js is a free and open-source `XMPP <http://xmpp.org/about-xmpp/>`_
-chat client written in Javascript which can be tightly integrated into any website.
+chat client written in JavaScript which can be tightly integrated into any website.
 
 The benefit of using converse.js as opposed to relying on a SaaS
 (software-as-a-service) solution, is that your users can have a much more

docs/source/plugin_development.rst

@@ -14,24 +14,36 @@ Writing a plugin
 Introduction
 ------------
 
-Developers are able to extend and override the objects, functions and the
+Converse.js is exposes a plugin architecture which allows developers to modify
-Backbone models and views that make up converse.js by means of writing plugins.
+and extend its functionality.
+
+Specifically, plugins enable developers to extend and override existing objects,
+functions and `Backbone <http://backbonejs.org/>`_ models and views that make up
+Converse.js, and also give them the ability to write new models and views.
+
+Various core features of Converse.js, such as
+`Message Archive Management <https://xmpp.org/extensions/xep-0313.html>`_ and
+`Group chats <https://xmpp.org/extensions/xep-0045.html>`_ are implemented
+as plugins, thereby showing their power and flexibility.
 
 Converse.js uses `pluggable.js <https://github.com/jcbrand/pluggable.js/>`_ as
 its plugin architecture.
 
-To understand how this plugin architecture works, please read the
+To more deeply understand how this plugin architecture works, please read the
 `pluggable.js documentation <https://jcbrand.github.io/pluggable.js/>`_
 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,
+Playing with a Converse.js plugin in JSFiddle
-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
+Because Converse.js consists only of JavaScript, HTML and CSS (with no backend
-initialized and when a message gets rendered: https://jsfiddle.net/4drfaok0/15/
+code required like PHP, Python or Ruby) it runs fine in JSFiddle.
 
+Here's an Fiddle with a Converse.js plugin that calls `alert` once it gets
+initialized and also when a chat message gets rendered:
+
+https://jsfiddle.net/4drfaok0/15/
 
 Registering a plugin
 --------------------
@@ -234,7 +246,7 @@ A full example plugin
 	(function (root, factory) {
 		if (typeof define === 'function' && define.amd) {
 			// AMD. Register as a module called "myplugin"
-            define("myplugin", ["converse"], factory);
+			define("<%= name %>", ["converse"], factory);
 		} else {
 			// Browser globals. If you're not using a module loader such as require.js,
 			// then this line below executes. Make sure that your plugin's <script> tag
@@ -256,121 +268,130 @@ A full example plugin
 			moment = converse.env.moment;
 
 		// The following line registers your plugin.
-        converse.plugins.add('myplugin', {
+		converse.plugins.add("<%= name %>", {
 
-            initialize: function () {
+			/* Optional dependencies are other plugins which might be
-                // Converse.js's plugin mechanism will call the initialize
+			* overridden or relied upon, and therefore need to be loaded before
-                // method on any plugin (if it exists) as soon as the plugin has
+			* this plugin. They are called "optional" because they might not be
-                // been loaded.
+			* available, in which case any overrides applicable to them will be
+			* ignored.
+			*
+			* NB: These plugins need to have already been loaded via require.js.
+			*
+			* It's possible to make optional dependencies non-optional.
+			* If the setting "strict_plugin_dependencies" is set to true,
+			* an error will be raised if the plugin is not found.
+			*/
+			'optional_dependencies': [],
 
+			/* Converse.js's plugin mechanism will call the initialize
+			* method on any plugin (if it exists) as soon as the plugin has
+			* been loaded.
+			*/
+			'initialize': function () {
+				/* Inside this method, you have access to the private
+				* `_converse` object.
+				*/
 				var _converse = this._converse;
+				_converse.log("The <%= name %> plugin is being initialized");
 
-                // Inside this method, you have access to the closured
+				/* From the `_converse` object you can get any configuration
-                // _converse object, from which you can get any configuration
+				* options that the user might have passed in via
-                // options that the user might have passed in via
+				* `converse.initialize`. These values are stored in the
-                // converse.initialize. These values are stored in the
+				* "user_settings" attribute.
-                // "user_settings" attribute.
+				*
-
+				* You can also specify new configuration settings for this
-                // We can also specify new configuration settings for this
+				* plugin, or override the default values of existing
-                // plugin, or override the default values of existing
+				* configuration settings. This is done like so:
-                // configuration settings. This is done like so:
+				*/
-
 				_converse.api.settings.update({
-                    'initialize_message': 'Initialized', // New configuration setting
+					'initialize_message': 'Initializing <%= name %>!'
-                    'auto_subscribe': true, // New default value for an
-                                            // existing "core" configuration setting
 				});
 
-                // The user can then pass in values for the configuration
+				/* The user can then pass in values for the configuration
-                // settings when `converse.initialize` gets called.
+				* settings when `converse.initialize` gets called.
-                // For example:
+				* For example:
-                //
+				*
-                // converse.initialize({
+				*      converse.initialize({
-                //      "initialize_message": "My plugin has been initialized"
+				*           "initialize_message": "My plugin has been initialized"
-                // });
+				*      });
-                //
+				*
-                // And the configuration setting is then available via the
+				* And the configuration setting is then available via the
-                // `user_settings` attribute:
+				* `user_settings` attribute:
+				*/
+				alert(this._converse.user_settings.initialize_message);
 
-                // alert(this._converse.user_settings.initialize_message);
+				/* Besides `_converse.api.settings.update`, there is also a
-
+				* `_converse.api.promises.add` method, which allows you to
-                // Besides `_converse.api.settings.update`, there is also a
+				* add new promises that your plugin is obligated to fulfill.
-                // `_converse.api.promises.add` method, which allows you to
+				*
-                // add new promises that your plugin is obligated to fulfill.
+				* This method takes a string or a list of strings which
-
+				* represent the promise names:
-                // This method takes a string or a list of strings which
+				*
-                // represent the promise names.
+				*      _converse.api.promises.add('myPromise');
-
+				*
-                _converse.api.promises.add('operationCompleted');
+				* Your plugin should then, when appropriate, resolve the
-
+				* promise by calling `_converse.api.emit`, which will also
-                // Your plugin should then, when appropriate, resolve the
+				* emit an event with the same name as the promise.
-                // promise by calling `_converse.api.emit`, which will also
+				* For example:
-                // emit an event with the same name as the promise.
+				*
-                // For example:
+				*      _converse.api.emit('operationCompleted');
-                // _converse.api.emit('operationCompleted');
+				*
-                //
+				* Other plugins can then either listen for the event
-                // Other plugins can then either listen for the event
+				* `operationCompleted` like so:
-                // `operationCompleted` like so:
+				*
-                // `_converse.api.listen.on('operationCompleted', function { ... });`
+				*      _converse.api.listen.on('operationCompleted', function { ... });
-                //
+				*
-                // or they can wait for the promise to be fulfilled like so:
+				* or they can wait for the promise to be fulfilled like so:
-                // `_converse.api.waitUntil('operationCompleted', function { ... });`
+				*
+				*      _converse.api.waitUntil('operationCompleted', function { ... });
+				*/
 			},
 
-            // Optional dependencies are other plugins which might be
+			/* If you want to override some function or a Backbone model or
-            // overridden or relied upon, and therefore need to be loaded before
+			* view defined elsewhere in converse.js, then you do that under
-            // this plugin. They are called "optional" because they might not be
+			* the "overrides" namespace.
-            // available, in which case any overrides applicable to them will be
+			*/
-            // ignored.
+			'overrides': {
-
+				/* For example, the private *_converse* object has a
-            // It's possible however to make optional dependencies non-optional.
+				* method "onConnected". You can override that method as follows:
-            // If the setting "strict_plugin_dependencies" is set to true,
+				*/
-            // an error will be raised if the plugin is not found.
+				'onConnected': function () {
-            //
-            // NB: These plugins need to have already been loaded via require.js.
-
-            optional_dependencies: [],
-
-            overrides: {
-                // If you want to override some function or a Backbone model or
-                // view defined elsewhere in converse.js, then you do that under
-                // this "overrides" namespace.
-
-                // For example, the inner protected *_converse* object has a
-                // method "onConnected". You can override that method as follows:
-                onConnected: function () {
 					// Overrides the onConnected method in converse.js
 
 					// Top-level functions in "overrides" are bound to the
 					// inner "_converse" object.
 					var _converse = this;
 
-                    // Your custom code comes here.
+					// Your custom code can come here ...
-                    // ...
 
 					// You can access the original function being overridden
 					// via the __super__ attribute.
 					// Make sure to pass on the arguments supplied to this
 					// function and also to apply the proper "this" object.
 					_converse.__super__.onConnected.apply(this, arguments);
+
+					// Your custom code can come here ...
 				},
 
-                XMPPStatus: {
+				/* Override converse.js's XMPPStatus Backbone model so that we can override the
-                    // Override converse.js's XMPPStatus Backbone model so that we can override the
+				* function that sends out the presence stanza.
-                    // function that sends out the presence stanza.
+				*/
-                    sendPresence: function (type, status_message, jid) {
+				'XMPPStatus': {
+					'sendPresence': function (type, status_message, jid) {
 						// The "_converse" object is available via the __super__
 						// attribute.
 						var _converse = this.__super__._converse;
 
-                        // Custom code can come here
+						// Custom code can come here ...
-                        // ...
 
 						// You can call the original overridden method, by
 						// accessing it via the __super__ attribute.
 						// When calling it, you need to apply the proper
 						// context as reference by the "this" variable.
 						this.__super__.sendPresence.apply(this, arguments);
+
+						// Custom code can come here ...
 					}
 				}
 			}

docs/source/quickstart.rst

@@ -13,7 +13,7 @@ Use the content delivery network
 --------------------------------
 
 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.
 
 The latest versions of these files are available at these URLs:
 
@@ -44,7 +44,7 @@ Initializing Converse.js
 You'll then need to initialize Converse.js with configuration settings relevant to your requirements.
 Refer to the :ref:`configuration-settings` section for info on all the available configuration settings.
 
-To quickly get started, you can put the following 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)::
 
     <script>
@@ -75,7 +75,7 @@ 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.
+then the mobile JavaScript build and its CSS will be used.
 
 Excluding 3rd party dependencies
 --------------------------------

docs/source/security.rst

@@ -57,7 +57,7 @@ Addititional measures
 Besides the measures mentioned above, integrators and hosts can also take
 further security precautions.
 
-The most effective is to avoid serving untrusted 3rd party Javascript (e.g.
+The most effective is to avoid serving untrusted 3rd party JavaScript (e.g.
 advertisements and analytics).
 
 Another option is to forego the use of a global ``converse`` object (which

docs/source/style_guide.rst

@@ -14,10 +14,10 @@ Software Style Guide
     rely on a transpiler and still support older browsers.
 
 Most of the style guide recommendations here come from Douglas Crockford's book
-`Javascript, the good parts <http://shop.oreilly.com/product/9780596517748.do>`_
+`JavaScript, the good parts <http://shop.oreilly.com/product/9780596517748.do>`_
 
 This style guide is fairly opinionated. Some of these opinions perhaps don't
-conform to your expectations on how Javascript code should look like.
+conform to your expectations on how JavaScript code should look like.
 I apologize for that. However, for the sake of sanity, consistency and having
 code that is pleasing to the eye, please stick to these guidelines.
 
@@ -103,7 +103,7 @@ and method invocations.
 Checking for equality
 ---------------------
 
-Javascript has a strict ``===`` and less strict ``==`` equality operator. The
+JavaScript has a strict ``===`` and less strict ``==`` equality operator. The
 stricter equality operator also does type checking. To avoid subtle bugs when
 doing comparisons, always use the strict equality check.
 

docs/source/theming.rst

@@ -71,7 +71,7 @@ Creating dist files
 ===================
 
 Once you've themed converse.js, you'll want to create new minified distribution
-files of all the Javascript and CSS.
+files of all the JavaScript and CSS.
 
 Please refer to the :doc:`builds` section for information on how this is done.
 

docs/source/translations.rst

@@ -59,7 +59,7 @@ translated into, do the following
 
 Please make sure to add the following attributes at the top of the file (under
 *Content-Transfer-Encoding*). They are required as configuration settings for Jed,
-the Javascript translations library that we're using.
+the JavaScript translations library that we're using.
 
 .. code-block:: po
 
@@ -90,7 +90,7 @@ The resulting `.po` file is then what gets translated.
 
 
 -----------------------------------------------------
-Generating a Javascript file from a translations file
+Generating a JavaScript file from a translations file
 -----------------------------------------------------
 
 Unfortunately `Jed <http://slexaxton.github.io/Jed>`_, which we use for

docs/source/troubleshooting.rst

@@ -42,13 +42,13 @@ more likely on the XMPP server's end (perhaps a misconfiguration?). If they
 **are** logged, then there might be a bug or misconfiguration in Converse.js.
 
 
-Conflicts with other Javascript libraries
+Conflicts with other JavaScript libraries
 =========================================
 
 Problem: 
 ---------
 
-You are using other Javascript libraries (like JQuery plugins), and
+You are using other JavaScript libraries (like JQuery plugins), and
 get errors like these in your browser console::
 
     Uncaught TypeError: Object [object Object] has no method 'xxx' from example.js

index.html

@@ -12,11 +12,11 @@
     <link type="text/css" rel="stylesheet" media="screen" href="css/bootstrap.min.css" />
     <link type="text/css" rel="stylesheet" media="screen" href="css/font-awesome.min.css" />
     <link type="text/css" rel="stylesheet" media="screen" href="css/theme.min.css" />
-    <link type="text/css" rel="stylesheet" media="screen" href="css/converse.css" />
     <script type="text/javascript" src="analytics.js"></script>
     <noscript><p><img src="//stats.opkode.com/piwik.php?idsite=1" style="border:0;" alt="" /></p></noscript>
 	<script src="src/website.js"></script>
     <![if gte IE 11]>
+    <link type="text/css" rel="stylesheet" media="screen" href="css/converse.css" />
 	<script src="dist/converse.min.js"></script>
     <![endif]>
 </head>