Chapril/xmpp.chapril.org-conversejs
Chapril/xmpp.chapril.org-conversejs
25
0
Fork 0
Code Issues Pull Requests Projects Releases Activity

Update documentation

Browse Source
This commit is contained in:
JC Brand 2013-07-25 00:09:09 +02:00
parent ded2b23388
commit edc578b8b7
7 changed files with 116 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
docs/doctrees/environment.pickle
View File

Binary file not shown.

BIN
docs/doctrees/index.doctree
View File

Binary file not shown.

50
docs/html/_sources/index.txt
View File

@ -99,6 +99,8 @@ website. This will remove the need for any cross-domain XHR support.
Server-side authentication Server-side authentication
========================== ==========================
.. _`Session Support`:
Pre-binding and Single Session Support Pre-binding and Single Session Support
-------------------------------------- --------------------------------------
@ -110,7 +112,7 @@ Jack Moffitt has a great `blogpost`_ about this and even provides an `example Dj
.. Note:: .. Note::
If you want to enable single session support, make sure to pass **prebind: true** If you want to enable single session support, make sure to pass **prebind: true**
when you call **converse.initialize** (see ./main.js). when you call **converse.initialize** (see ./index.html).
When you authenticate to the XMPP server on your backend, you'll receive two When you authenticate to the XMPP server on your backend, you'll receive two
tokens, RID (request ID) and SID (session ID). tokens, RID (request ID) and SID (session ID).
@ -153,21 +155,36 @@ connection object.
Quickstart (to get a demo up and running) Quickstart (to get a demo up and running)
========================================= =========================================
When you download a specific release of *Converse.js*, say for example version 0.3, When you download a specific release of *Converse.js* there will be two minified files inside the zip file.
there will be two minified files inside the zip file.
For version 0.3 they will be: * converse.min.js
* converse.min.css
* converse.0.3.min.js You can include these two files inside the *<head>* element of your website via the *script* and *link*
* converse.0.3.min.css
You can include these two files in your website via the *script* and *link*
tags: tags:
:: ::
<link rel="stylesheet" type="text/css" media="screen" href="converse.0.3.min.css"> <link rel="stylesheet" type="text/css" media="screen" href="converse.min.css">
<script src="converse.0.3.min.js"></script> <script src="converse.min.js"></script>
Then, at the bottom of your page, after the closing *</body>* element, put the
following inline Javascript code:
::
<script>
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
});
</script>
The *index.html* file inside the Converse.js folder serves as a nice usable The *index.html* file inside the Converse.js folder serves as a nice usable
example of this. example of this.
@ -180,7 +197,7 @@ 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 your website, where users authenticate once in your website and then stay
logged into their XMPP session upon page reload. logged into their XMPP session upon page reload.
For more info on this, read `Session Support`_. For more info on this, read: `Pre-binding and Single Session Support`_.
You might also want to have more fine-grained control of what gets included in You might also want to have more fine-grained control of what gets included in
the minified Javascript file. Read `Configuration`_ and `Minification`_ for more info on how to do the minified Javascript file. Read `Configuration`_ and `Minification`_ for more info on how to do
@ -198,6 +215,9 @@ on your website.
*Converse.js* is passed its configuration settings when you call its *Converse.js* is passed its configuration settings when you call its
*initialize* method. *initialize* method.
You'll most likely want to call the *initialize* method in your HTML page. For
an example of how this is done, please see the bottom of the *./index.html* page.
Please refer to the `Configuration variables`_ section below for info on Please refer to the `Configuration variables`_ section below for info on
all the available configuration settings. all the available configuration settings.
@ -358,6 +378,14 @@ CSS can be minimized with Yahoo's yuicompressor tool:
Translations Translations
============ ============
.. Note ::
Translations take up a lot of space and will bloat your minified file.
At the time of writing, the difference between *converse.min.js* and
*converse.min.no-locales.js* is about 50KB! Therefore, make sure to only
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.
The gettext POT file located in ./locale/converse.pot is the template The gettext POT file located in ./locale/converse.pot is the template
containing all translations and from which for each language an individual PO containing all translations and from which for each language an individual PO
file is generated. file is generated.

50
docs/html/index.html
View File

@ -115,7 +115,7 @@ properly configure and integrate it into your site.</p>
webchat experience and that you have control over the data. The latter being a webchat experience and that you have control over the data. The latter being a
requirement for many sites dealing with sensitive information.</p> requirement for many sites dealing with sensitive information.</p>
<p>You&#8217;ll need to set up your own XMPP server and in order to have <p>You&#8217;ll need to set up your own XMPP server and in order to have
<a href="#id24"><span class="problematic" id="id25">`Session Support`_</span></a> (i.e. single-signon functionality whereby users are authenticated once and stay <a class="reference internal" href="#session-support">Session Support</a> (i.e. single-signon functionality whereby users are authenticated once and stay
logged in to XMPP upon page reload) you will also have to add some server-side logged in to XMPP upon page reload) you will also have to add some server-side
code.</p> 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 <p>The <a class="reference internal" href="#what-you-will-need">What you will need</a> section has more information on all these
@ -128,7 +128,7 @@ requirements.</p>
<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 <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> 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 <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
have <a href="#id26"><span class="problematic" id="id27">`Session Support`_</span></a> you&#8217;ll have to set up your own XMPP server.</p> have <a class="reference internal" href="#session-support">Session Support</a> you&#8217;ll have to set up your own XMPP server.</p>
<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 <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> 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>
@ -168,7 +168,7 @@ website. This will remove the need for any cross-domain XHR support.</p>
<div class="section" id="server-side-authentication"> <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> <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>
<div class="section" id="pre-binding-and-single-session-support"> <div class="section" id="pre-binding-and-single-session-support">
<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> <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>
<p>It&#8217;s possible to enable single-site login, whereby users already <p>It&#8217;s possible to enable single-site login, whereby users already
authenticated in your website will also automatically be logged in on the chat server, authenticated in your website will also automatically be logged in on the chat server,
but this will require custom code on your server.</p> but this will require custom code on your server.</p>
@ -176,7 +176,7 @@ but this will require custom code on your server.</p>
<div class="admonition note"> <div class="admonition note">
<p class="first admonition-title">Note</p> <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> <p class="last">If you want to enable single session support, make sure to pass <strong>prebind: true</strong>
when you call <strong>converse.initialize</strong> (see ./main.js).</p> when you call <strong>converse.initialize</strong> (see ./index.html).</p>
</div> </div>
<p>When you authenticate to the XMPP server on your backend, you&#8217;ll receive two <p>When you authenticate to the XMPP server on your backend, you&#8217;ll receive two
tokens, RID (request ID) and SID (session ID).</p> tokens, RID (request ID) and SID (session ID).</p>
@ -209,17 +209,30 @@ connection object.</p>
</div> </div>
<div class="section" id="quickstart-to-get-a-demo-up-and-running"> <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> <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>
<p>When you download a specific release of <em>Converse.js</em>, say for example version 0.3, <p>When you download a specific release of <em>Converse.js</em> there will be two minified files inside the zip file.</p>
there will be two minified files inside the zip file.</p>
<p>For version 0.3 they will be:</p>
<ul class="simple"> <ul class="simple">
<li>converse.0.3.min.js</li> <li>converse.min.js</li>
<li>converse.0.3.min.css</li> <li>converse.min.css</li>
</ul> </ul>
<p>You can include these two files in your website via the <em>script</em> and <em>link</em> <p>You can include these two files inside the <em>&lt;head&gt;</em> element of your website via the <em>script</em> and <em>link</em>
tags:</p> tags:</p>
<div class="highlight-python"><pre>&lt;link rel="stylesheet" type="text/css" media="screen" href="converse.0.3.min.css"&gt; <div class="highlight-python"><pre>&lt;link rel="stylesheet" type="text/css" media="screen" href="converse.min.css"&gt;
&lt;script src="converse.0.3.min.js"&gt;&lt;/script&gt;</pre> &lt;script src="converse.min.js"&gt;&lt;/script&gt;</pre>
</div>
<p>Then, at the bottom of your page, after the closing <em>&lt;/body&gt;</em> element, put the
following inline Javascript code:</p>
<div class="highlight-python"><pre>&lt;script&gt;
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
});
&lt;/script&gt;</pre>
</div> </div>
<p>The <em>index.html</em> file inside the Converse.js folder serves as a nice usable <p>The <em>index.html</em> file inside the Converse.js folder serves as a nice usable
example of this.</p> example of this.</p>
@ -229,7 +242,7 @@ practical.</p>
<p>You&#8217;ll most likely want to implement some kind of single-signon solution for <p>You&#8217;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 your website, where users authenticate once in your website and then stay
logged into their XMPP session upon page reload.</p> logged into their XMPP session upon page reload.</p>
<p>For more info on this, read <a href="#id28"><span class="problematic" id="id29">`Session Support`_</span></a>.</p> <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>
<p>You might also want to have more fine-grained control of what gets included in <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 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> that.</p>
@ -241,6 +254,8 @@ you&#8217;ll want to configure <em>Converse.js</em> to suit your needs before yo
on your website.</p> on your website.</p>
<p><em>Converse.js</em> is passed its configuration settings when you call its <p><em>Converse.js</em> is passed its configuration settings when you call its
<em>initialize</em> method.</p> <em>initialize</em> method.</p>
<p>You&#8217;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>
<p>Please refer to the <a class="reference internal" href="#configuration-variables">Configuration variables</a> section below for info on <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> all the available configuration settings.</p>
<p>After you have configured <em>Converse.js</em>, you&#8217;ll have to regenerate the minified <p>After you have configured <em>Converse.js</em>, you&#8217;ll have to regenerate the minified
@ -357,6 +372,15 @@ manager, NPM.</p>
</div> </div>
<div class="section" id="translations"> <div class="section" id="translations">
<h1><a class="toc-backref" href="#id23">Translations</a><a class="headerlink" href="#translations" title="Permalink to this headline"></a></h1> <h1><a class="toc-backref" href="#id23">Translations</a><a class="headerlink" href="#translations" title="Permalink to this headline"></a></h1>
<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.
At the time of writing, the difference between <em>converse.min.js</em> and
<em>converse.min.no-locales.js</em> is about 50KB! Therefore, make sure to only
include those languages that you intend to support and remove from
./locale/locales.js those which you don&#8217;t need. Remember to rebuild the
minified file afterwards.</p>
</div>
<p>The gettext POT file located in ./locale/converse.pot is the template <p>The gettext POT file located in ./locale/converse.pot is the template
containing all translations and from which for each language an individual PO containing all translations and from which for each language an individual PO
file is generated.</p> file is generated.</p>

BIN
docs/html/objects.inv
View File

Binary file not shown.

2
docs/html/searchindex.js
View File

@ -1 +1 @@
Search.setIndex({objects:{},terms:{all:0,code:0,partial:0,queri:0,webchat:0,follow:0,middl:0,depend:0,sensit:0,sorri:0,those:0,under:0,string:0,fals:0,mechan:0,jack:0,veri:0,list:0,pleas:0,prevent:0,past:0,second:0,pass:0,download:0,further:0,fullnam:0,click:0,even:0,index:0,what:0,hide:0,section:0,current:0,version:0,"new":0,net:0,"public":0,widget:0,gener:0,here:0,valu:0,box:0,convert:0,convers:0,mysit:0,fetch:0,implement:0,via:0,extra:0,apach:0,ask:0,href:0,org:0,auto_list_room:0,instal:0,from:0,zip:0,commun:0,doubl:0,two:0,websit:0,stylesheet:0,call:0,recommend:0,type:0,until:0,tightli:0,more:0,yahoo:0,must:0,room:0,setup:[],work:0,xhr:0,can:0,lc_messag:0,purpos:0,root:0,blogpost:0,control:0,quickstart:0,share:0,templat:0,tag:0,proprietari:0,explor:0,onlin:0,occup:0,end:0,goal:0,write:0,how:0,sid:0,instead:0,css:0,updat:0,npm:0,regener:0,product:0,resourc:0,after:0,usabl:0,befor:0,callback:0,underscor:0,data:0,demonstr:0,man:0,practic:0,bind:0,show_controlbox_by_default:0,django:0,inform:0,order:0,chatbox:0,xmpp:0,over:0,through:0,streamlin:0,snippet:0,jid:0,directli:0,fit:0,pend:0,hidden:0,therefor:0,might:0,them:0,anim:0,"return":0,thei:0,initi:0,front:0,now:0,introduct:0,name:0,edit:0,authent:0,token:0,ejabberd:0,each:0,side:0,mean:0,domain:0,individu:0,realli:0,legwork:0,connect:0,happen:0,extract:0,special:0,variabl:0,shown:0,open:0,content:0,rel:0,internet:0,plural:0,factori:0,po2json:0,proxi:0,insid:0,standard:0,standalon:0,ajax:0,put:0,succesfulli:0,could:0,success:0,keep:0,yui:0,first:0,origin:0,softwar:0,render:0,onc:0,hoop:0,lastnam:0,number:0,yourself:0,restrict:0,alreadi:0,owner:0,jabber:0,differ:0,script:0,top:0,messag:0,attach:0,attack:0,jed:0,luckili:0,option:0,tool:0,specifi:0,compressor:0,part:0,exactli:0,than:0,serv:0,jump:0,kind:0,provid:0,remov:0,bridg:0,toward:[],browser:0,pre:0,sai:0,saa:0,modern:0,ani:0,packag:0,have:0,tabl:0,need:0,moffitt:0,element:0,bosh_service_url:0,prebind:0,min:0,latter:0,note:0,also:0,contact:0,build:0,which:0,singl:0,sure:0,roster:0,track:0,object:0,most:0,deploi:0,homepag:0,"class":0,don:0,url:0,request:0,face:0,runtim:0,xdomainrequest:0,show:0,german:0,text:0,session:0,fine:0,find:0,onli:0,locat:0,just:0,configur:0,solut:0,should:0,folder:0,local:0,meant:0,get:0,opkod:0,cannot:0,deploy:0,requir:0,enabl:0,emb:0,method:0,reload:0,integr:0,contain:0,where:0,set:0,stroph:0,see:0,close:0,statu:0,state:0,reus:0,between:0,experi:0,hide_muc_serv:0,attribut:0,kei:0,screen:0,javascript:0,conjunct:[],job:0,bosh:0,cor:0,instant:0,shortliv:0,conversej:0,etc:0,grain:0,mani:0,login:0,com:0,load:0,instanti:0,pot:0,backend:0,creat:0,json:0,much:0,besid:0,subscrib:0,msgmerg:0,great:0,minifi:0,togeth:0,i18n:0,present:0,multi:0,main:0,servic:0,plugin:0,defin:0,file:0,helper:0,demo:0,auto_subscrib:0,site:0,rid:0,minim:0,receiv:0,media:0,make:0,minif:0,cross:0,same:0,html:0,chatroom:0,signon:0,http:0,webserv:0,optim:0,upon:0,hand:0,user:0,xhr_user_search:0,recent:0,stateless:0,markup:0,person:[],exampl:0,command:0,wherebi:0,thi:0,choos:0,usual:0,plural_form:0,protocol:0,firstnam:0,languag:0,web:0,xmlhttprequest:0,had:0,add:0,valid:0,input:0,yuicompressor:0,match:0,applic:0,format:0,read:0,nginx:0,traffic:0,xss:0,like:0,specif:0,server:0,benefit:0,necessari:0,either:0,page:0,deal:0,nplural:0,some:0,back:0,librari:0,though:0,overcom:0,refer:0,run:0,host:0,panel:0,src:0,about:0,obj:[],controlbox:0,unfortun:0,act:0,own:0,encod:0,automat:0,wrap:0,your:0,manag:0,log:0,wai:0,transfer:0,support:0,custom:0,avail:0,start:[],includ:0,lot:0,suit:0,"var":0,"function":0,properli:0,form:0,bundl:0,link:0,translat:0,synonym:0,"true":0,congratul:0,requirej:0,info:0,made:0,locale_data:0,possibl:0,"default":0,below:0,toggl:0,otherwis:0,problem:0,expect:0,featur:0,onconnect:0,exist:0,chat:0,want:0,when:0,detail:0,gettext:0,field:0,other:0,test:0,you:0,nice:0,node:0,releas:0,stai:0,lang:0,longer:0,getjson:0},objtypes:{},titles:["Introduction"],objnames:{},filenames:["index"]}) Search.setIndex({objects:{},terms:{all:0,code:0,partial:0,queri:0,webchat:0,follow:0,middl:0,depend:0,sensit:0,sorri:0,specif:0,those:0,under:0,string:0,fals:0,mechan:0,jack:0,veri:0,list:0,pleas:0,prevent:0,past:0,second:0,pass:0,download:0,further:0,fullnam:0,click:0,even:0,index:0,what:0,hide:0,section:0,current:0,version:[],"new":0,net:0,method:0,widget:0,gener:0,here:0,bodi:0,valu:0,box:0,convert:0,convers:0,mysit:0,fetch:0,implement:0,via:0,extra:0,solut:0,put:0,href:0,succesfulli:0,auto_list_room:0,instal:0,from:0,zip:0,commun:0,doubl:0,two:0,websit:0,stylesheet:0,call:0,recommend:0,type:0,until:0,tightli:0,more:0,yahoo:0,must:0,room:0,setup:[],work:0,xhr:0,can:0,lc_messag:0,purpos:0,root:0,blogpost:0,control:0,quickstart:0,share:0,templat:0,tag:0,proprietari:0,explor:0,onlin:0,occup:0,end:0,goal:0,snippet:0,how:0,sid:0,instead:0,css:0,updat:0,npm:0,regener:0,product:0,resourc:0,after:0,usabl:0,befor:0,callback:0,underscor:0,data:0,demonstr:0,man:0,practic:0,bind:0,show_controlbox_by_default:0,element:0,inform:0,order:0,chatbox:0,xmpp:0,over:0,through:0,streamlin:0,write:0,jid:0,directli:0,fit:0,pend:0,hidden:0,therefor:0,might:0,them:0,anim:0,"return":0,thei:0,initi:0,front:0,now:0,introduct:0,name:0,edit:0,authent:0,token:0,ejabberd:0,each:0,side:0,mean:0,domain:0,individu:0,realli:0,legwork:0,connect:0,happen:0,extract:0,special:0,variabl:0,shown:0,space:0,open:0,content:0,rel:0,internet:0,plural:0,factori:0,po2json:0,proxi:0,insid:0,standard:0,standalon:0,ajax:0,ask:0,org:0,afterward:0,could:0,keep:0,yui:0,first:0,origin:0,softwar:0,render:0,onc:0,hoop:0,lastnam:0,number:0,yourself:0,restrict:0,alreadi:0,done:0,owner:0,jabber:0,differ:0,script:0,top:0,messag:0,attach:0,attack:0,jed:0,luckili:0,option:0,tool:0,specifi:0,compressor:0,part:0,exactli:0,than:0,serv:0,jump:0,kind:0,bloat:0,provid:0,remov:0,reus:0,toward:[],browser:0,pre:0,sai:[],saa:0,modern:0,ani:0,packag:0,have:0,tabl:0,need:0,moffitt:0,django:0,bosh_service_url:0,prebind:0,min:0,latter:0,note:0,also:0,exampl:0,build:0,which:0,singl:0,sure:0,roster:0,track:0,object:0,most:0,deploi:0,homepag:0,"class":0,don:0,url:0,request:0,face:0,runtim:0,xdomainrequest:0,show:0,german:0,text:0,session:0,fine:0,find:0,onli:0,locat:0,firstnam:0,configur:0,apach:0,should:0,folder:0,local:0,meant:0,get:0,opkod:0,cannot:0,deploy:0,requir:0,enabl:0,emb:0,"public":0,reload:0,integr:0,contain:0,where:0,set:0,stroph:0,see:0,close:0,statu:0,state:0,bridg:0,between:0,experi:0,hide_muc_serv:0,attribut:0,kei:0,screen:0,javascript:0,conjunct:[],job:0,bosh:0,cor:0,instant:0,shortliv:0,conversej:0,etc:0,grain:0,mani:0,login:0,com:0,load:0,instanti:0,pot:0,backend:0,onconnect:0,rebuild:0,json:0,much:0,besid:0,subscrib:0,msgmerg:0,great:0,minifi:0,togeth:0,i18n:0,present:0,multi:0,main:0,servic:0,plugin:0,defin:0,chat:0,helper:0,demo:0,auto_subscrib:0,site:0,rid:0,minim:0,receiv:0,media:0,make:0,minif:0,cross:0,same:0,html:0,chatroom:0,signon:0,http:0,webserv:0,optim:0,upon:0,hand:0,"50kb":0,user:0,xhr_user_search:0,recent:0,stateless:0,markup:0,person:[],contact:0,command:0,wherebi:0,thi:0,choos:0,usual:0,plural_form:0,protocol:0,just:0,languag:0,web:0,xmlhttprequest:0,had:0,add:0,other:0,input:0,yuicompressor:0,match:0,take:0,applic:0,format:0,read:0,nginx:0,traffic:0,xss:0,like:0,success:0,server:0,benefit:0,necessari:0,either:0,page:0,deal:0,nplural:0,some:0,back:0,librari:0,bottom:0,though:0,overcom:0,refer:0,run:0,host:0,panel:0,src:0,about:0,obj:[],controlbox:0,unfortun:0,act:0,own:0,encod:0,automat:0,wrap:0,your:0,manag:0,log:0,wai:0,transfer:0,support:0,custom:0,avail:0,start:[],includ:0,lot:0,suit:0,"var":0,"function":0,head:0,properli:0,form:0,bundl:0,link:0,translat:0,synonym:0,inlin:0,"true":0,congratul:0,longer:0,info:0,made:0,locale_data:0,possibl:0,"default":0,below:0,toggl:0,otherwis:0,problem:0,expect:0,featur:0,creat:0,"100kb":[],exist:0,file:0,want:0,when:0,detail:0,gettext:0,field:0,valid:0,rememb:0,test:0,you:0,nice:0,node:0,intend:0,releas:0,stai:0,lang:0,requirej:0,getjson:0,time:0},objtypes:{},titles:["Introduction"],objnames:{},filenames:["index"]})

50
docs/source/index.rst
View File

@ -99,6 +99,8 @@ website. This will remove the need for any cross-domain XHR support.
Server-side authentication Server-side authentication
========================== ==========================
.. _`Session Support`:
Pre-binding and Single Session Support Pre-binding and Single Session Support
-------------------------------------- --------------------------------------
@ -110,7 +112,7 @@ Jack Moffitt has a great `blogpost`_ about this and even provides an `example Dj
.. Note:: .. Note::
If you want to enable single session support, make sure to pass **prebind: true** If you want to enable single session support, make sure to pass **prebind: true**
when you call **converse.initialize** (see ./main.js). when you call **converse.initialize** (see ./index.html).
When you authenticate to the XMPP server on your backend, you'll receive two When you authenticate to the XMPP server on your backend, you'll receive two
tokens, RID (request ID) and SID (session ID). tokens, RID (request ID) and SID (session ID).
@ -153,21 +155,36 @@ connection object.
Quickstart (to get a demo up and running) Quickstart (to get a demo up and running)
========================================= =========================================
When you download a specific release of *Converse.js*, say for example version 0.3, When you download a specific release of *Converse.js* there will be two minified files inside the zip file.
there will be two minified files inside the zip file.
For version 0.3 they will be: * converse.min.js
* converse.min.css
* converse.0.3.min.js You can include these two files inside the *<head>* element of your website via the *script* and *link*
* converse.0.3.min.css
You can include these two files in your website via the *script* and *link*
tags: tags:
:: ::
<link rel="stylesheet" type="text/css" media="screen" href="converse.0.3.min.css"> <link rel="stylesheet" type="text/css" media="screen" href="converse.min.css">
<script src="converse.0.3.min.js"></script> <script src="converse.min.js"></script>
Then, at the bottom of your page, after the closing *</body>* element, put the
following inline Javascript code:
::
<script>
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
});
</script>
The *index.html* file inside the Converse.js folder serves as a nice usable The *index.html* file inside the Converse.js folder serves as a nice usable
example of this. example of this.
@ -180,7 +197,7 @@ 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 your website, where users authenticate once in your website and then stay
logged into their XMPP session upon page reload. logged into their XMPP session upon page reload.
For more info on this, read `Session Support`_. For more info on this, read: `Pre-binding and Single Session Support`_.
You might also want to have more fine-grained control of what gets included in You might also want to have more fine-grained control of what gets included in
the minified Javascript file. Read `Configuration`_ and `Minification`_ for more info on how to do the minified Javascript file. Read `Configuration`_ and `Minification`_ for more info on how to do
@ -198,6 +215,9 @@ on your website.
*Converse.js* is passed its configuration settings when you call its *Converse.js* is passed its configuration settings when you call its
*initialize* method. *initialize* method.
You'll most likely want to call the *initialize* method in your HTML page. For
an example of how this is done, please see the bottom of the *./index.html* page.
Please refer to the `Configuration variables`_ section below for info on Please refer to the `Configuration variables`_ section below for info on
all the available configuration settings. all the available configuration settings.
@ -358,6 +378,14 @@ CSS can be minimized with Yahoo's yuicompressor tool:
Translations Translations
============ ============
.. Note ::
Translations take up a lot of space and will bloat your minified file.
At the time of writing, the difference between *converse.min.js* and
*converse.min.no-locales.js* is about 50KB! Therefore, make sure to only
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.
The gettext POT file located in ./locale/converse.pot is the template The gettext POT file located in ./locale/converse.pot is the template
containing all translations and from which for each language an individual PO containing all translations and from which for each language an individual PO
file is generated. file is generated.