Two websocket related changes. updates #204

* Handle case where no websocket url is specified.
* Update the documentation w.r.t. websockets

converse.js

@@ -5100,10 +5100,12 @@
                 if (!this.bosh_service_url && ! this.websocket_url) {
                     throw("Error: you must supply a value for the bosh_service_url or websocket_url");
                 }
-                if ('WebSocket' in window || 'MozWebSocket' in window) {
+                if (('WebSocket' in window || 'MozWebSocket' in window) && this.websocket_url) {
                     this.connection = new Strophe.Connection(this.websocket_url);
-                } else {
+                } else if (this.bosh_service_url) {
                     this.connection = new Strophe.Connection(this.bosh_service_url);
+                } else {
+                    throw("Error: this browser does not support websockets and no bosh_service_url specified.");
                 }
                 this.setUpXMLLogging();
 

docs/source/configuration.rst

@@ -103,11 +103,20 @@ If true, the user will automatically subscribe back to any contact requests.
 bosh_service_url
 ----------------
 
-Connections to an XMPP server depend on a BOSH connection manager which acts as
-a middle man between HTTP and XMPP.
+Default: ``undefined``
 
+To connect to an XMPP server over HTTP you need a `BOSH <https://en.wikipedia.org/wiki/BOSH>`_
+connection manager which acts as a middle man between the HTTP and XMPP
+protocols.
+
+The bosh_service_url setting takes the URL of a BOSH connection manager.
+
+Please refer to your XMPP server's documentation on how to enable BOSH.
 For more information, read this blog post: `Which BOSH server do you need? <http://metajack.im/2008/09/08/which-bosh-server-do-you-need>`_
 
+A more modern alternative to BOSH is to use `websockets <https://developer.mozilla.org/en/docs/WebSockets>`_.
+Please see the :ref:`websocket-url` configuration setting.
+
 cache_otr_key
 -------------
 
@@ -145,6 +154,8 @@ Default: ``e.g. conversejs.org``
 
 The placeholder text shown in the domain input on the registration form.
 
+.. _`keepalive`:
+
 keepalive
 ---------
 
@@ -158,6 +169,13 @@ See also:
 * :ref:`session-support`
 * `Using prebind in connection with keepalive`_
 
+.. note::
+    Currently the "keepalive" setting only works with BOSH and not with
+    websockets. This is because XMPP over websocket does not use the same
+    session token as with BOSH. A possible solution for this is to implement
+    `XEP-0198 <http://xmpp.org/extensions/xep-0198.html>`_, specifically
+    with regards to "stream resumption".
+
 message_carbons
 ---------------
 
@@ -257,6 +275,8 @@ it in both formats as ``http://yoursite.com/sounds/msg_received.mp3`` and
 
 ``http://yoursite.com`` should of course be your site's URL.
 
+.. _`prebind`:
+
 prebind
 --------
 
@@ -452,6 +472,33 @@ Allows you to show or hide buttons on the chat boxes' toolbars.
 * toggle_participants:
     Shows a button for toggling (i.e. showing/hiding) the list of participants in a chat room.
 
+.. _`websocket-url`:
+
+websocket_url
+-------------
+
+Default: ``undefined``
+
+This option is used to specify a 
+`websocket <https://developer.mozilla.org/en/docs/WebSockets>`_ URI to which
+converse.js can connect to.
+
+Websockets provide a more modern and effective two-way communication protocol
+between the browser and a server, effectively emulating TCP at the application
+layer and therefore overcoming many of the problems with existing long-polling
+techniques for bidirectional HTTP (such as `BOSH <https://en.wikipedia.org/wiki/BOSH>`_).
+
+Please refer to your XMPP server's documentation on how to enable websocket
+support.
+
+.. note::
+    Please note that not older browsers do not support websockets. For older
+    browsers you'll want to specify a BOSH URL. See the :ref:`bosh-service-url`
+    configuration setting).
+    
+.. note::
+    Converse.js does not yet support "keepalive" with websockets.
+
 xhr_custom_status
 -----------------
 

docs/source/setup.rst

@@ -120,15 +120,15 @@ Apache
 Single Session Support
 ----------------------
 
-Server-side authentication
-==========================
+Server-side authentication (prebind)
+====================================
 
-It's possible to enable single-site login, whereby users already
-authenticated in your website will also automatically be logged in on the chat server,
+It's possible to enable shared sessions whereby users already
+authenticated in your website will also automatically be logged in on the XMPP server,
 
-This session should also persist across page loads. In other words, we don't
-want the user to have to give their chat credentials every time they reload the
-page.
+This session can be made to persist across page loads. In other words, we want
+a user to automatically be logged in to chat when they log in to the website,
+and we want their chat session to persist across page loads.
 
 To do this you will require a `BOSH server <http://xmpp.org/about-xmpp/technology-overview/bosh/>`_
 for converse.js to connect to (see the :ref:`bosh-service-url` under :ref:`configuration-variables`)
@@ -193,6 +193,12 @@ These values are then passed to converse.js's ``initialize`` method.
    Additionally you need to pass in valid **jid**, **sid**, **rid** and
    **bosh_service_url** values.
 
+   The :ref:`prebind` configuration setting can be used together with the
+   :ref:`keepalive` setting. This means you only have to prebind once for the
+   first page the user loads and not anymore for subsequent pages.
+
+   For more info, please refer to the :ref:`configuration-variables` section.
+
 
 Example code for server-side prebinding
 =======================================