Allow auto_login also with a provided jid and password.

* Update the docs to mention the new ``authentication`` option.
* Update failing tests due to ``prebind`` being replaced with ``authentication``.
* Rename 'manual' value for authentication to 'login' since it's used in both manual and auto cases.

converse.js

@@ -182,7 +182,7 @@
 
         // Constants
         // ---------
-        var MANUAL = "manual";
+        var LOGIN = "login";
         var ANONYMOUS  = "anonymous";
         var PREBIND = "prebind";
 
@@ -261,7 +261,8 @@
             message_carbons: false,
             no_trimming: false, // Set to true for phantomjs tests (where browser apparently has no width)
             play_sounds: false,
-            authentication: 'manual', // Available values are "manual", "prebind", "anonymous".
+            password: undefined,
+            authentication: 'login', // Available values are "login", "prebind", "anonymous".
             prebind: false, // XXX: Deprecated, use "authentication" instead.
             prebind_url: null,
             providers_link: 'https://xmpp.net/directory.php', // Link to XMPP providers shown on registration page
@@ -5160,7 +5161,7 @@
             initialize: function (cfg) {
                 cfg.$parent.html(this.$el.html(
                     converse.templates.login_panel({
-                        'MANUAL': MANUAL,
+                        'LOGIN': LOGIN,
                         'ANONYMOUS': ANONYMOUS,
                         'PREBIND': PREBIND,
                         'auto_login': converse.auto_login,
@@ -5378,8 +5379,19 @@
                         if (rid && sid && jid) {
                             this.session.save({rid: rid}); // The RID needs to be increased with each request.
                             this.connection.attach(jid, sid, rid, this.onConnect);
-                        } else if (this.authentication === ANONYMOUS && this.auto_login) {
-                            this.connection.connect(this.jid, null, this.onConnect);
+                        } else if (this.auto_login) {
+                            if (!this.jid) {
+                                throw new Error("initConnection: If you use auto_login, you also need to provide a jid value");
+                            }
+                            if (this.authentication === ANONYMOUS) {
+                                this.connection.connect(this.jid, null, this.onConnect);
+                            } else if (this.authentication === LOGIN) {
+                                if (!this.password) {
+                                    throw new Error("initConnection: If you use auto_login and "+
+                                        "authentication='login' then you also need to provide a password.");
+                                }
+                                this.connection.connect(this.jid, this.password, this.onConnect);
+                            }
                         }
                     }
                 } else if (this.authentication == "prebind") {

docs/source/configuration.rst

@@ -28,10 +28,77 @@ JS file so that it will include the new settings. Please refer to the
 Configuration variables
 =======================
 
+authentication
+--------------
+
+* Default:  ``login``
+* Allowed values: `login`_, `anonymous`_, `prebind`_
+
+This option states the way converse.js will authenticate.
+
+login
+~~~~~
+
+The default means is ``login``, which means that the user either logs in manually with their
+username and password, or automatically if used together with ``auto_login=true``
+and ``jid`` and ``password`` values. See `auto_login`_.
+
+anonymous
+~~~~~~~~~
+
+This enables anonymous login if the XMPP server supports it. This option can be
+used together with `auto_login`_ to automatically and anonymously log a user in
+as soon as the page loads.
+
+prebind
+~~~~~~~
+
+See also: :ref:`session-support`
+
+Use this option when you want to attach to an existing XMPP
+`BOSH <https://en.wikipedia.org/wiki/BOSH>`_ session.
+
+Usually a BOSH session is set up server-side in your web app.
+
+Attaching to an existing BOSH session that was set up server-side is useful
+when you want to maintain a persistent single session for your users instead of
+requiring them to log in manually.
+
+When a BOSH session is initially created, you'll receive three tokens.
+A JID (jabber ID), SID (session ID) and RID (Request ID).
+
+Converse.js needs these tokens in order to attach to that same session.
+
+There are two complementary configuration settings to ``prebind``.
+They are :ref:`keepalive` and :ref:`prebind_url`.
+
+``keepalive`` can be used keep the session alive without having to pass in
+new RID and SID tokens to ``converse.initialize`` every time you reload the page.
+This removes the need to set up a new BOSH session every time a page loads.
+You do however still need to supply the user's JID so that converse.js can be
+sure that the session it's resuming is for the right user.
+
+``prebind_url`` lets you specify a URL which converse.js will call whenever a
+new BOSH session needs to be set up.
+
+Here's an example of converse.js being initialized with these three options:
+
+.. code-block:: javascript
+
+    converse.initialize({
+        bosh_service_url: 'https://bind.example.com',
+        keepalive: true,
+        jid: 'me@example.com',
+        authentication: 'prebind',
+        prebind_url: 'http://example.com/api/prebind',
+        allow_logout: false
+    });
+
+
 allow_contact_removal
 ---------------------
 
-Default:  ``true``
+* Default:  ``true``
 
 Allow the user to remove roster contacts by clicking on the delete icon
 (i.e. traschcan) next to a contact's name in the roster.
@@ -39,7 +106,7 @@ Allow the user to remove roster contacts by clicking on the delete icon
 allow_contact_requests
 ----------------------
 
-Default:  ``true``
+* Default:  ``true``
 
 Allow users to add one another as contacts. If this is set to false, the
 **Add a contact** widget, **Contact Requests** and **Pending Contacts** roster
@@ -49,7 +116,7 @@ ignored.
 allow_muc
 ---------
 
-Default:  ``true``
+* Default:  ``true``
 
 Allow multi-user chat (muc) in chatrooms. Setting this to ``false`` will remove
 the ``Chatrooms`` tab from the control box.
@@ -57,14 +124,14 @@ the ``Chatrooms`` tab from the control box.
 allow_otr
 ---------
 
-Default:  ``true``
+* Default:  ``true``
 
 Allow Off-the-record encryption of single-user chat messages.
 
 allow_registration
 ------------------
 
-Default:  ``true``
+* Default:  ``true``
 
 Support for `XEP-0077: In band registration <http://xmpp.org/extensions/xep-0077.html>`_
 
@@ -73,14 +140,14 @@ Allow XMPP account registration showing the corresponding UI register form inter
 animate
 -------
 
-Default:  ``true``
+* Default:  ``true``
 
 Show animations, for example when opening and closing chat boxes.
 
 auto_list_rooms
 ---------------
 
-Default:  ``false``
+* Default:  ``false``
 
 If true, and the XMPP server on which the current user is logged in supports
 multi-user chat, then a list of rooms on that server will be fetched.
@@ -91,10 +158,24 @@ For each room on the server a query is made to fetch further details (e.g.
 features, number of occupants etc.), so on servers with many rooms this
 option will create lots of extra connection traffic.
 
+auto_login
+----------
+
+* Default:  ``false``
+
+This option can be used to let converse.js automatically log the user in as
+soon as the page loads.
+
+It should be used either with ``authentication`` set to ``anonymous`` or to
+``login``.
+
+If ``authentication`` is set to ``login``, then you will also need to provide a
+valid ``jid`` and ``password`` values.
+
 auto_reconnect
 --------------
 
-Default:  ``true``
+* Default:  ``true``
 
 Automatically reconnect to the XMPP server if the connection drops
 unexpectedly.
@@ -102,7 +183,7 @@ unexpectedly.
 auto_subscribe
 --------------
 
-Default:  ``false``
+* Default:  ``false``
 
 If true, the user will automatically subscribe back to any contact requests.
 
@@ -111,7 +192,7 @@ If true, the user will automatically subscribe back to any contact requests.
 bosh_service_url
 ----------------
 
-Default: ``undefined``
+* 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
@@ -128,7 +209,7 @@ Please see the :ref:`websocket-url` configuration setting.
 cache_otr_key
 -------------
 
-Default:  ``false``
+* Default:  ``false``
 
 Let the `OTR (Off-the-record encryption) <https://otr.cypherpunks.ca>`_ private
 key be cached in your browser's session storage.
@@ -151,14 +232,14 @@ This setting can only be used together with ``allow_otr = true``.
 debug
 -----
 
-Default:  ``false``
+* Default:  ``false``
 
 If set to true, debugging output will be logged to the browser console.
 
 domain_placeholder
 ------------------
 
-Default: ``e.g. conversejs.org``
+* Default: ``e.g. conversejs.org``
 
 The placeholder text shown in the domain input on the registration form.
 
@@ -178,12 +259,12 @@ with `prebind`_.
 keepalive
 ---------
 
-Default:    ``true``
+* Default:    ``true``
 
 Determines whether Converse.js will maintain the chat session across page
 loads.
 
-This setting should also be used in conjunction with :ref:`prebind`.
+This setting should also be used in conjunction with ``authentication`` set to `prebind`_.
 
 When using ``keepalive`` and ``prebind``, you will have to provide the `jid`_
 of the current user to ensure that a cached session is only resumed if it
@@ -192,7 +273,6 @@ belongs to the current user.
 See also:
 
 * :ref:`session-support`
-* `Using prebind in connection with keepalive`_
 
 .. note::
     Currently the "keepalive" setting only works with BOSH and not with
@@ -204,7 +284,7 @@ See also:
 message_carbons
 ---------------
 
-Default:  ``false``
+* Default:  ``false``
 
 Support for `XEP-0280: Message Carbons <https://xmpp.org/extensions/xep-0280.html>`_
 
@@ -225,7 +305,7 @@ solve this problem, while `forward_messages`_ uses
 expose_rid_and_sid
 ------------------
 
-Default:  ``false``
+* Default:  ``false``
 
 Allow the prebind tokens, RID (request ID) and SID (session ID), to be exposed
 globally via the API. This allows other scripts served on the same page to use
@@ -237,7 +317,7 @@ and inject fake chat messages.
 forward_messages
 ----------------
 
-Default:  ``false``
+* Default:  ``false``
 
 If set to ``true``, sent messages will also be forwarded to the sending user's
 bare JID (their Jabber ID independent of any chat clients aka resources).
@@ -261,7 +341,7 @@ logged in user, otherwise the user's vCard will be fetched.
 hide_muc_server
 ---------------
 
-Default:  ``false``
+* Default:  ``false``
 
 Hide the ``server`` input field of the form inside the ``Room`` panel of the
 controlbox. Useful if you want to restrict users to a specific XMPP server of
@@ -270,7 +350,7 @@ your choosing.
 hide_offline_users
 ------------------
 
-Default:  ``false``
+* Default:  ``false``
 
 If set to ``true``, then don't show offline users.
 
@@ -285,7 +365,7 @@ Specify the locale/language. The language must be in the ``locales`` object. Ref
 play_sounds
 -----------
 
-Default:  ``false``
+* Default:  ``false``
 
 Plays a notification sound when you receive a personal message or when your
 nickname is mentioned in a chat room.
@@ -300,62 +380,6 @@ 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
---------
-
-Default:  ``false``
-
-See also: :ref:`session-support`
-
-Use this option when you want to attach to an existing XMPP
-`BOSH <https://en.wikipedia.org/wiki/BOSH>`_ session.
-
-Usually a BOSH session is set up server-side in your web app.
-
-Attaching to an existing BOSH session that was set up server-side is useful
-when you want to maintain a persistent single session for your users instead of
-requiring them to log in manually.
-
-When a BOSH session is initially created, you'll receive three tokens.
-A JID (jabber ID), SID (session ID) and RID (Request ID).
-
-Converse.js needs these tokens in order to attach to that same session.
-
-There are two complementary configuration settings to ``prebind``.
-They are :ref:`keepalive` and :ref:`prebind_url`.
-
-``keepalive`` can be used keep the session alive without having to pass in
-new RID and SID tokens to ``converse.initialize`` every time you reload the page.
-This removes the need to set up a new BOSH session every time a page loads.
-You do however still need to supply the user's JID so that converse.js can be
-sure that the session it's resuming is for the right user.
-
-``prebind_url`` lets you specify a URL which converse.js will call whenever a
-new BOSH session needs to be set up.
-
-Here's an example of converse.js being initialized with these three options:
-
-.. code-block:: javascript
-
-    converse.initialize({
-        bosh_service_url: 'https://bind.example.com',
-        keepalive: true,
-        jid: me@example.com,
-        prebind: true,
-        prebind_url: 'http://example.com/api/prebind',
-        allow_logout: false
-    });
-
-.. note:: The ``prebind_url`` configuration setting is new in version 0.9 and
-    simplifies the code needed to set up and maintain prebinded sessions.
-
-    When using ``prebind``, ``prebind_url`` and ``keepalive``, you don't need
-    to manually pass in the RID, SID tokens anymore, but you still need to
-    provide the JID.
-
-
 .. _`prebind_url`:
 
 prebind_url
@@ -366,7 +390,7 @@ prebind_url
 
 See also: :ref:`session-support`
 
-This setting should be used in conjunction with :ref:`prebind` and :ref:`keepalive`.
+This setting should be used in conjunction with ``authentication`` set to `prebind` and :ref:`keepalive` set to ``true``.
 
 It allows you to specify a URL which converse.js will call when it needs to get
 the RID and SID (Request ID and Session ID) tokens of a BOSH connection, which
@@ -384,7 +408,7 @@ three tokens::
 providers_link
 --------------
 
-Default:  ``https://xmpp.net/directory.php``
+* Default:  ``https://xmpp.net/directory.php``
 
 The hyperlink on the registration form which points to a directory of public
 XMPP servers.
@@ -393,7 +417,7 @@ XMPP servers.
 roster_groups
 -------------
 
-Default:  ``false``
+* Default:  ``false``
 
 If set to ``true``, converse.js will show any roster groups you might have
 configured.
@@ -406,7 +430,7 @@ configured.
 show_controlbox_by_default
 --------------------------
 
-Default:  ``false``
+* Default:  ``false``
 
 The "controlbox" refers to the special chatbox containing your contacts roster,
 status widget, chatrooms and other controls.
@@ -420,7 +444,7 @@ page load.
 show_only_online_users
 ----------------------
 
-Default:  ``false``
+* Default:  ``false``
 
 If set to ``true``, only online users will be shown in the contacts roster.
 Users with any other status (e.g. away, busy etc.) will not be shown.
@@ -428,7 +452,7 @@ Users with any other status (e.g. away, busy etc.) will not be shown.
 storage
 -------
 
-Default: ``session``
+* Default: ``session``
 
 Valid options: ``session``, ``local``.
 
@@ -457,7 +481,7 @@ Data in localStorage on the other hand is kept indefinitely.
 use_otr_by_default
 ------------------
 
-Default:  ``false``
+* Default:  ``false``
 
 If set to ``true``, Converse.js will automatically try to initiate an OTR (off-the-record)
 encrypted chat session every time you open a chat box.
@@ -465,7 +489,7 @@ encrypted chat session every time you open a chat box.
 use_vcards
 ----------
 
-Default:  ``true``
+* Default:  ``true``
 
 Determines whether the XMPP server will be queried for roster contacts' VCards
 or not. VCards contain extra personal information such as your fullname and
@@ -474,7 +498,7 @@ avatar image.
 visible_toolbar_buttons
 -----------------------
 
-Default:
+* Default:
 
 .. code-block:: javascript
 
@@ -508,7 +532,7 @@ Allows you to show or hide buttons on the chat boxes' toolbars.
 websocket_url
 -------------
 
-Default: ``undefined``
+* Default: ``undefined``
 
 This option is used to specify a 
 `websocket <https://developer.mozilla.org/en/docs/WebSockets>`_ URI to which
@@ -533,7 +557,7 @@ support.
 xhr_custom_status
 -----------------
 
-Default:  ``false``
+* Default:  ``false``
 
 .. note::
     XHR stands for XMLHTTPRequest, and is meant here in the AJAX sense (Asynchronous Javascript and XML).
@@ -547,7 +571,7 @@ xhr_custom_status_url
 .. note::
     XHR stands for XMLHTTPRequest, and is meant here in the AJAX sense (Asynchronous Javascript and XML).
 
-Default:  Empty string
+* Default:  Empty string
 
 Used only in conjunction with ``xhr_custom_status``.
 
@@ -559,7 +583,7 @@ The message itself is sent in the request under the key ``msg``.
 xhr_user_search
 ---------------
 
-Default:  ``false``
+* Default:  ``false``
 
 .. note::
     XHR stands for XMLHTTPRequest, and is meant here in the AJAX sense (Asynchronous Javascript and XML).
@@ -582,7 +606,7 @@ xhr_user_search_url
 .. note::
     XHR stands for XMLHTTPRequest, and is meant here in the AJAX sense (Asynchronous Javascript and XML).
 
-Default:  Empty string
+* Default:  Empty string
 
 Used only in conjunction with ``xhr_user_search``.
 

docs/source/quickstart.rst

@@ -28,12 +28,8 @@ bottom of your page (after the closing *</body>* element).
 
     require(['converse'], function (converse) {
         converse.initialize({
-            auto_list_rooms: false,
-            auto_subscribe: false,
             bosh_service_url: 'https://bind.conversejs.org', // Please use this connection manager only for testing purposes
-            hide_muc_server: false,
             i18n: locales.en, // Refer to ./locale/locales.js to see which locales are supported
-            prebind: false,
             show_controlbox_by_default: true,
             roster_groups: true
         });

spec/converse.js

@@ -20,37 +20,39 @@
 
             describe("with prebind", function () {
                 it("needs a jid when also using keepalive", function () {
+                    var authentication = converse.authentication;
                     var connection = converse.connection;
                     var jid = converse.jid;
                     converse.bosh_service_url = "localhost";
                     converse.connection = undefined;
                     converse.jid = undefined;
                     converse.keepalive = true;
-                    converse.prebind = true;
+                    converse.authentication = "prebind";
                     expect(converse.initConnection.bind(converse)).toThrow(
                         new Error("initConnection: when using 'keepalive' with 'prebind, you must supply the JID of the current user."));
+                    converse.authentication= authentication;
                     converse.bosh_service_url = undefined;
                     converse.connection = connection;
                     converse.jid = jid;
                     converse.keepalive = undefined;
-                    converse.prebind = undefined;
                 });
 
                 it("needs jid, rid and sid values when not using keepalive", function () {
+                    var authentication = converse.authentication;
                     var connection = converse.connection;
                     var jid = converse.jid;
                     converse.bosh_service_url = "localhost";
                     converse.connection = undefined;
                     converse.jid = undefined;
                     converse.keepalive = false;
-                    converse.prebind = true;
+                    converse.authentication = "prebind";
                     expect(converse.initConnection.bind(converse)).toThrow(
                         new Error("initConnection: If you use prebind and not keepalive, then you MUST supply JID, RID and SID values"));
+                    converse.authentication= authentication;
                     converse.bosh_service_url = undefined;
                     converse.connection = connection;
                     converse.jid = jid;
                     converse.keepalive = undefined;
-                    converse.prebind = undefined;
                 });
             });
         });

src/templates/login_panel.html

@@ -3,7 +3,7 @@
         <span class="spinner login-submit"/>
     {[ } ]}
     {[ if (!auto_login) { ]}
-        {[ if (authentication == MANUAL) { ]}
+        {[ if (authentication == LOGIN) { ]}
             <label>{{label_username}}</label>
             <input type="email" name="jid" placeholder="user@server">
             <label>{{label_password}}</label>