Skip to content

C
converse.js
Commit a2be2567 authored by JC Brand's avatar JC Brand
Browse files
Options

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.
parent a2d27ee9
Show whitespace changes
Inline Side-by-side
Showing with 140 additions and 106 deletions
converse.js
View file @ a2be2567
......@@ -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) {
} 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
View file @ a2be2567
......@@ -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
View file @ a2be2567
......@@ -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
View file @ a2be2567
......@@ -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
View file @ a2be2567
......@@ -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>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7