2013-04-26 21:01:39 +02:00
< !DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
< html xmlns = "http://www.w3.org/1999/xhtml" >
< head >
< meta http-equiv = "Content-Type" content = "text/html; charset=utf-8" / >
2013-05-22 19:29:46 +02:00
< title > Introduction — Converse.js 0.3 documentation< / title >
2013-04-26 21:01:39 +02:00
2013-04-26 21:49:26 +02:00
< link rel = "stylesheet" href = "_static/stylesheet.css" type = "text/css" / >
2013-04-26 21:01:39 +02:00
< link rel = "stylesheet" href = "_static/pygments.css" type = "text/css" / >
< script type = "text/javascript" >
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '0.3',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
< / script >
< script type = "text/javascript" src = "_static/jquery.js" > < / script >
< script type = "text/javascript" src = "_static/underscore.js" > < / script >
< script type = "text/javascript" src = "_static/doctools.js" > < / script >
< link rel = "top" title = "Converse.js 0.3 documentation" href = "#" / >
< / head >
< body >
2013-04-26 21:49:26 +02:00
< div id = "header_wrap" class = "outer" >
< header class = "inner" >
< a id = "forkme_banner" href = "https://github.com/jcbrand/converse.js" > View on GitHub< / a >
< h1 id = "project_title" > < a href = "http://conversejs.org" > Converse.js< / a > < / h1 >
< h2 id = "project_tagline" > Documentation< / h2 >
< section id = "downloads" >
< a class = "zip_download_link" href = "https://github.com/jcbrand/converse.js/zipball/master" > Download this project as a .zip file< / a >
< a class = "tar_download_link" href = "https://github.com/jcbrand/converse.js/tarball/master" > Download this project as a tar.gz file< / a >
< / section >
< / header >
< / div >
< div id = "main_content_wrap" class = "outer" >
2013-04-26 21:01:39 +02:00
< div class = "related" >
< h3 > Navigation< / h3 >
< ul >
< li class = "right" style = "margin-right: 10px" >
< a href = "genindex.html" title = "General Index"
accesskey="I">index< / a > < / li >
< li > < a href = "#" > Converse.js 0.3 documentation< / a > » < / li >
< / ul >
2013-04-26 21:49:26 +02:00
< / div >
< section id = "main_content" class = "inner" >
2013-04-26 21:01:39 +02:00
< div class = "document" >
< div class = "documentwrapper" >
< div class = "body" >
2013-04-26 21:49:26 +02:00
< div class = "toctree-wrapper compound" >
2013-04-26 21:01:39 +02:00
< ul class = "simple" >
< / ul >
< / div >
< div class = "contents local topic" id = "table-of-contents" >
< p class = "topic-title first" > Table of Contents< / p >
< ul class = "simple" >
2013-05-22 19:29:46 +02:00
< li > < a class = "reference internal" href = "#introduction" id = "id1" > Introduction< / a > < / li >
< li > < a class = "reference internal" href = "#what-you-will-need" id = "id2" > What you will need< / a > < ul >
< li > < a class = "reference internal" href = "#an-xmpp-jabber-server" id = "id3" > An XMPP/Jabber server< / a > < / li >
2013-05-17 12:48:05 +02:00
< li > < a class = "reference internal" href = "#connection-manager" id = "id4" > Connection Manager< / a > < ul >
< li > < a class = "reference internal" href = "#overcoming-cross-domain-request-restrictions" id = "id5" > Overcoming cross-domain request restrictions< / a > < / li >
< / ul >
< / li >
2013-05-22 19:29:46 +02:00
< li > < a class = "reference internal" href = "#server-side-authentication" id = "id6" > Server-side authentication< / a > < ul >
2013-06-03 22:48:34 +02:00
< li > < a class = "reference internal" href = "#pre-binding-and-single-session-support" id = "id7" > Pre-binding and Single Session Support< / a > < / li >
2013-05-17 12:48:05 +02:00
< / ul >
< / li >
2013-05-22 19:29:46 +02:00
< / ul >
< / li >
< li > < a class = "reference internal" href = "#quickstart-to-get-a-demo-up-and-running" id = "id8" > Quickstart (to get a demo up and running)< / a > < / li >
2013-07-27 01:48:10 +02:00
< li > < a class = "reference internal" href = "#development" id = "id9" > Development< / a > < / li >
< li > < a class = "reference internal" href = "#configuration" id = "id10" > Configuration< / a > < ul >
< li > < a class = "reference internal" href = "#configuration-variables" id = "id11" > Configuration variables< / a > < ul >
< li > < a class = "reference internal" href = "#animate" id = "id12" > animate< / a > < / li >
< li > < a class = "reference internal" href = "#auto-list-rooms" id = "id13" > auto_list_rooms< / a > < / li >
< li > < a class = "reference internal" href = "#auto-subscribe" id = "id14" > auto_subscribe< / a > < / li >
< li > < a class = "reference internal" href = "#bosh-service-url" id = "id15" > bosh_service_url< / a > < / li >
< li > < a class = "reference internal" href = "#fullname" id = "id16" > fullname< / a > < / li >
< li > < a class = "reference internal" href = "#hide-muc-server" id = "id17" > hide_muc_server< / a > < / li >
< li > < a class = "reference internal" href = "#prebind" id = "id18" > prebind< / a > < / li >
< li > < a class = "reference internal" href = "#show-controlbox-by-default" id = "id19" > show_controlbox_by_default< / a > < / li >
< li > < a class = "reference internal" href = "#xhr-user-search" id = "id20" > xhr_user_search< / a > < / li >
2013-05-22 19:29:46 +02:00
< / ul >
< / li >
< / ul >
< / li >
2013-07-27 01:48:10 +02:00
< li > < a class = "reference internal" href = "#minification" id = "id21" > Minification< / a > < ul >
< li > < a class = "reference internal" href = "#minifying-javascript" id = "id22" > Minifying Javascript< / a > < / li >
< li > < a class = "reference internal" href = "#minifying-css" id = "id23" > Minifying CSS< / a > < / li >
2013-04-26 21:01:39 +02:00
< / ul >
< / li >
2013-07-27 01:48:10 +02:00
< li > < a class = "reference internal" href = "#translations" id = "id24" > Translations< / a > < / li >
2013-04-26 21:01:39 +02:00
< / ul >
< / div >
2013-05-22 19:29:46 +02:00
< div class = "section" id = "introduction" >
< h1 > < a class = "toc-backref" href = "#id1" > 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 >
2013-05-28 21:02:11 +02:00
website, < em > Converse.js< / em > is not really meant to be a “ Software-as-a-service” (SaaS)
2013-05-22 19:29:46 +02:00
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 >
< p > As a website owner, you are expected to host < em > Converse.js< / em > yourself, and to do some legwork to
2013-05-28 21:02:11 +02:00
properly configure and integrate it into your site.< / p >
2013-05-22 19:29:46 +02:00
< p > The benefit in doing this, is that your users have a much more streamlined and integrated
webchat experience and that you have control over the data. The latter being a
requirement for many sites dealing with sensitive information.< / p >
< p > You’ ll need to set up your own XMPP server and in order to have
2013-07-25 00:09:09 +02:00
< a class = "reference internal" href = "#session-support" > Session Support< / a > (i.e. single-signon functionality whereby users are authenticated once and stay
2013-05-28 21:02:11 +02:00
logged in to XMPP upon page reload) you will also have to add some server-side
2013-05-22 19:29:46 +02:00
code.< / p >
< p > The < a class = "reference internal" href = "#what-you-will-need" > What you will need< / a > section has more information on all these
requirements.< / p >
< / div >
2013-05-17 12:48:05 +02:00
< div class = "section" id = "what-you-will-need" >
2013-05-22 19:29:46 +02:00
< h1 > < a class = "toc-backref" href = "#id2" > What you will need< / a > < a class = "headerlink" href = "#what-you-will-need" title = "Permalink to this headline" > ¶< / a > < / h1 >
2013-05-17 12:48:05 +02:00
< div class = "section" id = "an-xmpp-jabber-server" >
2013-05-22 19:29:46 +02:00
< h2 > < a class = "toc-backref" href = "#id3" > An XMPP/Jabber server< / a > < a class = "headerlink" href = "#an-xmpp-jabber-server" title = "Permalink to this headline" > ¶< / a > < / h2 >
2013-05-17 12:48:05 +02:00
< 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 >
2013-05-28 21:02:11 +02:00
< 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
2013-07-25 00:09:09 +02:00
have < a class = "reference internal" href = "#session-support" > Session Support< / a > you’ ll have to set up your own XMPP server.< / p >
2013-05-28 21:02:11 +02:00
< 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 >
2013-05-17 12:48:05 +02:00
< / div >
< div class = "section" id = "connection-manager" >
< h2 > < a class = "toc-backref" href = "#id4" > Connection Manager< / a > < a class = "headerlink" href = "#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
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. < 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.opkode.im" > https://bind.opkode.im< / a > .
This connection manager is 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 = "#id5" > 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).
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.
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 < a class = "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 >
< / div >
< / div >
2013-05-22 19:29:46 +02:00
< div class = "section" id = "server-side-authentication" >
< h2 > < a class = "toc-backref" href = "#id6" > Server-side authentication< / a > < a class = "headerlink" href = "#server-side-authentication" title = "Permalink to this headline" > ¶< / a > < / h2 >
2013-06-03 22:48:34 +02:00
< div class = "section" id = "pre-binding-and-single-session-support" >
2013-07-25 00:09:09 +02:00
< span id = "session-support" > < / span > < h3 > < a class = "toc-backref" href = "#id7" > Pre-binding and Single Session Support< / a > < a class = "headerlink" href = "#pre-binding-and-single-session-support" title = "Permalink to this headline" > ¶< / a > < / h3 >
2013-05-22 19:29:46 +02:00
< 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 < a class = "reference external" href = "http://metajack.im/2008/10/03/getting-attached-to-strophe" > blogpost< / a > about this and even provides an < a class = "reference external" href = "https://github.com/metajack/strophejs/tree/master/examples/attach" > example Django application< / a > to demonstrate it.< / p >
2013-06-03 22:48:34 +02:00
< div class = "admonition note" >
< p class = "first admonition-title" > Note< / p >
< p class = "last" > If you want to enable single session support, make sure to pass < strong > prebind: true< / strong >
2013-07-25 00:09:09 +02:00
when you call < strong > converse.initialize< / strong > (see ./index.html).< / p >
2013-06-03 22:48:34 +02:00
< / div >
2013-06-03 22:42:34 +02:00
< p > When you authenticate to the XMPP server on your backend, you’ ll receive two
tokens, RID (request ID) and SID (session ID).< / p >
< p > These tokens then need to be passed back to the javascript running in your
browser, where you will need them attach to the existing session.< / p >
< p > You can embed the RID and SID tokens in your HTML markup or you can do an
XMLHttpRequest call to you server and ask it to return them for you.< / p >
< p > Below is one example of how this could work. An Ajax call is made to the
relative URL < strong > /prebind< / strong > and it expects to receive JSON data back.< / p >
< div class = "highlight-python" > < pre > $.getJSON('/prebind', function (data) {
var connection = new Strophe.Connection(converse.bosh_service_url);
connection.attach(data.jid, data.sid, data.rid, function (status) {
if ((status === Strophe.Status.ATTACHED) || (status === Strophe.Status.CONNECTED)) {
converse.onConnected(connection)
}
});
}
);< / pre >
< / div >
< p > < strong > Here’ s what’ s happening:< / strong > < / p >
< p > The JSON data contains the user’ s JID (jabber ID), RID and SID. The URL to the
BOSH connection manager is already set as a configuration setting on the
< em > converse< / em > object (see ./main.js), so we can reuse it from there.< / p >
< p > A new Strophe.Connection object is instantiated and then < em > attach< / em > is called with
the user’ s JID, the necessary tokens and a callback function.< / p >
< p > In the callback function, you call < em > converse.onConnected< / em > together with the
connection object.< / p >
2013-05-22 19:29:46 +02:00
< / div >
< / div >
< / div >
< div class = "section" id = "quickstart-to-get-a-demo-up-and-running" >
< h1 > < a class = "toc-backref" href = "#id8" > 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 >
2013-07-25 00:09:09 +02:00
< p > When you download a specific release of < em > Converse.js< / em > there will be two minified files inside the zip file.< / p >
2013-05-22 19:29:46 +02:00
< ul class = "simple" >
2013-07-25 00:09:09 +02:00
< li > converse.min.js< / li >
< li > converse.min.css< / li >
2013-05-22 19:29:46 +02:00
< / ul >
2013-07-25 00:09:09 +02:00
< 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 >
2013-05-22 19:29:46 +02:00
tags:< / p >
2013-07-25 00:09:09 +02:00
< div class = "highlight-python" > < pre > < link rel="stylesheet" type="text/css" media="screen" href="converse.min.css">
< script src="converse.min.js"> < /script> < / pre >
< / div >
< p > Then, at the bottom of your page, after the closing < em > < /body> < / em > element, put the
following inline Javascript code:< / p >
2013-07-27 01:48:10 +02:00
< div class = "highlight-python" > < pre > require(['converse'], function (converse) {
2013-07-25 00:09:09 +02:00
converse.initialize({
auto_list_rooms: false,
auto_subscribe: false,
bosh_service_url: 'https://bind.opkode.im', // Please use this connection manager only for testing purposes
hide_muc_server: false,
i18n: locales.en, // Refer to ./locale/locales.js to see which locales are supported
prebind: false,
show_controlbox_by_default: true,
xhr_user_search: false
});
2013-07-27 01:48:10 +02:00
});< / pre >
2013-05-22 19:29:46 +02:00
< / div >
< p > The < em > index.html< / em > file inside the Converse.js folder serves as a nice usable
example of this.< / 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 >
< 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 >
2013-07-25 00:09:09 +02:00
< p > For more info on this, read: < a class = "reference internal" href = "#pre-binding-and-single-session-support" > Pre-binding and Single Session Support< / a > .< / p >
2013-05-22 19:29:46 +02:00
< p > You might also want to have more fine-grained control of what gets included in
the minified Javascript file. Read < a class = "reference internal" href = "#configuration" > Configuration< / a > and < a class = "reference internal" href = "#minification" > Minification< / a > for more info on how to do
that.< / p >
< / div >
2013-07-27 01:48:10 +02:00
< div class = "section" id = "development" >
< h1 > < a class = "toc-backref" href = "#id9" > Development< / a > < a class = "headerlink" href = "#development" title = "Permalink to this headline" > ¶< / a > < / h1 >
< p > Converse.js uses < a class = "reference external" href = "http://requirejs.org" > require.js< / a > to track and load dependencies.< / p >
< p > If you want to develop or customize converse.js, you’ ll want to load the
non-minified javascript files.< / p >
< p > Add the following two lines to the < em > < head> < / em > section of your webpage.< / p >
< div class = "highlight-python" > < pre > < link rel="stylesheet" type="text/css" media="screen" href="converse.css">
< script data-main="main" src="Libraries/require-jquery.js"> < /script> < / pre >
< / div >
< p > Converse.js can also be used without require.js. If you for some reason prefer
to use it this way, please refer to < em > non_amd.html< / em > for an example of how and in
what order all the Javascript files that converse.js depends on need to be
loaded.< / p >
< / div >
2013-05-22 19:29:46 +02:00
< div class = "section" id = "configuration" >
2013-07-27 01:48:10 +02:00
< h1 > < a class = "toc-backref" href = "#id10" > Configuration< / a > < a class = "headerlink" href = "#configuration" title = "Permalink to this headline" > ¶< / a > < / h1 >
2013-05-22 19:29:46 +02:00
< 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 >
2013-07-25 00:09:09 +02:00
< p > You’ ll most likely want to call the < em > initialize< / em > method in your HTML page. For
an example of how this is done, please see the bottom of the < em > ./index.html< / em > page.< / p >
2013-05-22 19:29:46 +02:00
< p > Please refer to the < a class = "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
< a class = "reference internal" href = "#minification" > Minification< / a > section for more info on how to do this.< / p >
< div class = "section" id = "configuration-variables" >
2013-07-27 01:48:10 +02:00
< h2 > < a class = "toc-backref" href = "#id11" > Configuration variables< / a > < a class = "headerlink" href = "#configuration-variables" title = "Permalink to this headline" > ¶< / a > < / h2 >
2013-05-22 19:29:46 +02:00
< div class = "section" id = "animate" >
2013-07-27 01:48:10 +02:00
< h3 > < a class = "toc-backref" href = "#id12" > animate< / a > < a class = "headerlink" href = "#animate" title = "Permalink to this headline" > ¶< / a > < / h3 >
2013-05-22 19:29:46 +02:00
< p > Default = True< / p >
< p > Show animations, for example when opening and closing chat boxes.< / p >
< / div >
< div class = "section" id = "auto-list-rooms" >
2013-07-27 01:48:10 +02:00
< h3 > < a class = "toc-backref" href = "#id13" > auto_list_rooms< / a > < a class = "headerlink" href = "#auto-list-rooms" title = "Permalink to this headline" > ¶< / a > < / h3 >
2013-05-22 19:29:46 +02:00
< 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 >
< div class = "section" id = "auto-subscribe" >
2013-07-27 01:48:10 +02:00
< h3 > < a class = "toc-backref" href = "#id14" > auto_subscribe< / a > < a class = "headerlink" href = "#auto-subscribe" title = "Permalink to this headline" > ¶< / a > < / h3 >
2013-05-22 19:29:46 +02:00
< p > Default = False< / p >
< p > If true, the user will automatically subscribe back to any contact requests.< / p >
< / div >
< div class = "section" id = "bosh-service-url" >
2013-07-27 01:48:10 +02:00
< h3 > < a class = "toc-backref" href = "#id15" > bosh_service_url< / a > < a class = "headerlink" href = "#bosh-service-url" title = "Permalink to this headline" > ¶< / a > < / h3 >
2013-05-22 19:29:46 +02:00
< 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/l" > here< / a > for more information.< / p >
< / div >
< div class = "section" id = "fullname" >
2013-07-27 01:48:10 +02:00
< h3 > < a class = "toc-backref" href = "#id16" > fullname< / a > < a class = "headerlink" href = "#fullname" title = "Permalink to this headline" > ¶< / a > < / h3 >
2013-05-22 19:29:46 +02:00
< p > If you are using prebinding, you need to specify the fullname of the currently
logged in user.< / p >
< / div >
< div class = "section" id = "hide-muc-server" >
2013-07-27 01:48:10 +02:00
< h3 > < a class = "toc-backref" href = "#id17" > hide_muc_server< / a > < a class = "headerlink" href = "#hide-muc-server" title = "Permalink to this headline" > ¶< / a > < / h3 >
2013-05-22 19:29:46 +02:00
< p > Default = False< / 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 >
2013-05-17 12:48:05 +02:00
< / div >
2013-04-26 21:01:39 +02:00
< div class = "section" id = "prebind" >
2013-07-27 01:48:10 +02:00
< h3 > < a class = "toc-backref" href = "#id18" > prebind< / a > < a class = "headerlink" href = "#prebind" title = "Permalink to this headline" > ¶< / a > < / h3 >
2013-05-22 19:29:46 +02:00
< p > Default = False< / p >
2013-04-26 21:01:39 +02:00
< 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 >
< p > This is useful when you don’ t want to render the login form on the chat control
box with each page load.< / p >
< p > When set to true, you’ ll need to make sure that the onConnected method is
called, and passed to it a Strophe connection object.< / p >
< p > Besides requiring the back-end to authenticate you, you’ ll also
have to write a Javascript snippet to attach to the set up connection:< / p >
< div class = "highlight-python" > < pre > $.JSON({
'url': 'mysite.com/xmpp-authenticate',
'success': function (data) {
connection = new Strophe.Connection(bosh_service_url);
connection.attach(data.jid, data.sid, data.rid, converse.onConnected);
}< / pre >
< / div >
< p > The backend must authenticate for you, and then return a SID (session ID) and
RID (Request ID), which you use when you attach to the connection.< / p >
< / div >
2013-06-03 22:42:34 +02:00
< div class = "section" id = "show-controlbox-by-default" >
2013-07-27 01:48:10 +02:00
< h3 > < a class = "toc-backref" href = "#id19" > show_controlbox_by_default< / a > < a class = "headerlink" href = "#show-controlbox-by-default" title = "Permalink to this headline" > ¶< / a > < / h3 >
2013-06-03 22:42:34 +02:00
< 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
page load.< / p >
< / div >
2013-04-26 21:01:39 +02:00
< div class = "section" id = "xhr-user-search" >
2013-07-27 01:48:10 +02:00
< h3 > < a class = "toc-backref" href = "#id20" > xhr_user_search< / a > < a class = "headerlink" href = "#xhr-user-search" title = "Permalink to this headline" > ¶< / a > < / h3 >
2013-05-22 19:29:46 +02:00
< p > Default = False< / p >
2013-04-26 21:01:39 +02:00
< p > There are two ways to add users.< / p >
< ul class = "simple" >
2013-05-22 19:29:46 +02:00
< 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 >
2013-04-26 21:01:39 +02:00
< / ul >
< p > This setting enables the second mechanism, otherwise by default the first will
be used.< / p >
< / div >
< / div >
2013-05-17 12:48:05 +02:00
< / div >
2013-05-22 19:29:46 +02:00
< div class = "section" id = "minification" >
2013-07-27 01:48:10 +02:00
< h1 > < a class = "toc-backref" href = "#id21" > Minification< / a > < a class = "headerlink" href = "#minification" title = "Permalink to this headline" > ¶< / a > < / h1 >
2013-05-22 19:29:46 +02:00
< div class = "section" id = "minifying-javascript" >
2013-07-27 01:48:10 +02:00
< h2 > < a class = "toc-backref" href = "#id22" > Minifying Javascript< / a > < a class = "headerlink" href = "#minifying-javascript" title = "Permalink to this headline" > ¶< / a > < / h2 >
2013-05-22 19:29:46 +02:00
< p > We use < a class = "reference external" href = "http://requirejs.org" > require.js< / a > to keep track of < em > Converse.js< / em > and its dependencies and to
to bundle them together in a single minified file fit for deployment to a
production site.< / p >
< p > To use the require.js’ s optimization tool, you’ ll need Node and it’ s package
manager, NPM.< / p >
< p > You can then install install require.js for Node like so:< / p >
< div class = "highlight-python" > < pre > npm install requirejs< / pre >
< / div >
< p > The minified javascript file is then created like this:< / p >
< div class = "highlight-python" > < pre > r.js -o build.js< / pre >
< / div >
< p > You should now have a new minified file (the name which is specified in build.js).< / p >
< p > You can < a class = "reference external" href = "http://requirejs.org/docs/optimization.html" > read more about require.js’ s optimizer here< / a > .< / p >
< / div >
< div class = "section" id = "minifying-css" >
2013-07-27 01:48:10 +02:00
< h2 > < a class = "toc-backref" href = "#id23" > Minifying CSS< / a > < a class = "headerlink" href = "#minifying-css" title = "Permalink to this headline" > ¶< / a > < / h2 >
2013-05-22 19:29:46 +02:00
< p > CSS can be minimized with Yahoo’ s yuicompressor tool:< / p >
< div class = "highlight-python" > < pre > yui-compressor --type=css converse.css -o converse.min.css< / pre >
< / div >
2013-04-26 21:01:39 +02:00
< / div >
2013-06-02 00:23:24 +02:00
< / div >
< div class = "section" id = "translations" >
2013-07-27 01:48:10 +02:00
< h1 > < a class = "toc-backref" href = "#id24" > Translations< / a > < a class = "headerlink" href = "#translations" title = "Permalink to this headline" > ¶< / a > < / h1 >
2013-07-25 00:09:09 +02:00
< 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.
2013-07-25 00:21:42 +02:00
At the time of writing, all the translations add about 50KB of extra data to
the minified javascript file. Therefore, make sure to only
2013-07-25 00:09:09 +02:00
include those languages that you intend to support and remove from
./locale/locales.js those which you don’ t need. Remember to rebuild the
minified file afterwards.< / p >
< / div >
2013-06-02 19:44:06 +02:00
< p > The gettext POT file located in ./locale/converse.pot is the template
2013-06-02 00:23:24 +02:00
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 >
< div class = "highlight-python" > < div class = "highlight" > < pre > < span class = "n" > __< / span > < span class = "p" > (< / span > < span class = "s" > ' This string will be translated at runtime' < / span > < span class = "p" > );< / span >
< / pre > < / div >
< / div >
< p > After adding the string, you’ ll need to regenerate the POT file, like so:< / p >
< div class = "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 >
2013-06-02 19:44:06 +02:00
< div class = "highlight-python" > < pre > msgmerge ./locale/af/LC_MESSAGES/converse.po ./locale/converse.pot -U< / pre >
2013-06-02 00:23:24 +02:00
< / div >
< p > This PO file is then what gets translated.< / p >
< p > If you’ ve created a new PO file, please make sure to add the following
attributes at the top of the file (under < em > Content-Transfer-Encoding< / em > ). They are
required as configuration settings for Jed, the Javascript translations library
that we’ re using.< / p >
< div class = "highlight-python" > < div class = "highlight" > < pre > < span class = "s" > " domain: converse< / span > < span class = "se" > \n< / span > < span class = "s" > " < / span >
2013-06-02 19:44:06 +02:00
< span class = "s" > " lang: af< / span > < span class = "se" > \n< / span > < span class = "s" > " < / span >
2013-06-02 00:23:24 +02:00
< span class = "s" > " plural_forms: nplurals=2; plural=(n != 1);< / span > < span class = "se" > \n< / span > < span class = "s" > " < / span >
< / pre > < / div >
< / div >
< p > Unfortunately Jed cannot use the PO files directly. We have to generate from it
a file in JSON format and then put that in a .js file for the specific
language.< / p >
< p > To generate JSON from a PO file, you’ ll need po2json for node.js. Run the
following command to install it (npm being the node.js package manager):< / p >
< div class = "highlight-python" > < pre > npm install po2json< / pre >
< / div >
< p > You can then convert the translations into JSON format:< / p >
2013-06-02 19:44:06 +02:00
< div class = "highlight-python" > < pre > po2json locale/af/LC_MESSAGES/converse.po locale/af/LC_MESSAGES/converse.json< / pre >
2013-06-02 00:23:24 +02:00
< / div >
< p > Now from converse.json paste the data as a value for the “ locale_data” key in the
object in the language’ s .js file.< / p >
< p > So, if you are for example translating into German (language code ‘ de’ ), you’ ll
create or update the file ./locale/LC_MESSAGES/de.js with the following code:< / p >
< div class = "highlight-python" > < pre > (function (root, factory) {
define("af", ['jed'], function () {
return factory(new Jed({
"domain": "converse",
"locale_data": {
// Paste the JSON data from converse.json here
}
})
}
}(this, function (i18n) {
return i18n;
}));< / pre >
< / div >
< p > making sure to also paste the JSON data as value to the “ locale_data” key.< / p >
2013-06-02 19:44:06 +02:00
< div class = "admonition note" >
< p class = "first admonition-title" > Note< / p >
< p class = "last" > If you are adding translations for a new language that is not already supported,
you’ ll have to make one more edit in ./locale/locales.js to make sure the
language is loaded by require.js.< / p >
< / div >
2013-06-02 00:23:24 +02:00
< p > Congratulations, you’ ve now succesfully added your translations. Sorry for all
those hoops you had to jump through.< / p >
2013-04-26 21:01:39 +02:00
< / div >
< / div >
< / div >
< div class = "clearer" > < / div >
< / div >
2013-04-26 21:49:26 +02:00
< / section >
2013-04-26 21:01:39 +02:00
< div class = "related" >
< h3 > Navigation< / h3 >
< ul >
< li class = "right" style = "margin-right: 10px" >
< a href = "genindex.html" title = "General Index"
>index< / a > < / li >
< li > < a href = "#" > Converse.js 0.3 documentation< / a > » < / li >
< / ul >
< / div >
2013-04-26 21:49:26 +02:00
< / div >
< div id = "footer_wrap" class = "outer" >
< footer class = "inner" >
2013-04-26 21:01:39 +02:00
© Copyright 2013, JC Brand.
2013-04-26 21:49:26 +02:00
< p class = "copyright" > Converse.js created by < a href = "http://opkode.com" target = "_blank" > jcbrand< / a > < / p >
< / footer >
2013-04-26 21:01:39 +02:00
< / div >
< / body >
< / html >
