<ahref="#id24"><spanclass="problematic"id="id25">`Session Support`_</span></a> (i.e. single-signon functionality whereby users are authenticated once and stay
<h2><aclass="toc-backref"href="#id3">An XMPP/Jabber server</a><aclass="headerlink"href="#an-xmpp-jabber-server"title="Permalink to this headline">¶</a></h2>
<p><em>Converse.js</em> implements <aclass="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>
<h2><aclass="toc-backref"href="#id4">Connection Manager</a><aclass="headerlink"href="#connection-manager"title="Permalink to this headline">¶</a></h2>
<p>Your website and <em>Converse.js</em> use <aclass="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><aclass="reference external"href="https://en.wikipedia.org/wiki/Xmpp">XMPP</a> on the other hand, is the protocol that enables instant messaging, and
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>This is the job of a connection manager. A connection manager can be either a
standalone application or part of an XMPP server. <aclass="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 <aclass="reference external"href="http://conversejs.org">Converse.js homepage</a> uses a a connection manager located at <aclass="reference external"href="https://bind.opkode.im">https://bind.opkode.im</a>.
This connection manager is for testing purposes only, please don’t use it in
<h3><aclass="toc-backref"href="#id5">Overcoming cross-domain request restrictions</a><aclass="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).
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 <aclass="reference external"href="https://en.wikipedia.org/wiki/Cross-origin_resource_sharing">CORS</a> (Cross-origin resource sharing), which enables exactly that.
Modern browsers support CORS, but there are problems with Internet Explorer <
10.</p>
<p>IE 8 and 9 partially support CORS via a proprietary implementation called
XDomainRequest. There is a <aclass="reference external"href="https://gist.github.com/1095825/6b4517276f26b66b01fa97b0a78c01275fdc6ff2">Strophe.js plugin</a> which you can use to enable
support for XDomainRequest when it is present.</p>
<p>In IE < 8, there is no support for CORS.</p>
<p>If you need to support these browsers, you can add a front-end proxy in
Apache/Nginx which serves the connection manager under the same domain as your
website. This will remove the need for any cross-domain XHR support.</p>
<h2><aclass="toc-backref"href="#id6">Server-side authentication</a><aclass="headerlink"href="#server-side-authentication"title="Permalink to this headline">¶</a></h2>
<h3><aclass="toc-backref"href="#id7">Pre-binding and Single Session Support</a><aclass="headerlink"href="#pre-binding-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,
but this will require custom code on your server.</p>
<p>Jack Moffitt has a great <aclass="reference external"href="http://metajack.im/2008/10/03/getting-attached-to-strophe">blogpost</a> about this and even provides an <aclass="reference external"href="https://github.com/metajack/strophejs/tree/master/examples/attach">example Django application</a> to demonstrate it.</p>
<h1><aclass="toc-backref"href="#id8">Quickstart (to get a demo up and running)</a><aclass="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>, say for example version 0.3,
there will be two minified files inside the zip file.</p>
<p>For version 0.3 they will be:</p>
<ulclass="simple">
<li>converse.0.3.min.js</li>
<li>converse.0.3.min.css</li>
</ul>
<p>You can include these two files in your website via the <em>script</em> and <em>link</em>
<p>You might also want to have more fine-grained control of what gets included in
the minified Javascript file. Read <aclass="reference internal"href="#configuration">Configuration</a> and <aclass="reference internal"href="#minification">Minification</a> for more info on how to do
that.</p>
</div>
<divclass="section"id="configuration">
<h1><aclass="toc-backref"href="#id9">Configuration</a><aclass="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>
<p><em>Converse.js</em> is passed its configuration settings when you call its
<em>initialize</em> method.</p>
<p>Please refer to the <aclass="reference internal"href="#configuration-variables">Configuration variables</a> section below for info on
all the available configuration settings.</p>
<p>After you have configured <em>Converse.js</em>, you’ll have to regenerate the minified
JS file so that it will include the new settings. Please refer to the
<aclass="reference internal"href="#minification">Minification</a> section for more info on how to do this.</p>
<divclass="section"id="configuration-variables">
<h2><aclass="toc-backref"href="#id10">Configuration variables</a><aclass="headerlink"href="#configuration-variables"title="Permalink to this headline">¶</a></h2>
<divclass="section"id="animate">
<h3><aclass="toc-backref"href="#id11">animate</a><aclass="headerlink"href="#animate"title="Permalink to this headline">¶</a></h3>
<p>Default = True</p>
<p>Show animations, for example when opening and closing chat boxes.</p>
</div>
<divclass="section"id="auto-list-rooms">
<h3><aclass="toc-backref"href="#id12">auto_list_rooms</a><aclass="headerlink"href="#auto-list-rooms"title="Permalink to this headline">¶</a></h3>
<p>Default = False</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>
<p>Not recommended for servers with lots of chat rooms.</p>
<p>For each room on the server a query is made to fetch further details (e.g.
features, number of occupants etc.), so on servers with many rooms this
option will create lots of extra connection traffic.</p>
</div>
<divclass="section"id="auto-subscribe">
<h3><aclass="toc-backref"href="#id13">auto_subscribe</a><aclass="headerlink"href="#auto-subscribe"title="Permalink to this headline">¶</a></h3>
<p>Default = False</p>
<p>If true, the user will automatically subscribe back to any contact requests.</p>
</div>
<divclass="section"id="bosh-service-url">
<h3><aclass="toc-backref"href="#id14">bosh_service_url</a><aclass="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 <aclass="reference external"href="http://metajack.im/2008/09/08/which-bosh-server-do-you-need/l">here</a> for more information.</p>
</div>
<divclass="section"id="fullname">
<h3><aclass="toc-backref"href="#id15">fullname</a><aclass="headerlink"href="#fullname"title="Permalink to this headline">¶</a></h3>
<p>If you are using prebinding, you need to specify the fullname of the currently
logged in user.</p>
</div>
<divclass="section"id="hide-muc-server">
<h3><aclass="toc-backref"href="#id16">hide_muc_server</a><aclass="headerlink"href="#hide-muc-server"title="Permalink to this headline">¶</a></h3>
<p>Default = False</p>
<p>Hide the <ttclass="docutils literal"><spanclass="pre">server</span></tt> input field of the form inside the <ttclass="docutils literal"><spanclass="pre">Room</span></tt> panel of the
controlbox. Useful if you want to restrict users to a specific XMPP server of
<h3><aclass="toc-backref"href="#id18">show_controlbox_by_default</a><aclass="headerlink"href="#show-controlbox-by-default"title="Permalink to this headline">¶</a></h3>
<p>Default = False</p>
<p>The “controlbox” refers to the special chatbox containing your contacts roster,
status widget, chatrooms and other controls.</p>
<p>By default this box is hidden and can be toggled by clicking on any element in
the page with class <em>toggle-online-users</em>.</p>
<p>If this options is set to true, the controlbox will by default be shown upon
<li>The user inputs a valid JID (Jabber ID), and the user is added as a pending contact.</li>
<li>The user inputs some text (for example part of a firstname or lastname), an XHR will be made to a backend, and a list of matches are returned. The user can then choose one of the matches to add as a contact.</li>
<h2><aclass="toc-backref"href="#id21">Minifying Javascript</a><aclass="headerlink"href="#minifying-javascript"title="Permalink to this headline">¶</a></h2>
containing all translations and from which for each language an individual PO
file is generated.</p>
<p>The POT file contains all translateable strings extracted from converse.js.</p>
<p>To make a user facing string translateable, wrap it in the double underscore helper
function like so:</p>
<divclass="highlight-python"><divclass="highlight"><pre><spanclass="n">__</span><spanclass="p">(</span><spanclass="s">'This string will be translated at runtime'</span><spanclass="p">);</span>
</pre></div>
</div>
<p>After adding the string, you’ll need to regenerate the POT file, like so:</p>
<divclass="highlight-python"><pre>make pot</pre>
</div>
<p>You can then create or update the PO file for a specific language by doing the following:</p>
