Update the docs and add section about sound notifications. updates #62
This commit is contained in:
JC Brand
parent
8061171b9c
commit
83c68696cd
Binary file not shown.
@ -17,16 +17,16 @@ Quickstart (to get a demo up and running)
|
||||
|
||||
When you download a specific release of *Converse.js* there will be two minified files inside the zip file.
|
||||
|
||||
* converse.min.js
|
||||
* converse.min.css
|
||||
* builds/converse.min.js
|
||||
* css/converse.min.css
|
||||
|
||||
You can include these two files inside the *<head>* element of your website via the *script* and *link*
|
||||
tags:
|
||||
|
||||
::
|
||||
|
||||
<link rel="stylesheet" type="text/css" media="screen" href="converse.min.css">
|
||||
<script src="converse.min.js"></script>
|
||||
<link rel="stylesheet" type="text/css" media="screen" href="css/converse.min.css">
|
||||
<script src="builds/converse.min.js"></script>
|
||||
|
||||
You need to initialize Converse.js with configuration settings particular to
|
||||
your requirements.
|
||||
@ -34,7 +34,7 @@ your requirements.
|
||||
Please refer to the `Configuration variables`_ section further below for info on
|
||||
all the available configuration settings.
|
||||
|
||||
To do this, put the following inline Javascript code at the
|
||||
To configure Converse.js, put the following inline Javascript code at the
|
||||
bottom of your page (after the closing *</body>* element).
|
||||
|
||||
::
|
||||
@ -48,12 +48,12 @@ bottom of your page (after the closing *</body>* element).
|
||||
i18n: locales.en, // Refer to ./locale/locales.js to see which locales are supported
|
||||
prebind: false,
|
||||
show_controlbox_by_default: true,
|
||||
xhr_user_search: false
|
||||
roster_groups: true
|
||||
});
|
||||
});
|
||||
|
||||
The `index.html <https://github.com/jcbrand/converse.js/blob/master/index.html>`_ file inside the
|
||||
Converse.js repository serves as a nice usable example of this.
|
||||
Converse.js repository may serve as a nice usable example.
|
||||
|
||||
These minified files provide the same demo-like functionality as is available
|
||||
on the `conversejs.org <http://conversejs.org>`_ website. Useful for testing or demoing, but not very
|
||||
@ -79,7 +79,7 @@ website, *Converse.js* is not really meant to be a "Software-as-a-service" (SaaS
|
||||
webchat.
|
||||
|
||||
Instead, its goal is to provide the means for website owners to add a tightly
|
||||
integrated instant messaging service to their own sites.
|
||||
integrated instant messaging service to their own websites.
|
||||
|
||||
As a website owner, you are expected to host *Converse.js* yourself, and to do some legwork to
|
||||
properly configure and integrate it into your site.
|
||||
@ -114,8 +114,8 @@ You can find a list of public XMPP servers/providers on `xmpp.net`_ and a list o
|
||||
servers that you can set up yourself on `xmpp.org`_.
|
||||
|
||||
|
||||
Connection Manager
|
||||
==================
|
||||
A BOSH Connection Manager
|
||||
=========================
|
||||
|
||||
Your website and *Converse.js* use `HTTP`_ as protocol to communicate with
|
||||
the webserver. HTTP connections are stateless and usually shortlived.
|
||||
@ -127,18 +127,25 @@ To enable a web application like *Converse.js* to communicate with an XMPP
|
||||
server, we need a proxy in the middle that can act as a bridge between the two
|
||||
protocols.
|
||||
|
||||
This is the job of a connection manager. A connection manager can be either a
|
||||
standalone application or part of an XMPP server. `ejabberd`_ for example,
|
||||
includes a connection manager (but you have to enable it).
|
||||
The `index.html <https://github.com/jcbrand/converse.js/blob/master/index.html>`_ file inside the
|
||||
|
||||
The demo on the `Converse.js homepage`_ uses a a connection manager located at https://bind.conversejs.org.
|
||||
This connection manager is for testing purposes only, please don't use it in
|
||||
production.
|
||||
This is the job of a connection manager. A connection manager can be either a
|
||||
standalone application or part of an XMPP server. Popular XMPP servers such as
|
||||
`ejabberd <http://www.ejabberd.im>`_, `prosody <http://prosody.im/doc/setting_up_bosh>`_ and
|
||||
`openfire <http://www.igniterealtime.org/projects/openfire/>`_ all include their own connection managers
|
||||
(but you usually have to enable them in the configuration).
|
||||
|
||||
Standalone connection managers also exist, see for example `Punjab <https://github.com/twonds/punjab>`_.
|
||||
|
||||
The demo on the `Converse.js homepage`_ uses a connection manager located at https://bind.conversejs.org.
|
||||
This connection manager is available for testing purposes only, please don't use it in production.
|
||||
|
||||
Overcoming cross-domain request restrictions
|
||||
--------------------------------------------
|
||||
|
||||
The domain of the *Converse.js* demo is *conversejs.org*, but the domain of the connection manager is *opkode.im*.
|
||||
Lets say your domain is *example.org*, but the domain of your connection
|
||||
manager is *example.com*.
|
||||
|
||||
HTTP requests are made by *Converse.js* to the connection manager via XmlHttpRequests (XHR).
|
||||
Until recently, it was not possible to make such requests to a different domain
|
||||
than the one currently being served (to prevent XSS attacks).
|
||||
@ -281,67 +288,6 @@ Example code for server-side prebinding
|
||||
See this `example Django application`_ by Jack Moffitt.
|
||||
|
||||
|
||||
Setting up a BOSH server
|
||||
------------------------
|
||||
|
||||
The `Movim <http://movim.eu/>`_ project wiki has a very thorough page on setting up a BOSH server for
|
||||
a wide variety of standalone or XMPP servers.
|
||||
|
||||
http://wiki.movim.eu/manual:bosh_servers
|
||||
|
||||
Facebook integration
|
||||
====================
|
||||
|
||||
.. Note ::
|
||||
It should be possible to integrate Converse.js with Facebook chat, and
|
||||
below I'll provide some tips and documentation on how to achieve this. That
|
||||
said, I don't have a Facebook account and therefore haven't tried to do
|
||||
this myself. Feedback and patches from people who have succesfully done this
|
||||
will be appreciated.
|
||||
|
||||
Converse.js uses `Strophe.js <http://strophe.im/strophejs>`_ to connect and
|
||||
communicate with the XMPP server. One nice thing about Strophe.js is that it
|
||||
can be extended via `plugins <http://github.com/strophe/strophejs-plugins>`_.
|
||||
|
||||
Here is a `plugin for authenticating with facebook
|
||||
<https://github.com/kissrobber/turedsocial/blob/master/strophe-plugins/src/facebook.js>`_.
|
||||
|
||||
You will need your own BOSH connection manager to act as a proxy between
|
||||
Converse.js/Strophe.js and Facebook's XMPP server. That is because Facebook's
|
||||
XMPP server doesn't support BOSH natively.
|
||||
|
||||
The BOSH connection manager that I make available for
|
||||
testing purposes (at https://bind.conversejs.org) uses `Punjab <https://github.com/twonds/punjab>`_,
|
||||
although there are quite a few other options available as well.
|
||||
|
||||
When you configure Converse.js, via its ``initialize`` method, you must specify the
|
||||
`bosh_service_url`_ value, which is to be your BOSH connection manager.
|
||||
|
||||
Please note, to enable Facebook integration, you'll have to
|
||||
get your hands dirty and modify Converse.js's code, so that it calls the
|
||||
``facebookConnect`` method of the plugin above.
|
||||
|
||||
The plugin above gives the following code example for you to meditate upon:
|
||||
|
||||
::
|
||||
|
||||
connection = new Strophe.Connection("http://localhost:5280/bosh");
|
||||
connection.facebookConnect(
|
||||
"12345@chat.facebook.com",
|
||||
onConnectFacebook,
|
||||
300,
|
||||
1,
|
||||
'5e64a30272af065bd72258c565a03f2f',
|
||||
'8147a27e4a7f9b55ffc85c2683f9529a',
|
||||
FB.getSession().session_key
|
||||
);
|
||||
|
||||
The connection is already created inside Converse.js, so the
|
||||
``facebookConnect`` method needs to also be called from there.
|
||||
|
||||
If someone submits a sane patch that does the above, I'll be happy to merge it.
|
||||
Until then, people will have to do this themselves.
|
||||
|
||||
========
|
||||
Features
|
||||
========
|
||||
@ -375,6 +321,25 @@ For now, suffice to say that although its useful to have OTR support in
|
||||
Converse.js in order to avoid most eavesdroppers, if you need serious
|
||||
communications privacy, then you're much better off using native software.
|
||||
|
||||
Sound Notifications
|
||||
===================
|
||||
|
||||
From version 0.8.1 Converse.js can play a sound notification when you receive a
|
||||
message.
|
||||
|
||||
For more info, please see the `play_sounds`_ configuration setting.
|
||||
|
||||
Multilingual Support
|
||||
====================
|
||||
|
||||
Converse.js is translated into multiple languages. The default build,
|
||||
``converse.min.js``, includes all languages.
|
||||
|
||||
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
|
||||
make a custom build which includes only those languages that you need.
|
||||
|
||||
===========
|
||||
Development
|
||||
===========
|
||||
@ -982,6 +947,21 @@ i18n
|
||||
Specify the locale/language. The language must be in the ``locales`` object. Refer to
|
||||
``./locale/locales.js`` to see which locales are supported.
|
||||
|
||||
play_sounds
|
||||
-----------
|
||||
|
||||
Default: ``false``
|
||||
|
||||
Inside the ``./sounds`` directory of the Converse.js repo, you'll see MP3 and Ogg
|
||||
formatted sound files. We need both, because neither format is supported by all browsers.
|
||||
|
||||
For now, sound files are looked up by convention, not configuration. So to have
|
||||
a sound play when a message is received, make sure that your webserver serves
|
||||
it in both formats as ``http://yoursite.com/sounds/msg_received.mp3`` and
|
||||
``http://yoursite.com/sounds/msg_received.ogg``.
|
||||
|
||||
``http://yoursite.com`` should of course be your site's URL.
|
||||
|
||||
prebind
|
||||
--------
|
||||
|
||||
|
||||
@ -57,87 +57,88 @@
|
||||
<div class="contents local topic" id="table-of-contents">
|
||||
<p class="topic-title first">Table of Contents</p>
|
||||
<ul class="simple">
|
||||
<li><a class="reference internal" href="#quickstart-to-get-a-demo-up-and-running" id="id5">Quickstart (to get a demo up and running)</a></li>
|
||||
<li><a class="reference internal" href="#introduction" id="id6">Introduction</a></li>
|
||||
<li><a class="reference internal" href="#what-you-will-need" id="id7">What you will need</a><ul>
|
||||
<li><a class="reference internal" href="#an-xmpp-jabber-server" id="id8">An XMPP/Jabber server</a></li>
|
||||
<li><a class="reference internal" href="#connection-manager" id="id9">Connection Manager</a><ul>
|
||||
<li><a class="reference internal" href="#overcoming-cross-domain-request-restrictions" id="id10">Overcoming cross-domain request restrictions</a></li>
|
||||
<li><a class="reference internal" href="#quickstart-to-get-a-demo-up-and-running" id="id7">Quickstart (to get a demo up and running)</a></li>
|
||||
<li><a class="reference internal" href="#introduction" id="id8">Introduction</a></li>
|
||||
<li><a class="reference internal" href="#what-you-will-need" id="id9">What you will need</a><ul>
|
||||
<li><a class="reference internal" href="#an-xmpp-jabber-server" id="id10">An XMPP/Jabber server</a></li>
|
||||
<li><a class="reference internal" href="#a-bosh-connection-manager" id="id11">A BOSH Connection Manager</a><ul>
|
||||
<li><a class="reference internal" href="#overcoming-cross-domain-request-restrictions" id="id12">Overcoming cross-domain request restrictions</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#server-side-authentication" id="id11">Server-side authentication</a><ul>
|
||||
<li><a class="reference internal" href="#prebinding-and-single-session-support" id="id12">Prebinding and Single Session Support</a></li>
|
||||
<li><a class="reference internal" href="#example-code-for-server-side-prebinding" id="id13">Example code for server-side prebinding</a></li>
|
||||
<li><a class="reference internal" href="#setting-up-a-bosh-server" id="id14">Setting up a BOSH server</a></li>
|
||||
<li><a class="reference internal" href="#server-side-authentication" id="id13">Server-side authentication</a><ul>
|
||||
<li><a class="reference internal" href="#prebinding-and-single-session-support" id="id14">Prebinding and Single Session Support</a></li>
|
||||
<li><a class="reference internal" href="#example-code-for-server-side-prebinding" id="id15">Example code for server-side prebinding</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#facebook-integration" id="id15">Facebook integration</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#features" id="id16">Features</a><ul>
|
||||
<li><a class="reference internal" href="#off-the-record-encryption" id="id17">Off-the-record encryption</a></li>
|
||||
<li><a class="reference internal" href="#sound-notifications" id="id18">Sound Notifications</a></li>
|
||||
<li><a class="reference internal" href="#multilingual-support" id="id19">Multilingual Support</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#development" id="id18">Development</a><ul>
|
||||
<li><a class="reference internal" href="#install-the-development-and-front-end-dependencies" id="id19">Install the development and front-end dependencies</a></li>
|
||||
<li><a class="reference internal" href="#with-amd-and-require-js-recommended" id="id20">With AMD and require.js (recommended)</a></li>
|
||||
<li><a class="reference internal" href="#without-amd-and-require-js" id="id21">Without AMD and require.js</a></li>
|
||||
<li><a class="reference internal" href="#before-submitting-a-pull-request" id="id22">Before submitting a pull request</a><ul>
|
||||
<li><a class="reference internal" href="#add-tests-for-your-bugfix-or-feature" id="id23">Add tests for your bugfix or feature</a></li>
|
||||
<li><a class="reference internal" href="#check-that-the-tests-pass" id="id24">Check that the tests pass</a></li>
|
||||
<li><a class="reference internal" href="#check-your-code-for-errors-or-bad-habits-by-running-jshint" id="id25">Check your code for errors or bad habits by running JSHint</a></li>
|
||||
<li><a class="reference internal" href="#development" id="id20">Development</a><ul>
|
||||
<li><a class="reference internal" href="#install-the-development-and-front-end-dependencies" id="id21">Install the development and front-end dependencies</a></li>
|
||||
<li><a class="reference internal" href="#with-amd-and-require-js-recommended" id="id22">With AMD and require.js (recommended)</a></li>
|
||||
<li><a class="reference internal" href="#without-amd-and-require-js" id="id23">Without AMD and require.js</a></li>
|
||||
<li><a class="reference internal" href="#before-submitting-a-pull-request" id="id24">Before submitting a pull request</a><ul>
|
||||
<li><a class="reference internal" href="#add-tests-for-your-bugfix-or-feature" id="id25">Add tests for your bugfix or feature</a></li>
|
||||
<li><a class="reference internal" href="#check-that-the-tests-pass" id="id26">Check that the tests pass</a></li>
|
||||
<li><a class="reference internal" href="#check-your-code-for-errors-or-bad-habits-by-running-jshint" id="id27">Check your code for errors or bad habits by running JSHint</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#minification" id="id26">Minification</a><ul>
|
||||
<li><a class="reference internal" href="#minifying-javascript-and-css" id="id27">Minifying Javascript and CSS</a></li>
|
||||
<li><a class="reference internal" href="#minification" id="id28">Minification</a><ul>
|
||||
<li><a class="reference internal" href="#minifying-javascript-and-css" id="id29">Minifying Javascript and CSS</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#translations" id="id28">Translations</a></li>
|
||||
<li><a class="reference internal" href="#translations" id="id30">Translations</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#troubleshooting" id="id29">Troubleshooting</a><ul>
|
||||
<li><a class="reference internal" href="#conflicts-with-other-javascript-libraries" id="id30">Conflicts with other Javascript libraries</a><ul>
|
||||
<li><a class="reference internal" href="#problem" id="id31">Problem:</a></li>
|
||||
<li><a class="reference internal" href="#solution" id="id32">Solution:</a></li>
|
||||
<li><a class="reference internal" href="#troubleshooting" id="id31">Troubleshooting</a><ul>
|
||||
<li><a class="reference internal" href="#conflicts-with-other-javascript-libraries" id="id32">Conflicts with other Javascript libraries</a><ul>
|
||||
<li><a class="reference internal" href="#problem" id="id33">Problem:</a></li>
|
||||
<li><a class="reference internal" href="#solution" id="id34">Solution:</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#events" id="id33">Events</a><ul>
|
||||
<li><a class="reference internal" href="#event-methods" id="id34">Event Methods</a></li>
|
||||
<li><a class="reference internal" href="#event-types" id="id35">Event Types</a></li>
|
||||
<li><a class="reference internal" href="#events" id="id35">Events</a><ul>
|
||||
<li><a class="reference internal" href="#event-methods" id="id36">Event Methods</a></li>
|
||||
<li><a class="reference internal" href="#event-types" id="id37">Event Types</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#configuration" id="id36">Configuration</a><ul>
|
||||
<li><a class="reference internal" href="#configuration-variables" id="id37">Configuration variables</a><ul>
|
||||
<li><a class="reference internal" href="#allow-contact-requests" id="id38">allow_contact_requests</a></li>
|
||||
<li><a class="reference internal" href="#allow-muc" id="id39">allow_muc</a></li>
|
||||
<li><a class="reference internal" href="#id2" id="id40">allow_muc</a></li>
|
||||
<li><a class="reference internal" href="#animate" id="id41">animate</a></li>
|
||||
<li><a class="reference internal" href="#auto-list-rooms" id="id42">auto_list_rooms</a></li>
|
||||
<li><a class="reference internal" href="#auto-reconnect" id="id43">auto_reconnect</a></li>
|
||||
<li><a class="reference internal" href="#auto-subscribe" id="id44">auto_subscribe</a></li>
|
||||
<li><a class="reference internal" href="#bosh-service-url" id="id45">bosh_service_url</a></li>
|
||||
<li><a class="reference internal" href="#cache-otr-key" id="id46">cache_otr_key</a></li>
|
||||
<li><a class="reference internal" href="#debug" id="id47">debug</a></li>
|
||||
<li><a class="reference internal" href="#message-carbons" id="id48">message_carbons</a></li>
|
||||
<li><a class="reference internal" href="#expose-rid-and-sid" id="id49">expose_rid_and_sid</a></li>
|
||||
<li><a class="reference internal" href="#forward-messages" id="id50">forward_messages</a></li>
|
||||
<li><a class="reference internal" href="#fullname" id="id51">fullname</a></li>
|
||||
<li><a class="reference internal" href="#hide-muc-server" id="id52">hide_muc_server</a></li>
|
||||
<li><a class="reference internal" href="#i18n" id="id53">i18n</a></li>
|
||||
<li><a class="reference internal" href="#prebind" id="id54">prebind</a></li>
|
||||
<li><a class="reference internal" href="#roster-groups" id="id55">roster_groups</a></li>
|
||||
<li><a class="reference internal" href="#show-controlbox-by-default" id="id56">show_controlbox_by_default</a></li>
|
||||
<li><a class="reference internal" href="#show-only-online-users" id="id57">show_only_online_users</a></li>
|
||||
<li><a class="reference internal" href="#storage" id="id58">storage</a></li>
|
||||
<li><a class="reference internal" href="#use-otr-by-default" id="id59">use_otr_by_default</a></li>
|
||||
<li><a class="reference internal" href="#use-vcards" id="id60">use_vcards</a></li>
|
||||
<li><a class="reference internal" href="#visible-toolbar-buttons" id="id61">visible_toolbar_buttons</a></li>
|
||||
<li><a class="reference internal" href="#xhr-custom-status" id="id62">xhr_custom_status</a></li>
|
||||
<li><a class="reference internal" href="#xhr-custom-status-url" id="id63">xhr_custom_status_url</a></li>
|
||||
<li><a class="reference internal" href="#xhr-user-search" id="id64">xhr_user_search</a></li>
|
||||
<li><a class="reference internal" href="#xhr-user-search-url" id="id65">xhr_user_search_url</a></li>
|
||||
<li><a class="reference internal" href="#configuration" id="id38">Configuration</a><ul>
|
||||
<li><a class="reference internal" href="#configuration-variables" id="id39">Configuration variables</a><ul>
|
||||
<li><a class="reference internal" href="#allow-contact-requests" id="id40">allow_contact_requests</a></li>
|
||||
<li><a class="reference internal" href="#allow-muc" id="id41">allow_muc</a></li>
|
||||
<li><a class="reference internal" href="#id3" id="id42">allow_muc</a></li>
|
||||
<li><a class="reference internal" href="#animate" id="id43">animate</a></li>
|
||||
<li><a class="reference internal" href="#auto-list-rooms" id="id44">auto_list_rooms</a></li>
|
||||
<li><a class="reference internal" href="#auto-reconnect" id="id45">auto_reconnect</a></li>
|
||||
<li><a class="reference internal" href="#auto-subscribe" id="id46">auto_subscribe</a></li>
|
||||
<li><a class="reference internal" href="#bosh-service-url" id="id47">bosh_service_url</a></li>
|
||||
<li><a class="reference internal" href="#cache-otr-key" id="id48">cache_otr_key</a></li>
|
||||
<li><a class="reference internal" href="#debug" id="id49">debug</a></li>
|
||||
<li><a class="reference internal" href="#message-carbons" id="id50">message_carbons</a></li>
|
||||
<li><a class="reference internal" href="#expose-rid-and-sid" id="id51">expose_rid_and_sid</a></li>
|
||||
<li><a class="reference internal" href="#forward-messages" id="id52">forward_messages</a></li>
|
||||
<li><a class="reference internal" href="#fullname" id="id53">fullname</a></li>
|
||||
<li><a class="reference internal" href="#hide-muc-server" id="id54">hide_muc_server</a></li>
|
||||
<li><a class="reference internal" href="#i18n" id="id55">i18n</a></li>
|
||||
<li><a class="reference internal" href="#play-sounds" id="id56">play_sounds</a></li>
|
||||
<li><a class="reference internal" href="#prebind" id="id57">prebind</a></li>
|
||||
<li><a class="reference internal" href="#roster-groups" id="id58">roster_groups</a></li>
|
||||
<li><a class="reference internal" href="#show-controlbox-by-default" id="id59">show_controlbox_by_default</a></li>
|
||||
<li><a class="reference internal" href="#show-only-online-users" id="id60">show_only_online_users</a></li>
|
||||
<li><a class="reference internal" href="#storage" id="id61">storage</a></li>
|
||||
<li><a class="reference internal" href="#use-otr-by-default" id="id62">use_otr_by_default</a></li>
|
||||
<li><a class="reference internal" href="#use-vcards" id="id63">use_vcards</a></li>
|
||||
<li><a class="reference internal" href="#visible-toolbar-buttons" id="id64">visible_toolbar_buttons</a></li>
|
||||
<li><a class="reference internal" href="#xhr-custom-status" id="id65">xhr_custom_status</a></li>
|
||||
<li><a class="reference internal" href="#xhr-custom-status-url" id="id66">xhr_custom_status_url</a></li>
|
||||
<li><a class="reference internal" href="#xhr-user-search" id="id67">xhr_user_search</a></li>
|
||||
<li><a class="reference internal" href="#xhr-user-search-url" id="id68">xhr_user_search_url</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
@ -145,23 +146,23 @@
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="quickstart-to-get-a-demo-up-and-running">
|
||||
<h1><a class="toc-backref" href="#id5">Quickstart (to get a demo up and running)</a><a class="headerlink" href="#quickstart-to-get-a-demo-up-and-running" title="Permalink to this headline">¶</a></h1>
|
||||
<h1><a class="toc-backref" href="#id7">Quickstart (to get a demo up and running)</a><a class="headerlink" href="#quickstart-to-get-a-demo-up-and-running" title="Permalink to this headline">¶</a></h1>
|
||||
<p>When you download a specific release of <em>Converse.js</em> there will be two minified files inside the zip file.</p>
|
||||
<ul class="simple">
|
||||
<li>converse.min.js</li>
|
||||
<li>converse.min.css</li>
|
||||
<li>builds/converse.min.js</li>
|
||||
<li>css/converse.min.css</li>
|
||||
</ul>
|
||||
<p>You can include these two files inside the <em><head></em> element of your website via the <em>script</em> and <em>link</em>
|
||||
tags:</p>
|
||||
<div class="highlight-python"><div class="highlight"><pre><link rel="stylesheet" type="text/css" media="screen" href="converse.min.css">
|
||||
<script src="converse.min.js"></script>
|
||||
<div class="highlight-python"><div class="highlight"><pre><link rel="stylesheet" type="text/css" media="screen" href="css/converse.min.css">
|
||||
<script src="builds/converse.min.js"></script>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>You need to initialize Converse.js with configuration settings particular to
|
||||
your requirements.</p>
|
||||
<p>Please refer to the <a class="reference internal" href="#configuration-variables">Configuration variables</a> section further below for info on
|
||||
all the available configuration settings.</p>
|
||||
<p>To do this, put the following inline Javascript code at the
|
||||
<p>To configure Converse.js, put the following inline Javascript code at the
|
||||
bottom of your page (after the closing <em></body></em> element).</p>
|
||||
<div class="highlight-python"><div class="highlight"><pre>require(['converse'], function (converse) {
|
||||
converse.initialize({
|
||||
@ -172,13 +173,13 @@ bottom of your page (after the closing <em></body></em> element).</p>
|
||||
i18n: locales.en, // Refer to ./locale/locales.js to see which locales are supported
|
||||
prebind: false,
|
||||
show_controlbox_by_default: true,
|
||||
xhr_user_search: false
|
||||
roster_groups: true
|
||||
});
|
||||
});
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The <a class="reference external" href="https://github.com/jcbrand/converse.js/blob/master/index.html">index.html</a> file inside the
|
||||
Converse.js repository serves as a nice usable example of this.</p>
|
||||
Converse.js repository may serve as a nice usable example.</p>
|
||||
<p>These minified files provide the same demo-like functionality as is available
|
||||
on the <a class="reference external" href="http://conversejs.org">conversejs.org</a> website. Useful for testing or demoing, but not very
|
||||
practical.</p>
|
||||
@ -191,12 +192,12 @@ the minified Javascript file. Read <a class="reference internal" href="#configur
|
||||
that.</p>
|
||||
</div>
|
||||
<div class="section" id="introduction">
|
||||
<h1><a class="toc-backref" href="#id6">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h1>
|
||||
<h1><a class="toc-backref" href="#id8">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h1>
|
||||
<p>Even though you can connect to public XMPP servers on the <a class="reference external" href="http://conversejs.org">conversejs.org</a>
|
||||
website, <em>Converse.js</em> is not really meant to be a “Software-as-a-service” (SaaS)
|
||||
webchat.</p>
|
||||
<p>Instead, its goal is to provide the means for website owners to add a tightly
|
||||
integrated instant messaging service to their own sites.</p>
|
||||
integrated instant messaging service to their own websites.</p>
|
||||
<p>As a website owner, you are expected to host <em>Converse.js</em> yourself, and to do some legwork to
|
||||
properly configure and integrate it into your site.</p>
|
||||
<p>The benefit in doing this, is that your users have a much more streamlined and integrated
|
||||
@ -210,9 +211,9 @@ code.</p>
|
||||
requirements.</p>
|
||||
</div>
|
||||
<div class="section" id="what-you-will-need">
|
||||
<h1><a class="toc-backref" href="#id7">What you will need</a><a class="headerlink" href="#what-you-will-need" title="Permalink to this headline">¶</a></h1>
|
||||
<h1><a class="toc-backref" href="#id9">What you will need</a><a class="headerlink" href="#what-you-will-need" title="Permalink to this headline">¶</a></h1>
|
||||
<div class="section" id="an-xmpp-jabber-server">
|
||||
<h2><a class="toc-backref" href="#id8">An XMPP/Jabber server</a><a class="headerlink" href="#an-xmpp-jabber-server" title="Permalink to this headline">¶</a></h2>
|
||||
<h2><a class="toc-backref" href="#id10">An XMPP/Jabber server</a><a class="headerlink" href="#an-xmpp-jabber-server" title="Permalink to this headline">¶</a></h2>
|
||||
<p><em>Converse.js</em> implements <a class="reference external" href="https://en.wikipedia.org/wiki/Xmpp">XMPP</a> as its messaging protocol, and therefore needs
|
||||
to connect to an XMPP/Jabber server (Jabber is really just a synonym for XMPP).</p>
|
||||
<p>You can connect to public XMPP servers like <tt class="docutils literal"><span class="pre">jabber.org</span></tt> but if you want to
|
||||
@ -220,8 +221,8 @@ have <a class="reference internal" href="#session-support">Session Support</a> y
|
||||
<p>You can find a list of public XMPP servers/providers on <a class="reference external" href="http://xmpp.net">xmpp.net</a> and a list of
|
||||
servers that you can set up yourself on <a class="reference external" href="http://xmpp.org/xmpp-software/servers/">xmpp.org</a>.</p>
|
||||
</div>
|
||||
<div class="section" id="connection-manager">
|
||||
<h2><a class="toc-backref" href="#id9">Connection Manager</a><a class="headerlink" href="#connection-manager" title="Permalink to this headline">¶</a></h2>
|
||||
<div class="section" id="a-bosh-connection-manager">
|
||||
<h2><a class="toc-backref" href="#id11">A BOSH Connection Manager</a><a class="headerlink" href="#a-bosh-connection-manager" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Your website and <em>Converse.js</em> use <a class="reference external" href="https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol">HTTP</a> as protocol to communicate with
|
||||
the webserver. HTTP connections are stateless and usually shortlived.</p>
|
||||
<p><a class="reference external" href="https://en.wikipedia.org/wiki/Xmpp">XMPP</a> on the other hand, is the protocol that enables instant messaging, and
|
||||
@ -229,16 +230,20 @@ its connections are stateful and usually longer.</p>
|
||||
<p>To enable a web application like <em>Converse.js</em> to communicate with an XMPP
|
||||
server, we need a proxy in the middle that can act as a bridge between the two
|
||||
protocols.</p>
|
||||
<p>The <a class="reference external" href="https://github.com/jcbrand/converse.js/blob/master/index.html">index.html</a> file inside the</p>
|
||||
<p>This is the job of a connection manager. A connection manager can be either a
|
||||
standalone application or part of an XMPP server. <a class="reference external" href="http://www.ejabberd.im">ejabberd</a> for example,
|
||||
includes a connection manager (but you have to enable it).</p>
|
||||
<p>The demo on the <a class="reference external" href="http://conversejs.org">Converse.js homepage</a> uses a a connection manager located at <a class="reference external" href="https://bind.conversejs.org">https://bind.conversejs.org</a>.
|
||||
This connection manager is for testing purposes only, please don’t use it in
|
||||
production.</p>
|
||||
standalone application or part of an XMPP server. Popular XMPP servers such as
|
||||
<a class="reference external" href="http://www.ejabberd.im">ejabberd</a>, <a class="reference external" href="http://prosody.im/doc/setting_up_bosh">prosody</a> and
|
||||
<a class="reference external" href="http://www.igniterealtime.org/projects/openfire/">openfire</a> all include their own connection managers
|
||||
(but you usually have to enable them in the configuration).</p>
|
||||
<p>Standalone connection managers also exist, see for example <a class="reference external" href="https://github.com/twonds/punjab">Punjab</a>.</p>
|
||||
<p>The demo on the <a class="reference external" href="http://conversejs.org">Converse.js homepage</a> uses a connection manager located at <a class="reference external" href="https://bind.conversejs.org">https://bind.conversejs.org</a>.
|
||||
This connection manager is available for testing purposes only, please don’t use it in production.</p>
|
||||
<div class="section" id="overcoming-cross-domain-request-restrictions">
|
||||
<h3><a class="toc-backref" href="#id10">Overcoming cross-domain request restrictions</a><a class="headerlink" href="#overcoming-cross-domain-request-restrictions" title="Permalink to this headline">¶</a></h3>
|
||||
<p>The domain of the <em>Converse.js</em> demo is <em>conversejs.org</em>, but the domain of the connection manager is <em>opkode.im</em>.
|
||||
HTTP requests are made by <em>Converse.js</em> to the connection manager via XmlHttpRequests (XHR).
|
||||
<h3><a class="toc-backref" href="#id12">Overcoming cross-domain request restrictions</a><a class="headerlink" href="#overcoming-cross-domain-request-restrictions" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Lets say your domain is <em>example.org</em>, but the domain of your connection
|
||||
manager is <em>example.com</em>.</p>
|
||||
<p>HTTP requests are made by <em>Converse.js</em> to the connection manager via XmlHttpRequests (XHR).
|
||||
Until recently, it was not possible to make such requests to a different domain
|
||||
than the one currently being served (to prevent XSS attacks).</p>
|
||||
<p>Luckily there is now a standard called <a class="reference external" href="https://en.wikipedia.org/wiki/Cross-origin_resource_sharing">CORS</a> (Cross-origin resource sharing), which enables exactly that.
|
||||
@ -287,9 +292,9 @@ the cross-domain restriction is <tt class="docutils literal"><span class="pre">m
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="server-side-authentication">
|
||||
<h2><a class="toc-backref" href="#id11">Server-side authentication</a><a class="headerlink" href="#server-side-authentication" title="Permalink to this headline">¶</a></h2>
|
||||
<h2><a class="toc-backref" href="#id13">Server-side authentication</a><a class="headerlink" href="#server-side-authentication" title="Permalink to this headline">¶</a></h2>
|
||||
<div class="section" id="prebinding-and-single-session-support">
|
||||
<span id="session-support"></span><h3><a class="toc-backref" href="#id12">Prebinding and Single Session Support</a><a class="headerlink" href="#prebinding-and-single-session-support" title="Permalink to this headline">¶</a></h3>
|
||||
<span id="session-support"></span><h3><a class="toc-backref" href="#id14">Prebinding and Single Session Support</a><a class="headerlink" href="#prebinding-and-single-session-support" title="Permalink to this headline">¶</a></h3>
|
||||
<p>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,</p>
|
||||
<p>This session should also persist across page loads. In other words, we don’t
|
||||
@ -347,7 +352,7 @@ Additionally you need to pass in valid <strong>jid</strong>, <strong>sid</strong
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="example-code-for-server-side-prebinding">
|
||||
<h3><a class="toc-backref" href="#id13">Example code for server-side prebinding</a><a class="headerlink" href="#example-code-for-server-side-prebinding" title="Permalink to this headline">¶</a></h3>
|
||||
<h3><a class="toc-backref" href="#id15">Example code for server-side prebinding</a><a class="headerlink" href="#example-code-for-server-side-prebinding" title="Permalink to this headline">¶</a></h3>
|
||||
<ul>
|
||||
<li><dl class="first docutils">
|
||||
<dt>PHP:</dt>
|
||||
@ -364,55 +369,6 @@ Michael Weibel and the folks from Candy chat.</p>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="setting-up-a-bosh-server">
|
||||
<h3><a class="toc-backref" href="#id14">Setting up a BOSH server</a><a class="headerlink" href="#setting-up-a-bosh-server" title="Permalink to this headline">¶</a></h3>
|
||||
<p>The <a class="reference external" href="http://movim.eu/">Movim</a> project wiki has a very thorough page on setting up a BOSH server for
|
||||
a wide variety of standalone or XMPP servers.</p>
|
||||
<p><a class="reference external" href="http://wiki.movim.eu/manual:bosh_servers">http://wiki.movim.eu/manual:bosh_servers</a></p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="facebook-integration">
|
||||
<h2><a class="toc-backref" href="#id15">Facebook integration</a><a class="headerlink" href="#facebook-integration" title="Permalink to this headline">¶</a></h2>
|
||||
<div class="admonition note">
|
||||
<p class="first admonition-title">Note</p>
|
||||
<p class="last">It should be possible to integrate Converse.js with Facebook chat, and
|
||||
below I’ll provide some tips and documentation on how to achieve this. That
|
||||
said, I don’t have a Facebook account and therefore haven’t tried to do
|
||||
this myself. Feedback and patches from people who have succesfully done this
|
||||
will be appreciated.</p>
|
||||
</div>
|
||||
<p>Converse.js uses <a class="reference external" href="http://strophe.im/strophejs">Strophe.js</a> to connect and
|
||||
communicate with the XMPP server. One nice thing about Strophe.js is that it
|
||||
can be extended via <a class="reference external" href="http://github.com/strophe/strophejs-plugins">plugins</a>.</p>
|
||||
<p>Here is a <a class="reference external" href="https://github.com/kissrobber/turedsocial/blob/master/strophe-plugins/src/facebook.js">plugin for authenticating with facebook</a>.</p>
|
||||
<p>You will need your own BOSH connection manager to act as a proxy between
|
||||
Converse.js/Strophe.js and Facebook’s XMPP server. That is because Facebook’s
|
||||
XMPP server doesn’t support BOSH natively.</p>
|
||||
<p>The BOSH connection manager that I make available for
|
||||
testing purposes (at <a class="reference external" href="https://bind.conversejs.org">https://bind.conversejs.org</a>) uses <a class="reference external" href="https://github.com/twonds/punjab">Punjab</a>,
|
||||
although there are quite a few other options available as well.</p>
|
||||
<p>When you configure Converse.js, via its <tt class="docutils literal"><span class="pre">initialize</span></tt> method, you must specify the
|
||||
<a class="reference internal" href="#bosh-service-url">bosh_service_url</a> value, which is to be your BOSH connection manager.</p>
|
||||
<p>Please note, to enable Facebook integration, you’ll have to
|
||||
get your hands dirty and modify Converse.js’s code, so that it calls the
|
||||
<tt class="docutils literal"><span class="pre">facebookConnect</span></tt> method of the plugin above.</p>
|
||||
<p>The plugin above gives the following code example for you to meditate upon:</p>
|
||||
<div class="highlight-python"><div class="highlight"><pre>connection = new Strophe.Connection("http://localhost:5280/bosh");
|
||||
connection.facebookConnect(
|
||||
"12345@chat.facebook.com",
|
||||
onConnectFacebook,
|
||||
300,
|
||||
1,
|
||||
'5e64a30272af065bd72258c565a03f2f',
|
||||
'8147a27e4a7f9b55ffc85c2683f9529a',
|
||||
FB.getSession().session_key
|
||||
);
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The connection is already created inside Converse.js, so the
|
||||
<tt class="docutils literal"><span class="pre">facebookConnect</span></tt> method needs to also be called from there.</p>
|
||||
<p>If someone submits a sane patch that does the above, I’ll be happy to merge it.
|
||||
Until then, people will have to do this themselves.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="features">
|
||||
@ -439,15 +395,29 @@ secure crypto.</p>
|
||||
Converse.js in order to avoid most eavesdroppers, if you need serious
|
||||
communications privacy, then you’re much better off using native software.</p>
|
||||
</div>
|
||||
<div class="section" id="sound-notifications">
|
||||
<h2><a class="toc-backref" href="#id18">Sound Notifications</a><a class="headerlink" href="#sound-notifications" title="Permalink to this headline">¶</a></h2>
|
||||
<p>From version 0.8.1 Converse.js can play a sound notification when you receive a
|
||||
message.</p>
|
||||
<p>For more info, please see the <a class="reference internal" href="#play-sounds">play_sounds</a> configuration setting.</p>
|
||||
</div>
|
||||
<div class="section" id="multilingual-support">
|
||||
<h2><a class="toc-backref" href="#id19">Multilingual Support</a><a class="headerlink" href="#multilingual-support" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Converse.js is translated into multiple languages. The default build,
|
||||
<tt class="docutils literal"><span class="pre">converse.min.js</span></tt>, includes all languages.</p>
|
||||
<p>Languages increase the size of the Converse.js significantly.</p>
|
||||
<p>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.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="development">
|
||||
<h1><a class="toc-backref" href="#id18">Development</a><a class="headerlink" href="#development" title="Permalink to this headline">¶</a></h1>
|
||||
<h1><a class="toc-backref" href="#id20">Development</a><a class="headerlink" href="#development" title="Permalink to this headline">¶</a></h1>
|
||||
<p>If you want to work with the non-minified Javascript and CSS files you’ll soon
|
||||
notice that there are references to a missing <em>components</em> folder. Please
|
||||
follow the instructions below to create this folder and fetch Converse’s
|
||||
3rd-party dependencies.</p>
|
||||
<div class="section" id="install-the-development-and-front-end-dependencies">
|
||||
<h2><a class="toc-backref" href="#id19">Install the development and front-end dependencies</a><a class="headerlink" href="#install-the-development-and-front-end-dependencies" title="Permalink to this headline">¶</a></h2>
|
||||
<h2><a class="toc-backref" href="#id21">Install the development and front-end dependencies</a><a class="headerlink" href="#install-the-development-and-front-end-dependencies" title="Permalink to this headline">¶</a></h2>
|
||||
<p>We use development tools (<a class="reference external" href="http://gruntjs.com">Grunt</a> and <a class="reference external" href="http://bower.io">Bower</a>)
|
||||
which depend on Node.js and npm (the Node package manager).</p>
|
||||
<p>If you don’t have Node.js installed, you can download and install the latest
|
||||
@ -486,7 +456,7 @@ Converse.js directly depends and which will be loaded in the browser.</p>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="with-amd-and-require-js-recommended">
|
||||
<h2><a class="toc-backref" href="#id20">With AMD and require.js (recommended)</a><a class="headerlink" href="#with-amd-and-require-js-recommended" title="Permalink to this headline">¶</a></h2>
|
||||
<h2><a class="toc-backref" href="#id22">With AMD and require.js (recommended)</a><a class="headerlink" href="#with-amd-and-require-js-recommended" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Converse.js uses <a class="reference external" href="http://requirejs.org">require.js</a> to asynchronously load dependencies.</p>
|
||||
<p>If you want to develop or customize converse.js, you’ll want to load the
|
||||
non-minified javascript files.</p>
|
||||
@ -500,7 +470,7 @@ attribute on the <em>script</em> tag), which will in turn cause converse.js to b
|
||||
parsed.</p>
|
||||
</div>
|
||||
<div class="section" id="without-amd-and-require-js">
|
||||
<h2><a class="toc-backref" href="#id21">Without AMD and require.js</a><a class="headerlink" href="#without-amd-and-require-js" title="Permalink to this headline">¶</a></h2>
|
||||
<h2><a class="toc-backref" href="#id23">Without AMD and require.js</a><a class="headerlink" href="#without-amd-and-require-js" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Converse.js can also be used without require.js. If you for some reason prefer
|
||||
to use it this way, please refer to
|
||||
<a class="reference external" href="https://github.com/jcbrand/converse.js/blob/master/non_amd.html">non_amd.html</a>
|
||||
@ -508,9 +478,9 @@ for an example of how and in what order all the Javascript files that converse.j
|
||||
depends on need to be loaded.</p>
|
||||
</div>
|
||||
<div class="section" id="before-submitting-a-pull-request">
|
||||
<h2><a class="toc-backref" href="#id22">Before submitting a pull request</a><a class="headerlink" href="#before-submitting-a-pull-request" title="Permalink to this headline">¶</a></h2>
|
||||
<h2><a class="toc-backref" href="#id24">Before submitting a pull request</a><a class="headerlink" href="#before-submitting-a-pull-request" title="Permalink to this headline">¶</a></h2>
|
||||
<div class="section" id="add-tests-for-your-bugfix-or-feature">
|
||||
<h3><a class="toc-backref" href="#id23">Add tests for your bugfix or feature</a><a class="headerlink" href="#add-tests-for-your-bugfix-or-feature" title="Permalink to this headline">¶</a></h3>
|
||||
<h3><a class="toc-backref" href="#id25">Add tests for your bugfix or feature</a><a class="headerlink" href="#add-tests-for-your-bugfix-or-feature" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Add a test for any bug fixed or feature added. We use Jasmine
|
||||
for testing.</p>
|
||||
<p>Take a look at <tt class="docutils literal"><span class="pre">tests.html</span></tt> and <tt class="docutils literal"><span class="pre">spec/MainSpec.js</span></tt> to see how
|
||||
@ -519,7 +489,7 @@ the tests are implemented.</p>
|
||||
<a class="reference external" href="http://opkode.com/contact">contact me</a> and I’ll be happy to help.</p>
|
||||
</div>
|
||||
<div class="section" id="check-that-the-tests-pass">
|
||||
<h3><a class="toc-backref" href="#id24">Check that the tests pass</a><a class="headerlink" href="#check-that-the-tests-pass" title="Permalink to this headline">¶</a></h3>
|
||||
<h3><a class="toc-backref" href="#id26">Check that the tests pass</a><a class="headerlink" href="#check-that-the-tests-pass" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Check that the Jasmine tests complete sucessfully. Open
|
||||
<a class="reference external" href="https://github.com/jcbrand/converse.js/blob/master/tests.html">tests.html</a>
|
||||
in your browser, and the tests will run automatically.</p>
|
||||
@ -529,7 +499,7 @@ in your browser, and the tests will run automatically.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="check-your-code-for-errors-or-bad-habits-by-running-jshint">
|
||||
<h3><a class="toc-backref" href="#id25">Check your code for errors or bad habits by running JSHint</a><a class="headerlink" href="#check-your-code-for-errors-or-bad-habits-by-running-jshint" title="Permalink to this headline">¶</a></h3>
|
||||
<h3><a class="toc-backref" href="#id27">Check your code for errors or bad habits by running JSHint</a><a class="headerlink" href="#check-your-code-for-errors-or-bad-habits-by-running-jshint" title="Permalink to this headline">¶</a></h3>
|
||||
<p><a class="reference external" href="http://jshint.com">JSHint</a> will do a static analysis of your code and hightlight potential errors
|
||||
and/or bad habits.</p>
|
||||
<div class="highlight-python"><div class="highlight"><pre>grunt jshint
|
||||
@ -542,9 +512,9 @@ and/or bad habits.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="minification">
|
||||
<h2><a class="toc-backref" href="#id26">Minification</a><a class="headerlink" href="#minification" title="Permalink to this headline">¶</a></h2>
|
||||
<h2><a class="toc-backref" href="#id28">Minification</a><a class="headerlink" href="#minification" title="Permalink to this headline">¶</a></h2>
|
||||
<div class="section" id="minifying-javascript-and-css">
|
||||
<h3><a class="toc-backref" href="#id27">Minifying Javascript and CSS</a><a class="headerlink" href="#minifying-javascript-and-css" title="Permalink to this headline">¶</a></h3>
|
||||
<h3><a class="toc-backref" href="#id29">Minifying Javascript and CSS</a><a class="headerlink" href="#minifying-javascript-and-css" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Please make sure to read the section <a class="reference internal" href="#development">Development</a> and that you have installed
|
||||
all development dependencies (long story short, you can run <tt class="docutils literal"><span class="pre">npm</span> <span class="pre">install</span></tt>
|
||||
and then <tt class="docutils literal"><span class="pre">grunt</span> <span class="pre">fetch</span></tt>).</p>
|
||||
@ -562,7 +532,7 @@ using <a class="reference external" href="https://github.com/jrburke/almond">alm
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="translations">
|
||||
<h2><a class="toc-backref" href="#id28">Translations</a><a class="headerlink" href="#translations" title="Permalink to this headline">¶</a></h2>
|
||||
<h2><a class="toc-backref" href="#id30">Translations</a><a class="headerlink" href="#translations" title="Permalink to this headline">¶</a></h2>
|
||||
<div class="admonition note">
|
||||
<p class="first admonition-title">Note</p>
|
||||
<p class="last">Translations take up a lot of space and will bloat your minified file.
|
||||
@ -645,11 +615,11 @@ those hoops you had to jump through.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="troubleshooting">
|
||||
<h1><a class="toc-backref" href="#id29">Troubleshooting</a><a class="headerlink" href="#troubleshooting" title="Permalink to this headline">¶</a></h1>
|
||||
<h1><a class="toc-backref" href="#id31">Troubleshooting</a><a class="headerlink" href="#troubleshooting" title="Permalink to this headline">¶</a></h1>
|
||||
<div class="section" id="conflicts-with-other-javascript-libraries">
|
||||
<h2><a class="toc-backref" href="#id30">Conflicts with other Javascript libraries</a><a class="headerlink" href="#conflicts-with-other-javascript-libraries" title="Permalink to this headline">¶</a></h2>
|
||||
<h2><a class="toc-backref" href="#id32">Conflicts with other Javascript libraries</a><a class="headerlink" href="#conflicts-with-other-javascript-libraries" title="Permalink to this headline">¶</a></h2>
|
||||
<div class="section" id="problem">
|
||||
<h3><a class="toc-backref" href="#id31">Problem:</a><a class="headerlink" href="#problem" title="Permalink to this headline">¶</a></h3>
|
||||
<h3><a class="toc-backref" href="#id33">Problem:</a><a class="headerlink" href="#problem" title="Permalink to this headline">¶</a></h3>
|
||||
<p>You are using other Javascript libraries (like JQuery plugins), and
|
||||
get errors like these in your browser console:</p>
|
||||
<div class="highlight-python"><div class="highlight"><pre>Uncaught TypeError: Object [object Object] has no method 'xxx' from example.js
|
||||
@ -657,7 +627,7 @@ get errors like these in your browser console:</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="solution">
|
||||
<h3><a class="toc-backref" href="#id32">Solution:</a><a class="headerlink" href="#solution" title="Permalink to this headline">¶</a></h3>
|
||||
<h3><a class="toc-backref" href="#id34">Solution:</a><a class="headerlink" href="#solution" title="Permalink to this headline">¶</a></h3>
|
||||
<p>First, find out which object is referred to by <tt class="docutils literal"><span class="pre">Object</span> <span class="pre">[object</span> <span class="pre">Object]</span></tt>.</p>
|
||||
<p>It will probably be the jQuery object <tt class="docutils literal"><span class="pre">$</span></tt> or perhaps the underscore.js object <tt class="docutils literal"><span class="pre">_</span></tt>.</p>
|
||||
<p>For the purpose of demonstration, I’m going to assume its <tt class="docutils literal"><span class="pre">$</span></tt>, but the same
|
||||
@ -699,11 +669,11 @@ jQuery plugins must load after jQuery).</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="events">
|
||||
<h1><a class="toc-backref" href="#id33">Events</a><a class="headerlink" href="#events" title="Permalink to this headline">¶</a></h1>
|
||||
<h1><a class="toc-backref" href="#id35">Events</a><a class="headerlink" href="#events" title="Permalink to this headline">¶</a></h1>
|
||||
<p>Converse.js emits events to which you can subscribe from your own Javascript.</p>
|
||||
<p>Concerning events, the following methods are available:</p>
|
||||
<div class="section" id="event-methods">
|
||||
<h2><a class="toc-backref" href="#id34">Event Methods</a><a class="headerlink" href="#event-methods" title="Permalink to this headline">¶</a></h2>
|
||||
<h2><a class="toc-backref" href="#id36">Event Methods</a><a class="headerlink" href="#event-methods" title="Permalink to this headline">¶</a></h2>
|
||||
<ul>
|
||||
<li><p class="first"><strong>on(eventName, callback)</strong>:</p>
|
||||
<blockquote>
|
||||
@ -749,7 +719,7 @@ exactly once.</p>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="event-types">
|
||||
<h2><a class="toc-backref" href="#id35">Event Types</a><a class="headerlink" href="#event-types" title="Permalink to this headline">¶</a></h2>
|
||||
<h2><a class="toc-backref" href="#id37">Event Types</a><a class="headerlink" href="#event-types" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Here are the different events that are emitted:</p>
|
||||
<table border="1" class="docutils">
|
||||
<colgroup>
|
||||
@ -833,7 +803,7 @@ exactly once.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="configuration">
|
||||
<h1><a class="toc-backref" href="#id36">Configuration</a><a class="headerlink" href="#configuration" title="Permalink to this headline">¶</a></h1>
|
||||
<h1><a class="toc-backref" href="#id38">Configuration</a><a class="headerlink" href="#configuration" title="Permalink to this headline">¶</a></h1>
|
||||
<p>The included minified JS and CSS files can be used for demoing or testing, but
|
||||
you’ll want to configure <em>Converse.js</em> to suit your needs before you deploy it
|
||||
on your website.</p>
|
||||
@ -847,9 +817,9 @@ all the available configuration settings.</p>
|
||||
JS file so that it will include the new settings. Please refer to the
|
||||
<a class="reference internal" href="#minification">Minification</a> section for more info on how to do this.</p>
|
||||
<div class="section" id="configuration-variables">
|
||||
<h2><a class="toc-backref" href="#id37">Configuration variables</a><a class="headerlink" href="#configuration-variables" title="Permalink to this headline">¶</a></h2>
|
||||
<h2><a class="toc-backref" href="#id39">Configuration variables</a><a class="headerlink" href="#configuration-variables" title="Permalink to this headline">¶</a></h2>
|
||||
<div class="section" id="allow-contact-requests">
|
||||
<h3><a class="toc-backref" href="#id38">allow_contact_requests</a><a class="headerlink" href="#allow-contact-requests" title="Permalink to this headline">¶</a></h3>
|
||||
<h3><a class="toc-backref" href="#id40">allow_contact_requests</a><a class="headerlink" href="#allow-contact-requests" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Default: <tt class="docutils literal"><span class="pre">true</span></tt></p>
|
||||
<p>Allow users to add one another as contacts. If this is set to false, the
|
||||
<strong>Add a contact</strong> widget, <strong>Contact Requests</strong> and <strong>Pending Contacts</strong> roster
|
||||
@ -857,23 +827,23 @@ sections will all not appear. Additionally, all incoming contact requests will b
|
||||
ignored.</p>
|
||||
</div>
|
||||
<div class="section" id="allow-muc">
|
||||
<h3><a class="toc-backref" href="#id39">allow_muc</a><a class="headerlink" href="#allow-muc" title="Permalink to this headline">¶</a></h3>
|
||||
<h3><a class="toc-backref" href="#id41">allow_muc</a><a class="headerlink" href="#allow-muc" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Default: <tt class="docutils literal"><span class="pre">true</span></tt></p>
|
||||
<p>Allow multi-user chat (muc) in chatrooms. Setting this to <tt class="docutils literal"><span class="pre">false</span></tt> will remove
|
||||
the <tt class="docutils literal"><span class="pre">Chatrooms</span></tt> tab from the control box.</p>
|
||||
</div>
|
||||
<div class="section" id="id2">
|
||||
<h3><a class="toc-backref" href="#id40">allow_muc</a><a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h3>
|
||||
<div class="section" id="id3">
|
||||
<h3><a class="toc-backref" href="#id42">allow_muc</a><a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Default: <tt class="docutils literal"><span class="pre">true</span></tt></p>
|
||||
<p>Allow Off-the-record encryption of single-user chat messages.</p>
|
||||
</div>
|
||||
<div class="section" id="animate">
|
||||
<h3><a class="toc-backref" href="#id41">animate</a><a class="headerlink" href="#animate" title="Permalink to this headline">¶</a></h3>
|
||||
<h3><a class="toc-backref" href="#id43">animate</a><a class="headerlink" href="#animate" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Default: <tt class="docutils literal"><span class="pre">true</span></tt></p>
|
||||
<p>Show animations, for example when opening and closing chat boxes.</p>
|
||||
</div>
|
||||
<div class="section" id="auto-list-rooms">
|
||||
<h3><a class="toc-backref" href="#id42">auto_list_rooms</a><a class="headerlink" href="#auto-list-rooms" title="Permalink to this headline">¶</a></h3>
|
||||
<h3><a class="toc-backref" href="#id44">auto_list_rooms</a><a class="headerlink" href="#auto-list-rooms" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Default: <tt class="docutils literal"><span class="pre">false</span></tt></p>
|
||||
<p>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.</p>
|
||||
@ -883,24 +853,24 @@ features, number of occupants etc.), so on servers with many rooms this
|
||||
option will create lots of extra connection traffic.</p>
|
||||
</div>
|
||||
<div class="section" id="auto-reconnect">
|
||||
<h3><a class="toc-backref" href="#id43">auto_reconnect</a><a class="headerlink" href="#auto-reconnect" title="Permalink to this headline">¶</a></h3>
|
||||
<h3><a class="toc-backref" href="#id45">auto_reconnect</a><a class="headerlink" href="#auto-reconnect" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Default: <tt class="docutils literal"><span class="pre">true</span></tt></p>
|
||||
<p>Automatically reconnect to the XMPP server if the connection drops
|
||||
unexpectedly.</p>
|
||||
</div>
|
||||
<div class="section" id="auto-subscribe">
|
||||
<h3><a class="toc-backref" href="#id44">auto_subscribe</a><a class="headerlink" href="#auto-subscribe" title="Permalink to this headline">¶</a></h3>
|
||||
<h3><a class="toc-backref" href="#id46">auto_subscribe</a><a class="headerlink" href="#auto-subscribe" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Default: <tt class="docutils literal"><span class="pre">false</span></tt></p>
|
||||
<p>If true, the user will automatically subscribe back to any contact requests.</p>
|
||||
</div>
|
||||
<div class="section" id="bosh-service-url">
|
||||
<h3><a class="toc-backref" href="#id45">bosh_service_url</a><a class="headerlink" href="#bosh-service-url" title="Permalink to this headline">¶</a></h3>
|
||||
<h3><a class="toc-backref" href="#id47">bosh_service_url</a><a class="headerlink" href="#bosh-service-url" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Connections to an XMPP server depend on a BOSH connection manager which acts as
|
||||
a middle man between HTTP and XMPP.</p>
|
||||
<p>See <a class="reference external" href="http://metajack.im/2008/09/08/which-bosh-server-do-you-need">here</a> for more information.</p>
|
||||
</div>
|
||||
<div class="section" id="cache-otr-key">
|
||||
<h3><a class="toc-backref" href="#id46">cache_otr_key</a><a class="headerlink" href="#cache-otr-key" title="Permalink to this headline">¶</a></h3>
|
||||
<h3><a class="toc-backref" href="#id48">cache_otr_key</a><a class="headerlink" href="#cache-otr-key" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Default: <tt class="docutils literal"><span class="pre">false</span></tt></p>
|
||||
<p>Let the <a class="reference external" href="https://otr.cypherpunks.ca">OTR (Off-the-record encryption)</a> private
|
||||
key be cached in your browser’s session storage.</p>
|
||||
@ -919,17 +889,17 @@ current session. Previous sessions however cannot be decrypted.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="debug">
|
||||
<h3><a class="toc-backref" href="#id47">debug</a><a class="headerlink" href="#debug" title="Permalink to this headline">¶</a></h3>
|
||||
<h3><a class="toc-backref" href="#id49">debug</a><a class="headerlink" href="#debug" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Default: <tt class="docutils literal"><span class="pre">false</span></tt></p>
|
||||
<p>If set to true, debugging output will be logged to the browser console.</p>
|
||||
</div>
|
||||
<div class="section" id="message-carbons">
|
||||
<h3><a class="toc-backref" href="#id48">message_carbons</a><a class="headerlink" href="#message-carbons" title="Permalink to this headline">¶</a></h3>
|
||||
<h3><a class="toc-backref" href="#id50">message_carbons</a><a class="headerlink" href="#message-carbons" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Default: <tt class="docutils literal"><span class="pre">false</span></tt></p>
|
||||
<p>Support for <a class="reference external" href="https://xmpp.org/extensions/xep-0280.html">XEP-0280: Message Carbons</a></p>
|
||||
</div>
|
||||
<div class="section" id="expose-rid-and-sid">
|
||||
<h3><a class="toc-backref" href="#id49">expose_rid_and_sid</a><a class="headerlink" href="#expose-rid-and-sid" title="Permalink to this headline">¶</a></h3>
|
||||
<h3><a class="toc-backref" href="#id51">expose_rid_and_sid</a><a class="headerlink" href="#expose-rid-and-sid" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Default: <tt class="docutils literal"><span class="pre">false</span></tt></p>
|
||||
<p>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
|
||||
@ -938,7 +908,7 @@ these values.</p>
|
||||
and inject fake chat messages.</p>
|
||||
</div>
|
||||
<div class="section" id="forward-messages">
|
||||
<h3><a class="toc-backref" href="#id50">forward_messages</a><a class="headerlink" href="#forward-messages" title="Permalink to this headline">¶</a></h3>
|
||||
<h3><a class="toc-backref" href="#id52">forward_messages</a><a class="headerlink" href="#forward-messages" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Default: <tt class="docutils literal"><span class="pre">false</span></tt></p>
|
||||
<p>If set to <tt class="docutils literal"><span class="pre">true</span></tt>, sent messages will also be forwarded to other connected
|
||||
XMPP resources (e.g. chat clients) of the same user.</p>
|
||||
@ -947,24 +917,35 @@ browser and you want sent messages to appear in all of them.</p>
|
||||
<p>See also <a class="reference external" href="http://www.xmpp.org/extensions/xep-0297.html">XEP 0297: Stanza Forwarding</a></p>
|
||||
</div>
|
||||
<div class="section" id="fullname">
|
||||
<h3><a class="toc-backref" href="#id51">fullname</a><a class="headerlink" href="#fullname" title="Permalink to this headline">¶</a></h3>
|
||||
<h3><a class="toc-backref" href="#id53">fullname</a><a class="headerlink" href="#fullname" title="Permalink to this headline">¶</a></h3>
|
||||
<p>If you are using prebinding, can specify the fullname of the currently
|
||||
logged in user, otherwise the user’s vCard will be fetched.</p>
|
||||
</div>
|
||||
<div class="section" id="hide-muc-server">
|
||||
<h3><a class="toc-backref" href="#id52">hide_muc_server</a><a class="headerlink" href="#hide-muc-server" title="Permalink to this headline">¶</a></h3>
|
||||
<h3><a class="toc-backref" href="#id54">hide_muc_server</a><a class="headerlink" href="#hide-muc-server" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Default: <tt class="docutils literal"><span class="pre">false</span></tt></p>
|
||||
<p>Hide the <tt class="docutils literal"><span class="pre">server</span></tt> input field of the form inside the <tt class="docutils literal"><span class="pre">Room</span></tt> panel of the
|
||||
controlbox. Useful if you want to restrict users to a specific XMPP server of
|
||||
your choosing.</p>
|
||||
</div>
|
||||
<div class="section" id="i18n">
|
||||
<h3><a class="toc-backref" href="#id53">i18n</a><a class="headerlink" href="#i18n" title="Permalink to this headline">¶</a></h3>
|
||||
<h3><a class="toc-backref" href="#id55">i18n</a><a class="headerlink" href="#i18n" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Specify the locale/language. The language must be in the <tt class="docutils literal"><span class="pre">locales</span></tt> object. Refer to
|
||||
<tt class="docutils literal"><span class="pre">./locale/locales.js</span></tt> to see which locales are supported.</p>
|
||||
</div>
|
||||
<div class="section" id="play-sounds">
|
||||
<h3><a class="toc-backref" href="#id56">play_sounds</a><a class="headerlink" href="#play-sounds" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Default: <tt class="docutils literal"><span class="pre">false</span></tt></p>
|
||||
<p>Inside the <tt class="docutils literal"><span class="pre">./sounds</span></tt> directory of the Converse.js repo, you’ll see MP3 and Ogg
|
||||
formatted sound files. We need both, because neither format is supported by all browsers.</p>
|
||||
<p>For now, sound files are looked up by convention, not configuration. So to have
|
||||
a sound play when a message is received, make sure that your webserver serves
|
||||
it in both formats as <tt class="docutils literal"><span class="pre">http://yoursite.com/sounds/msg_received.mp3</span></tt> and
|
||||
<tt class="docutils literal"><span class="pre">http://yoursite.com/sounds/msg_received.ogg</span></tt>.</p>
|
||||
<p><tt class="docutils literal"><span class="pre">http://yoursite.com</span></tt> should of course be your site’s URL.</p>
|
||||
</div>
|
||||
<div class="section" id="prebind">
|
||||
<h3><a class="toc-backref" href="#id54">prebind</a><a class="headerlink" href="#prebind" title="Permalink to this headline">¶</a></h3>
|
||||
<h3><a class="toc-backref" href="#id57">prebind</a><a class="headerlink" href="#prebind" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Default: <tt class="docutils literal"><span class="pre">false</span></tt></p>
|
||||
<p>Use this option when you want to attach to an existing XMPP connection that was
|
||||
already authenticated (usually on the backend before page load).</p>
|
||||
@ -977,7 +958,7 @@ values as <tt class="docutils literal"><span class="pre">jid</span></tt>, <tt cl
|
||||
<p>Additionally, you have to specify <tt class="docutils literal"><span class="pre">bosh_service_url</span></tt>.</p>
|
||||
</div>
|
||||
<div class="section" id="roster-groups">
|
||||
<h3><a class="toc-backref" href="#id55">roster_groups</a><a class="headerlink" href="#roster-groups" title="Permalink to this headline">¶</a></h3>
|
||||
<h3><a class="toc-backref" href="#id58">roster_groups</a><a class="headerlink" href="#roster-groups" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Default: <tt class="docutils literal"><span class="pre">false</span></tt></p>
|
||||
<p>If set to <tt class="docutils literal"><span class="pre">true</span></tt>, converse.js will show any roster groups you might have
|
||||
configured.</p>
|
||||
@ -989,7 +970,7 @@ elsewhere.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="show-controlbox-by-default">
|
||||
<h3><a class="toc-backref" href="#id56">show_controlbox_by_default</a><a class="headerlink" href="#show-controlbox-by-default" title="Permalink to this headline">¶</a></h3>
|
||||
<h3><a class="toc-backref" href="#id59">show_controlbox_by_default</a><a class="headerlink" href="#show-controlbox-by-default" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Default: <tt class="docutils literal"><span class="pre">false</span></tt></p>
|
||||
<p>The “controlbox” refers to the special chatbox containing your contacts roster,
|
||||
status widget, chatrooms and other controls.</p>
|
||||
@ -999,13 +980,13 @@ the page with class <em>toggle-controlbox</em>.</p>
|
||||
page load.</p>
|
||||
</div>
|
||||
<div class="section" id="show-only-online-users">
|
||||
<h3><a class="toc-backref" href="#id57">show_only_online_users</a><a class="headerlink" href="#show-only-online-users" title="Permalink to this headline">¶</a></h3>
|
||||
<h3><a class="toc-backref" href="#id60">show_only_online_users</a><a class="headerlink" href="#show-only-online-users" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Default: <tt class="docutils literal"><span class="pre">false</span></tt></p>
|
||||
<p>If set to <tt class="docutils literal"><span class="pre">true</span></tt>, only online users will be shown in the contacts roster.
|
||||
Users with any other status (e.g. away, busy etc.) will not be shown.</p>
|
||||
</div>
|
||||
<div class="section" id="storage">
|
||||
<h3><a class="toc-backref" href="#id58">storage</a><a class="headerlink" href="#storage" title="Permalink to this headline">¶</a></h3>
|
||||
<h3><a class="toc-backref" href="#id61">storage</a><a class="headerlink" href="#storage" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Default: <tt class="docutils literal"><span class="pre">session</span></tt></p>
|
||||
<p>Valid options: <tt class="docutils literal"><span class="pre">session</span></tt>, <tt class="docutils literal"><span class="pre">local</span></tt>.</p>
|
||||
<p>This option determines the type of <a class="reference external" href="https://developer.mozilla.org/en-US/docs/Web/Guide/API/DOM/Storage">storage</a>
|
||||
@ -1018,20 +999,20 @@ it’s closed, the data is cleared.</p>
|
||||
<p>Data in localStorage on the other hand is kept indefinitely.</p>
|
||||
</div>
|
||||
<div class="section" id="use-otr-by-default">
|
||||
<h3><a class="toc-backref" href="#id59">use_otr_by_default</a><a class="headerlink" href="#use-otr-by-default" title="Permalink to this headline">¶</a></h3>
|
||||
<h3><a class="toc-backref" href="#id62">use_otr_by_default</a><a class="headerlink" href="#use-otr-by-default" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Default: <tt class="docutils literal"><span class="pre">false</span></tt></p>
|
||||
<p>If set to <tt class="docutils literal"><span class="pre">true</span></tt>, Converse.js will automatically try to initiate an OTR (off-the-record)
|
||||
encrypted chat session every time you open a chat box.</p>
|
||||
</div>
|
||||
<div class="section" id="use-vcards">
|
||||
<h3><a class="toc-backref" href="#id60">use_vcards</a><a class="headerlink" href="#use-vcards" title="Permalink to this headline">¶</a></h3>
|
||||
<h3><a class="toc-backref" href="#id63">use_vcards</a><a class="headerlink" href="#use-vcards" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Default: <tt class="docutils literal"><span class="pre">true</span></tt></p>
|
||||
<p>Determines whether the XMPP server will be queried for roster contacts’ VCards
|
||||
or not. VCards contain extra personal information such as your fullname and
|
||||
avatar image.</p>
|
||||
</div>
|
||||
<div class="section" id="visible-toolbar-buttons">
|
||||
<h3><a class="toc-backref" href="#id61">visible_toolbar_buttons</a><a class="headerlink" href="#visible-toolbar-buttons" title="Permalink to this headline">¶</a></h3>
|
||||
<h3><a class="toc-backref" href="#id64">visible_toolbar_buttons</a><a class="headerlink" href="#visible-toolbar-buttons" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Default:</p>
|
||||
<div class="highlight-python"><div class="highlight"><pre><span class="p">{</span>
|
||||
<span class="s">'emoticons'</span><span class="p">:</span> <span class="n">true</span><span class="p">,</span>
|
||||
@ -1071,7 +1052,7 @@ When the call button is pressed, it will emit an event that can be used by a thi
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="xhr-custom-status">
|
||||
<h3><a class="toc-backref" href="#id62">xhr_custom_status</a><a class="headerlink" href="#xhr-custom-status" title="Permalink to this headline">¶</a></h3>
|
||||
<h3><a class="toc-backref" href="#id65">xhr_custom_status</a><a class="headerlink" href="#xhr-custom-status" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Default: <tt class="docutils literal"><span class="pre">false</span></tt></p>
|
||||
<div class="admonition note">
|
||||
<p class="first admonition-title">Note</p>
|
||||
@ -1081,7 +1062,7 @@ When the call button is pressed, it will emit an event that can be used by a thi
|
||||
remote server.</p>
|
||||
</div>
|
||||
<div class="section" id="xhr-custom-status-url">
|
||||
<h3><a class="toc-backref" href="#id63">xhr_custom_status_url</a><a class="headerlink" href="#xhr-custom-status-url" title="Permalink to this headline">¶</a></h3>
|
||||
<h3><a class="toc-backref" href="#id66">xhr_custom_status_url</a><a class="headerlink" href="#xhr-custom-status-url" title="Permalink to this headline">¶</a></h3>
|
||||
<div class="admonition note">
|
||||
<p class="first admonition-title">Note</p>
|
||||
<p class="last">XHR stands for XMLHTTPRequest, and is meant here in the AJAX sense (Asynchronous Javascript and XML).</p>
|
||||
@ -1093,7 +1074,7 @@ message will be made.</p>
|
||||
<p>The message itself is sent in the request under the key <tt class="docutils literal"><span class="pre">msg</span></tt>.</p>
|
||||
</div>
|
||||
<div class="section" id="xhr-user-search">
|
||||
<h3><a class="toc-backref" href="#id64">xhr_user_search</a><a class="headerlink" href="#xhr-user-search" title="Permalink to this headline">¶</a></h3>
|
||||
<h3><a class="toc-backref" href="#id67">xhr_user_search</a><a class="headerlink" href="#xhr-user-search" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Default: <tt class="docutils literal"><span class="pre">false</span></tt></p>
|
||||
<div class="admonition note">
|
||||
<p class="first admonition-title">Note</p>
|
||||
@ -1110,7 +1091,7 @@ message will be made.</p>
|
||||
corresponds to a matched user and needs the keys <tt class="docutils literal"><span class="pre">id</span></tt> and <tt class="docutils literal"><span class="pre">fullname</span></tt>.</p>
|
||||
</div>
|
||||
<div class="section" id="xhr-user-search-url">
|
||||
<h3><a class="toc-backref" href="#id65">xhr_user_search_url</a><a class="headerlink" href="#xhr-user-search-url" title="Permalink to this headline">¶</a></h3>
|
||||
<h3><a class="toc-backref" href="#id68">xhr_user_search_url</a><a class="headerlink" href="#xhr-user-search-url" title="Permalink to this headline">¶</a></h3>
|
||||
<div class="admonition note">
|
||||
<p class="first admonition-title">Note</p>
|
||||
<p class="last">XHR stands for XMLHTTPRequest, and is meant here in the AJAX sense (Asynchronous Javascript and XML).</p>
|
||||
|
||||
File diff suppressed because one or more lines are too long
@ -17,16 +17,16 @@ Quickstart (to get a demo up and running)
|
||||
|
||||
When you download a specific release of *Converse.js* there will be two minified files inside the zip file.
|
||||
|
||||
* converse.min.js
|
||||
* converse.min.css
|
||||
* builds/converse.min.js
|
||||
* css/converse.min.css
|
||||
|
||||
You can include these two files inside the *<head>* element of your website via the *script* and *link*
|
||||
tags:
|
||||
|
||||
::
|
||||
|
||||
<link rel="stylesheet" type="text/css" media="screen" href="converse.min.css">
|
||||
<script src="converse.min.js"></script>
|
||||
<link rel="stylesheet" type="text/css" media="screen" href="css/converse.min.css">
|
||||
<script src="builds/converse.min.js"></script>
|
||||
|
||||
You need to initialize Converse.js with configuration settings particular to
|
||||
your requirements.
|
||||
@ -34,7 +34,7 @@ your requirements.
|
||||
Please refer to the `Configuration variables`_ section further below for info on
|
||||
all the available configuration settings.
|
||||
|
||||
To do this, put the following inline Javascript code at the
|
||||
To configure Converse.js, put the following inline Javascript code at the
|
||||
bottom of your page (after the closing *</body>* element).
|
||||
|
||||
::
|
||||
@ -48,12 +48,12 @@ bottom of your page (after the closing *</body>* element).
|
||||
i18n: locales.en, // Refer to ./locale/locales.js to see which locales are supported
|
||||
prebind: false,
|
||||
show_controlbox_by_default: true,
|
||||
xhr_user_search: false
|
||||
roster_groups: true
|
||||
});
|
||||
});
|
||||
|
||||
The `index.html <https://github.com/jcbrand/converse.js/blob/master/index.html>`_ file inside the
|
||||
Converse.js repository serves as a nice usable example of this.
|
||||
Converse.js repository may serve as a nice usable example.
|
||||
|
||||
These minified files provide the same demo-like functionality as is available
|
||||
on the `conversejs.org <http://conversejs.org>`_ website. Useful for testing or demoing, but not very
|
||||
@ -79,7 +79,7 @@ website, *Converse.js* is not really meant to be a "Software-as-a-service" (SaaS
|
||||
webchat.
|
||||
|
||||
Instead, its goal is to provide the means for website owners to add a tightly
|
||||
integrated instant messaging service to their own sites.
|
||||
integrated instant messaging service to their own websites.
|
||||
|
||||
As a website owner, you are expected to host *Converse.js* yourself, and to do some legwork to
|
||||
properly configure and integrate it into your site.
|
||||
@ -114,8 +114,8 @@ You can find a list of public XMPP servers/providers on `xmpp.net`_ and a list o
|
||||
servers that you can set up yourself on `xmpp.org`_.
|
||||
|
||||
|
||||
Connection Manager
|
||||
==================
|
||||
A BOSH Connection Manager
|
||||
=========================
|
||||
|
||||
Your website and *Converse.js* use `HTTP`_ as protocol to communicate with
|
||||
the webserver. HTTP connections are stateless and usually shortlived.
|
||||
@ -127,18 +127,25 @@ To enable a web application like *Converse.js* to communicate with an XMPP
|
||||
server, we need a proxy in the middle that can act as a bridge between the two
|
||||
protocols.
|
||||
|
||||
This is the job of a connection manager. A connection manager can be either a
|
||||
standalone application or part of an XMPP server. `ejabberd`_ for example,
|
||||
includes a connection manager (but you have to enable it).
|
||||
The `index.html <https://github.com/jcbrand/converse.js/blob/master/index.html>`_ file inside the
|
||||
|
||||
The demo on the `Converse.js homepage`_ uses a a connection manager located at https://bind.conversejs.org.
|
||||
This connection manager is for testing purposes only, please don't use it in
|
||||
production.
|
||||
This is the job of a connection manager. A connection manager can be either a
|
||||
standalone application or part of an XMPP server. Popular XMPP servers such as
|
||||
`ejabberd <http://www.ejabberd.im>`_, `prosody <http://prosody.im/doc/setting_up_bosh>`_ and
|
||||
`openfire <http://www.igniterealtime.org/projects/openfire/>`_ all include their own connection managers
|
||||
(but you usually have to enable them in the configuration).
|
||||
|
||||
Standalone connection managers also exist, see for example `Punjab <https://github.com/twonds/punjab>`_.
|
||||
|
||||
The demo on the `Converse.js homepage`_ uses a connection manager located at https://bind.conversejs.org.
|
||||
This connection manager is available for testing purposes only, please don't use it in production.
|
||||
|
||||
Overcoming cross-domain request restrictions
|
||||
--------------------------------------------
|
||||
|
||||
The domain of the *Converse.js* demo is *conversejs.org*, but the domain of the connection manager is *opkode.im*.
|
||||
Lets say your domain is *example.org*, but the domain of your connection
|
||||
manager is *example.com*.
|
||||
|
||||
HTTP requests are made by *Converse.js* to the connection manager via XmlHttpRequests (XHR).
|
||||
Until recently, it was not possible to make such requests to a different domain
|
||||
than the one currently being served (to prevent XSS attacks).
|
||||
@ -281,67 +288,6 @@ Example code for server-side prebinding
|
||||
See this `example Django application`_ by Jack Moffitt.
|
||||
|
||||
|
||||
Setting up a BOSH server
|
||||
------------------------
|
||||
|
||||
The `Movim <http://movim.eu/>`_ project wiki has a very thorough page on setting up a BOSH server for
|
||||
a wide variety of standalone or XMPP servers.
|
||||
|
||||
http://wiki.movim.eu/manual:bosh_servers
|
||||
|
||||
Facebook integration
|
||||
====================
|
||||
|
||||
.. Note ::
|
||||
It should be possible to integrate Converse.js with Facebook chat, and
|
||||
below I'll provide some tips and documentation on how to achieve this. That
|
||||
said, I don't have a Facebook account and therefore haven't tried to do
|
||||
this myself. Feedback and patches from people who have succesfully done this
|
||||
will be appreciated.
|
||||
|
||||
Converse.js uses `Strophe.js <http://strophe.im/strophejs>`_ to connect and
|
||||
communicate with the XMPP server. One nice thing about Strophe.js is that it
|
||||
can be extended via `plugins <http://github.com/strophe/strophejs-plugins>`_.
|
||||
|
||||
Here is a `plugin for authenticating with facebook
|
||||
<https://github.com/kissrobber/turedsocial/blob/master/strophe-plugins/src/facebook.js>`_.
|
||||
|
||||
You will need your own BOSH connection manager to act as a proxy between
|
||||
Converse.js/Strophe.js and Facebook's XMPP server. That is because Facebook's
|
||||
XMPP server doesn't support BOSH natively.
|
||||
|
||||
The BOSH connection manager that I make available for
|
||||
testing purposes (at https://bind.conversejs.org) uses `Punjab <https://github.com/twonds/punjab>`_,
|
||||
although there are quite a few other options available as well.
|
||||
|
||||
When you configure Converse.js, via its ``initialize`` method, you must specify the
|
||||
`bosh_service_url`_ value, which is to be your BOSH connection manager.
|
||||
|
||||
Please note, to enable Facebook integration, you'll have to
|
||||
get your hands dirty and modify Converse.js's code, so that it calls the
|
||||
``facebookConnect`` method of the plugin above.
|
||||
|
||||
The plugin above gives the following code example for you to meditate upon:
|
||||
|
||||
::
|
||||
|
||||
connection = new Strophe.Connection("http://localhost:5280/bosh");
|
||||
connection.facebookConnect(
|
||||
"12345@chat.facebook.com",
|
||||
onConnectFacebook,
|
||||
300,
|
||||
1,
|
||||
'5e64a30272af065bd72258c565a03f2f',
|
||||
'8147a27e4a7f9b55ffc85c2683f9529a',
|
||||
FB.getSession().session_key
|
||||
);
|
||||
|
||||
The connection is already created inside Converse.js, so the
|
||||
``facebookConnect`` method needs to also be called from there.
|
||||
|
||||
If someone submits a sane patch that does the above, I'll be happy to merge it.
|
||||
Until then, people will have to do this themselves.
|
||||
|
||||
========
|
||||
Features
|
||||
========
|
||||
@ -375,6 +321,25 @@ For now, suffice to say that although its useful to have OTR support in
|
||||
Converse.js in order to avoid most eavesdroppers, if you need serious
|
||||
communications privacy, then you're much better off using native software.
|
||||
|
||||
Sound Notifications
|
||||
===================
|
||||
|
||||
From version 0.8.1 Converse.js can play a sound notification when you receive a
|
||||
message.
|
||||
|
||||
For more info, please see the `play_sounds`_ configuration setting.
|
||||
|
||||
Multilingual Support
|
||||
====================
|
||||
|
||||
Converse.js is translated into multiple languages. The default build,
|
||||
``converse.min.js``, includes all languages.
|
||||
|
||||
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
|
||||
make a custom build which includes only those languages that you need.
|
||||
|
||||
===========
|
||||
Development
|
||||
===========
|
||||
@ -982,6 +947,21 @@ i18n
|
||||
Specify the locale/language. The language must be in the ``locales`` object. Refer to
|
||||
``./locale/locales.js`` to see which locales are supported.
|
||||
|
||||
play_sounds
|
||||
-----------
|
||||
|
||||
Default: ``false``
|
||||
|
||||
Inside the ``./sounds`` directory of the Converse.js repo, you'll see MP3 and Ogg
|
||||
formatted sound files. We need both, because neither format is supported by all browsers.
|
||||
|
||||
For now, sound files are looked up by convention, not configuration. So to have
|
||||
a sound play when a message is received, make sure that your webserver serves
|
||||
it in both formats as ``http://yoursite.com/sounds/msg_received.mp3`` and
|
||||
``http://yoursite.com/sounds/msg_received.ogg``.
|
||||
|
||||
``http://yoursite.com`` should of course be your site's URL.
|
||||
|
||||
prebind
|
||||
--------
|
||||
|
||||
|
||||
@ -230,18 +230,16 @@
|
||||
<script>
|
||||
require(['converse'], function (converse) {
|
||||
converse.initialize({
|
||||
auto_reconnect: false, // Still buggy
|
||||
allow_otr: true,
|
||||
auto_list_rooms: false,
|
||||
auto_subscribe: false,
|
||||
bosh_service_url: 'https://bind.conversejs.org', // Please use this connection manager only for testing purposes
|
||||
debug: true ,
|
||||
debug: true,
|
||||
hide_muc_server: false,
|
||||
i18n: locales['en'], // Refer to ./locale/locales.js to see which locales are supported
|
||||
play_sounds: true,
|
||||
prebind: false,
|
||||
show_controlbox_by_default: true,
|
||||
xhr_user_search: false,
|
||||
roster_groups: true
|
||||
});
|
||||
});
|
||||
|
||||
Loading…
Reference in New Issue
Block a user