<li><aclass="reference internal"href="#install-node-js-and-development-dependencies"id="id12">Install Node.js and development dependencies</a></li>
<li><aclass="reference internal"href="#install-3rd-party-dependencies"id="id13">Install 3rd party dependencies</a></li>
<li><aclass="reference internal"href="#with-amd-and-require-js-recommended"id="id14">With AMD and require.js (recommended)</a></li>
<li><aclass="reference internal"href="#without-amd-and-require-js"id="id15">Without AMD and require.js</a></li>
<li><aclass="reference internal"href="#before-submitting-a-pull-request"id="id16">Before submitting a pull request</a><ul>
<li><aclass="reference internal"href="#add-tests-for-your-bugfix-or-feature"id="id17">Add tests for your bugfix or feature</a></li>
<li><aclass="reference internal"href="#check-that-the-tests-pass"id="id18">Check that the tests pass</a></li>
<li><aclass="reference internal"href="#check-your-code-for-errors-or-bad-habits-by-running-jshint"id="id19">Check your code for errors or bad habits by running JSHint</a></li>
<h1><aclass="toc-backref"href="#id2">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>These minified files provide the same demo-like functionality as is available
on the <aclass="reference external"href="http://conversejs.org">conversejs.org</a> website. Useful for testing or demoing, but not very
practical.</p>
<p>You’ll most likely want to implement some kind of single-signon solution for
your website, where users authenticate once in your website and then stay
logged into their XMPP session upon page reload.</p>
<p>For more info on this, read: <aclass="reference internal"href="#pre-binding-and-single-session-support">Pre-binding and Single Session Support</a>.</p>
<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
<aclass="reference internal"href="#session-support">Session Support</a> (i.e. single-signon functionality whereby users are authenticated once and stay
<h2><aclass="toc-backref"href="#id5">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>
<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="#id7">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>
<h4>For example:<aclass="headerlink"href="#for-example"title="Permalink to this headline">¶</a></h4>
<p>Assuming your site is accessible on port <ttclass="docutils literal"><spanclass="pre">80</span></tt> for the domain <ttclass="docutils literal"><spanclass="pre">mysite.com</span></tt>
and your connection manager manager is running at <ttclass="docutils literal"><spanclass="pre">someothersite.com/http-bind</span></tt>.</p>
<p>The <em>bosh_service_url</em> value you want to give Converse.js to overcome
the cross-domain restriction is <ttclass="docutils literal"><spanclass="pre">mysite.com/http-bind</span></tt> and not
<p>Your <ttclass="docutils literal"><spanclass="pre">nginx</span></tt> or <ttclass="docutils literal"><spanclass="pre">apache</span></tt> configuration will look as follows:</p>
</div>
<divclass="section"id="nginx">
<h4>Nginx<aclass="headerlink"href="#nginx"title="Permalink to this headline">¶</a></h4>
<divclass="highlight-python"><pre>http {
server {
listen 80
server_name mysite.com;
location ~ ^/http-bind/ {
proxy_pass http://someothersite.com;
}
}
}</pre>
</div>
</div>
<divclass="section"id="apache">
<h4>Apache<aclass="headerlink"href="#apache"title="Permalink to this headline">¶</a></h4>
<h2><aclass="toc-backref"href="#id8">Server-side authentication</a><aclass="headerlink"href="#server-side-authentication"title="Permalink to this headline">¶</a></h2>
<spanid="session-support"></span><h3><aclass="toc-backref"href="#id9">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>
<h2><aclass="toc-backref"href="#id10">Facebook integration</a><aclass="headerlink"href="#facebook-integration"title="Permalink to this headline">¶</a></h2>
<pclass="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 <aclass="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 <aclass="reference external"href="http://github.com/strophe/strophejs-plugins">plugins</a>.</p>
<p>Here is a <aclass="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
<h2><aclass="toc-backref"href="#id12">Install Node.js and development dependencies</a><aclass="headerlink"href="#install-node-js-and-development-dependencies"title="Permalink to this headline">¶</a></h2>
<p>We use development tools (<aclass="reference external"href="http://gruntjs.com">Grunt</a> and <aclass="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
version <aclass="reference external"href="https://nodejs.org/download">here</a>.</p>
<h2><aclass="toc-backref"href="#id13">Install 3rd party dependencies</a><aclass="headerlink"href="#install-3rd-party-dependencies"title="Permalink to this headline">¶</a></h2>
<p>After running <ttclass="docutils literal"><spanclass="pre">npm</span><spanclass="pre">install</span></tt>, you will now have Grunt and Bower installed.</p>
<p>We use Bower to manage Converse’s front-end dependencies (e.g. Javascript that
<h2><aclass="toc-backref"href="#id14">With AMD and require.js (recommended)</a><aclass="headerlink"href="#with-amd-and-require-js-recommended"title="Permalink to this headline">¶</a></h2>
<h2><aclass="toc-backref"href="#id15">Without AMD and require.js</a><aclass="headerlink"href="#without-amd-and-require-js"title="Permalink to this headline">¶</a></h2>
<h2><aclass="toc-backref"href="#id16">Before submitting a pull request</a><aclass="headerlink"href="#before-submitting-a-pull-request"title="Permalink to this headline">¶</a></h2>
<h3><aclass="toc-backref"href="#id17">Add tests for your bugfix or feature</a><aclass="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 <ttclass="docutils literal"><spanclass="pre">tests.html</span></tt> and <ttclass="docutils literal"><spanclass="pre">spec/MainSpec.js</span></tt> to see how
<h3><aclass="toc-backref"href="#id18">Check that the tests pass</a><aclass="headerlink"href="#check-that-the-tests-pass"title="Permalink to this headline">¶</a></h3>
<h3><aclass="toc-backref"href="#id19">Check your code for errors or bad habits by running JSHint</a><aclass="headerlink"href="#check-your-code-for-errors-or-bad-habits-by-running-jshint"title="Permalink to this headline">¶</a></h3>
<h2><aclass="toc-backref"href="#id21">Configuration variables</a><aclass="headerlink"href="#configuration-variables"title="Permalink to this headline">¶</a></h2>
<h3><aclass="toc-backref"href="#id22">allow_contact_requests</a><aclass="headerlink"href="#allow-contact-requests"title="Permalink to this headline">¶</a></h3>
<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
<p>For prebinding to work, your backend server must authenticate for you, and
then return a JID (jabber ID), SID (session ID) and RID (Request ID).</p>
<p>If you set <ttclass="docutils literal"><spanclass="pre">prebind</span></tt> to <ttclass="docutils literal"><spanclass="pre">true</span></tt>, you have to make sure to also pass in these
values as <ttclass="docutils literal"><spanclass="pre">jid</span></tt>, <ttclass="docutils literal"><spanclass="pre">sid</span></tt>, <ttclass="docutils literal"><spanclass="pre">rid</span></tt>.</p>
<p>Additionally, you have to specify <ttclass="docutils literal"><spanclass="pre">bosh_service_url</span></tt>.</p>
<h3><aclass="toc-backref"href="#id33">show_controlbox_by_default</a><aclass="headerlink"href="#show-controlbox-by-default"title="Permalink to this headline">¶</a></h3>
<h3><aclass="toc-backref"href="#id34">show_only_online_users</a><aclass="headerlink"href="#show-only-online-users"title="Permalink to this headline">¶</a></h3>
<pclass="last">XHR stands for XMLHTTPRequest, and is meant here in the AJAX sense (Asynchronous Javascript and XML).</p>
</div>
<p>This option will let converse.js make an AJAX POST with your changed custom chat status to a
remote server.</p>
</div>
<divclass="section"id="xhr-custom-status-url">
<h3><aclass="toc-backref"href="#id36">xhr_custom_status_url</a><aclass="headerlink"href="#xhr-custom-status-url"title="Permalink to this headline">¶</a></h3>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">XHR stands for XMLHTTPRequest, and is meant here in the AJAX sense (Asynchronous Javascript and XML).</p>
</div>
<p>Default = Empty string</p>
<p>Used only in conjunction with <ttclass="docutils literal"><spanclass="pre">xhr_custom_status</span></tt>.</p>
<p>This is the URL to which the AJAX POST request to set the user’s custom status
message will be made.</p>
<p>The message itself is sent in the request under the key <ttclass="docutils literal"><spanclass="pre">msg</span></tt>.</p>
<li>The user inputs some text (for example part of a firstname or lastname), an XHR (Ajax Request) will be made to a remote server, and a list of matches are returned. The user can then choose one of the matches to add as a contact.</li>
<p>This setting enables the second mechanism, otherwise by default the first will be used.</p>
<p><em>What is expected from the remote server?</em></p>
<p>A default JSON encoded list of objects must be returned. Each object
corresponds to a matched user and needs the keys <ttclass="docutils literal"><spanclass="pre">id</span></tt> and <ttclass="docutils literal"><spanclass="pre">fullname</span></tt>.</p>
</div>
<divclass="section"id="xhr-user-search-url">
<h3><aclass="toc-backref"href="#id38">xhr_user_search_url</a><aclass="headerlink"href="#xhr-user-search-url"title="Permalink to this headline">¶</a></h3>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">XHR stands for XMLHTTPRequest, and is meant here in the AJAX sense (Asynchronous Javascript and XML).</p>
</div>
<p>Default = Empty string</p>
<p>Used only in conjunction with <ttclass="docutils literal"><spanclass="pre">xhr_user_search</span></tt>.</p>
<p>This is the URL to which an AJAX GET request will be made to fetch user data from your remote server.
The query string will be included in the request with <ttclass="docutils literal"><spanclass="pre">q</span></tt> as its key.</p>
<h2><aclass="toc-backref"href="#id40">Minifying Javascript and CSS</a><aclass="headerlink"href="#minifying-javascript-and-css"title="Permalink to this headline">¶</a></h2>
<p>Please make sure to read the section <aclass="reference internal"href="#development">Development</a> and that you have installed
all development dependencies (long story short, you can run <ttclass="docutils literal"><spanclass="pre">npm</span><spanclass="pre">install</span></tt>
and then <ttclass="docutils literal"><spanclass="pre">grunt</span><spanclass="pre">fetch</span></tt>).</p>
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>
<p>Unfortunately <aclass="reference external"href="http://slexaxton.github.io/Jed">Jed</a> cannot use the PO files directly. We have to generate from it
