|
|
@@ -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>
|
JC Brand