diff --git a/docs/doctrees/index.doctree b/docs/doctrees/index.doctree index b6df0c562..bd1990e06 100644 Binary files a/docs/doctrees/index.doctree and b/docs/doctrees/index.doctree differ diff --git a/docs/html/_sources/index.txt b/docs/html/_sources/index.txt index 422756ba4..b91f13b54 100644 --- a/docs/html/_sources/index.txt +++ b/docs/html/_sources/index.txt @@ -721,8 +721,8 @@ Converse.js emits events to which you can subscribe from your own Javascript. Concerning events, the following methods are available: -Event Methods -============= +Event API Methods +================= * **on(eventName, callback)**: @@ -808,6 +808,95 @@ Here are the different events that are emitted: | **buddyStatusMessageChanged** | When a chat buddy's custom status message has changed. | ``converse.on('buddyStatusMessageChanged', function (buddy, messageText) { ... });`` | +----------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ +============= +Developer API +============= + +.. Note :: See also the `Event API Methods`_, not listed here. + +initialize +========== + +Initializes converse.js. This method must always be called when using +converse.js. + +The `initialize` method takes a map (also called a hash or dictionary) of +`configuration variables`_. + +Example:: + + converse.initialize({ + allow_otr: true, + auto_list_rooms: false, + auto_subscribe: false, + bosh_service_url: 'https://bind.example.com', + hide_muc_server: false, + i18n: locales['en'], + keepalive: true, + play_sounds: true, + prebind: false, + show_controlbox_by_default: true, + debug: false, + roster_groups: true + }); + + +getBuddy +======== + +Returns a map of attributes for a given buddy (i.e. roster contact), specified +by JID (Jabber ID). + +Example:: + + converse.getBuddy('buddy@example.com') + +The map of attributes: + ++----------------+--------------------------------------------------------------------------------------------------------------------------------------+ +| Attribute | | ++================+======================================================================================================================================+ +| ask | If ask === 'subscribe', then we have asked this person to be our chat buddy. | ++----------------+--------------------------------------------------------------------------------------------------------------------------------------+ +| fullname | The person's full name. | ++----------------+--------------------------------------------------------------------------------------------------------------------------------------+ +| jid | The person's Jabber/XMPP username. | ++----------------+--------------------------------------------------------------------------------------------------------------------------------------+ +| requesting | If true, then this person is asking to be our chat buddy. | ++----------------+--------------------------------------------------------------------------------------------------------------------------------------+ +| subscription | The subscription state between the current user and this chat buddy. Can be `none`, `to`, `from` or `both`. | ++----------------+--------------------------------------------------------------------------------------------------------------------------------------+ +| id | A unique id, same as the jid. | ++----------------+--------------------------------------------------------------------------------------------------------------------------------------+ +| chat_status | The person's chat status. Can be `online`, `offline`, `busy`, `xa` (extended away) or `away`. | ++----------------+--------------------------------------------------------------------------------------------------------------------------------------+ +| user_id | The user id part of the JID (the part before the `@`). | ++----------------+--------------------------------------------------------------------------------------------------------------------------------------+ +| resources | The known resources for this chat buddy. Each resource denotes a separate and connected chat client. | ++----------------+--------------------------------------------------------------------------------------------------------------------------------------+ +| groups | The roster groups in which this chat buddy was placed. | ++----------------+--------------------------------------------------------------------------------------------------------------------------------------+ +| status | Their human readable custom status message. | ++----------------+--------------------------------------------------------------------------------------------------------------------------------------+ +| image_type | The image's file type. | ++----------------+--------------------------------------------------------------------------------------------------------------------------------------+ +| image | The Base64 encoded image data. | ++----------------+--------------------------------------------------------------------------------------------------------------------------------------+ +| url | The buddy's website URL, as specified in their VCard data. | ++----------------+--------------------------------------------------------------------------------------------------------------------------------------+ +| vcard_updated | When last the buddy's VCard was updated. | ++----------------+--------------------------------------------------------------------------------------------------------------------------------------+ + +getRID +====== + +Returns the current RID (request ID) value. + +getSID +====== + +Returns the current SID (Session ID) value. + ============= Configuration ============= @@ -829,6 +918,9 @@ After you have configured *Converse.js*, you'll have to regenerate the minified JS file so that it will include the new settings. Please refer to the `Minification`_ section for more info on how to do this. + + + Configuration variables ======================= diff --git a/docs/html/index.html b/docs/html/index.html index bee5fff17..fedd58da9 100644 --- a/docs/html/index.html +++ b/docs/html/index.html @@ -108,42 +108,49 @@
Converse.js emits events to which you can subscribe from your own Javascript.
Concerning events, the following methods are available:
-on(eventName, callback):
@@ -881,8 +888,115 @@ exactly once.
Note
+See also the Event API Methods, not listed here.
+Initializes converse.js. This method must always be called when using +converse.js.
+The initialize method takes a map (also called a hash or dictionary) of +configuration variables.
+Example:
+converse.initialize({
+ allow_otr: true,
+ auto_list_rooms: false,
+ auto_subscribe: false,
+ bosh_service_url: 'https://bind.example.com',
+ hide_muc_server: false,
+ i18n: locales['en'],
+ keepalive: true,
+ play_sounds: true,
+ prebind: false,
+ show_controlbox_by_default: true,
+ debug: false,
+ roster_groups: true
+ });
+
Returns a map of attributes for a given buddy (i.e. roster contact), specified +by JID (Jabber ID).
+Example:
+converse.getBuddy('buddy@example.com')
+
The map of attributes:
+Attribute | ++ |
---|---|
ask | +If ask === ‘subscribe’, then we have asked this person to be our chat buddy. | +
fullname | +The person’s full name. | +
jid | +The person’s Jabber/XMPP username. | +
requesting | +If true, then this person is asking to be our chat buddy. | +
subscription | +The subscription state between the current user and this chat buddy. Can be none, to, from or both. | +
id | +A unique id, same as the jid. | +
chat_status | +The person’s chat status. Can be online, offline, busy, xa (extended away) or away. | +
user_id | +The user id part of the JID (the part before the @). | +
resources | +The known resources for this chat buddy. Each resource denotes a separate and connected chat client. | +
groups | +The roster groups in which this chat buddy was placed. | +
status | +Their human readable custom status message. | +
image_type | +The image’s file type. | +
image | +The Base64 encoded image data. | +
url | +The buddy’s website URL, as specified in their VCard data. | +
vcard_updated | +When last the buddy’s VCard was updated. | +
The included minified JS and CSS files can be used for demoing or testing, but you’ll want to configure Converse.js to suit your needs before you deploy it on your website.
@@ -896,9 +1010,9 @@ all the available configuration settings. JS file so that it will include the new settings. Please refer to the Minification section for more info on how to do this.Default: true
Allow users to add one another as contacts. If this is set to false, the Add a contact widget, Contact Requests and Pending Contacts roster @@ -906,23 +1020,23 @@ sections will all not appear. Additionally, all incoming contact requests will b ignored.
Default: true
Allow multi-user chat (muc) in chatrooms. Setting this to false will remove the Chatrooms tab from the control box.
Default: false
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.
@@ -932,24 +1046,24 @@ features, number of occupants etc.), so on servers with many rooms this option will create lots of extra connection traffic.Default: true
Automatically reconnect to the XMPP server if the connection drops unexpectedly.
Default: false
If true, the user will automatically subscribe back to any contact requests.
Connections to an XMPP server depend on a BOSH connection manager which acts as a middle man between HTTP and XMPP.
See here for more information.
Default: false
Let the OTR (Off-the-record encryption) private key be cached in your browser’s session storage.
@@ -968,12 +1082,12 @@ current session. Previous sessions however cannot be decrypted.Default: false
If set to true, debugging output will be logged to the browser console.
Default: true
Determines whether Converse.js will maintain the chat session across page loads.
@@ -981,7 +1095,7 @@ loads. unhandled edge-cases.Default: false
Support for XEP-0280: Message Carbons
In order to keep all IM clients for a user engaged in a conversation, @@ -992,11 +1106,11 @@ tab serves as a separate IM client.
(showing sent messages in all connected chat clients aka resources), but go about it in two different ways.Message carbons is the XEP (Jabber protocol extension) specifically drafted to -solve this problem, while `forwarded_messages`_ uses +solve this problem, while `forwarded_messages`_ uses stanza forwarding
Default: false
Allow the prebind tokens, RID (request ID) and SID (session ID), to be exposed globally via the API. This allows other scripts served on the same page to use @@ -1005,7 +1119,7 @@ these values.
and inject fake chat messages.Default: false
If set to true, sent messages will also be forwarded to the sending user’s bare JID (their Jabber ID independent of any chat clients aka resources).
@@ -1014,27 +1128,27 @@ and not just the one from which it was actually sent.This is especially important for web chat, such as converse.js, where each browser tab functions as a separate chat client, with its own resource.
This feature uses Stanza forwarding, see also XEP 0297: Stanza Forwarding
-For an alternative approach, see also `message carbons`_.
+For an alternative approach, see also `message carbons`_.
If you are using prebinding, can specify the fullname of the currently logged in user, otherwise the user’s vCard will be fetched.
Default: false
Hide the server input field of the form inside the Room panel of the controlbox. Useful if you want to restrict users to a specific XMPP server of your choosing.
Specify the locale/language. The language must be in the locales object. Refer to ./locale/locales.js to see which locales are supported.
Default: false
Plays a notification sound when you receive a personal message or when your nickname is mentioned in a chat room.
@@ -1047,7 +1161,7 @@ it in both formats as http://yourhttp://yoursite.com should of course be your site’s URL.
Default: false
Use this option when you want to attach to an existing XMPP connection that was already authenticated (usually on the backend before page load).
@@ -1060,7 +1174,7 @@ values as jid, Additionally, you have to specify bosh_service_url.Default: false
If set to true, converse.js will show any roster groups you might have configured.
@@ -1072,7 +1186,7 @@ elsewhere.Default: false
The “controlbox” refers to the special chatbox containing your contacts roster, status widget, chatrooms and other controls.
@@ -1082,13 +1196,13 @@ the page with class toggle-controlbox. page load.Default: false
If set to true, only online users will be shown in the contacts roster. Users with any other status (e.g. away, busy etc.) will not be shown.
Default: session
Valid options: session, local.
This option determines the type of storage @@ -1111,20 +1225,20 @@ only across more than one session.
Default: false
If set to true, Converse.js will automatically try to initiate an OTR (off-the-record) encrypted chat session every time you open a chat box.
Default: true
Determines whether the XMPP server will be queried for roster contacts’ VCards or not. VCards contain extra personal information such as your fullname and avatar image.
Default:
{
call: false,
@@ -1171,7 +1285,7 @@ When the call button is pressed, it will emit an event that can be used by a thi
Default: false
Note
@@ -1181,7 +1295,7 @@ When the call button is pressed, it will emit an event that can be used by a thi remote server.Note
XHR stands for XMLHTTPRequest, and is meant here in the AJAX sense (Asynchronous Javascript and XML).
@@ -1193,7 +1307,7 @@ message will be made.The message itself is sent in the request under the key msg.
Default: false
Note
@@ -1210,7 +1324,7 @@ message will be made. corresponds to a matched user and needs the keys id and fullname.Note
XHR stands for XMLHTTPRequest, and is meant here in the AJAX sense (Asynchronous Javascript and XML).
diff --git a/docs/html/searchindex.js b/docs/html/searchindex.js index 4b9aa597c..bb8463383 100644 --- a/docs/html/searchindex.js +++ b/docs/html/searchindex.js @@ -1 +1 @@ -Search.setIndex({envversion:42,terms:{"default":0,all:0,partial:0,edg:0,queri:0,lack:0,webchat:0,mp3:0,abil:0,follow:0,row:0,privat:0,middl:0,sensit:0,punjab:0,elsewher:0,send:0,vcard:0,buddi:0,under:0,sens:0,spec:0,sent:0,global:0,everi:0,string:0,fals:0,could:0,voic:0,ident:0,mechan:0,jack:0,veri:0,word:0,tri:[],button:0,messagetext:0,list:0,correct:0,"try":0,item:0,sane:[],increment:0,refer:0,pleas:0,prevent:0,almond:0,prosodi:0,focu:0,past:0,second:0,download:0,further:0,port:0,folk:0,even:0,index:0,hide:0,appear:0,section:0,abl:0,access:0,delet:0,version:0,"new":0,net:0,"public":0,jqueri:0,widget:0,themselv:[],messagexml:0,join:0,gener:0,here:0,bodi:0,typeerror:0,let:0,path:0,becom:0,modifi:[],sinc:0,valu:0,box:0,great:0,convers:0,mysit:0,current:0,ajax:0,implement:0,sorri:0,chanc:0,via:0,repositori:0,danger:0,primit:0,prefer:0,put:0,href:0,fake:0,sessionstorag:0,establish:0,from:0,zip:0,commun:0,deop:0,doubl:0,two:0,websit:0,few:[],stylesheet:0,busi:0,call:0,msg:0,until:0,tightli:0,more:0,emoticon:0,peopl:[],notic:0,site:0,particular:0,cach:0,must:0,account:[],retriev:0,room:[],work:0,uniqu:0,dev:0,xhr:0,legwork:0,can:0,lc_messag:0,purpos:0,root:0,fetch:0,control:0,getsess:[],give:0,challeng:0,share:0,templat:0,topic:0,critic:0,proprietari:0,explor:0,onlin:0,callbuttonclick:0,occup:0,cours:0,multipl:0,goal:0,turn:0,anoth:0,deniabl:0,write:0,how:0,bosh_serv:[],sid:0,instead:0,perspect:0,updat:0,npm:0,regener:0,product:0,resourc:0,after:0,usabl:0,mai:0,underscor:0,data:0,demonstr:0,man:0,opkod:[],"short":0,attempt:0,practic:0,third:0,seriou:0,secur:0,credenti:0,correspond:0,assign:0,caus:0,inform:0,maintain:0,allow:0,media:0,order:0,talk:0,feedback:[],chatbox:0,chatroomopen:0,over:0,move:0,becaus:0,chatboxopen:0,own:0,through:0,reconnect:0,still:0,paramet:0,streamlin:0,jid:0,"8147a27e4a7f9b55ffc85c2683f9529a":[],render:0,fit:0,fix:0,better:0,window:0,pend:0,persist:0,hidden:0,main:0,might:0,them:0,lastnam:0,"return":0,thei:0,python:0,encod:0,initi:0,rewriterul:0,mention:0,verifi:0,now:0,jump:0,name:0,edit:0,drop:0,crypto:0,separ:0,achiev:0,ejabberd:0,each:0,mean:0,subset:0,everyth:0,harm:0,chatboxfocus:0,michael:0,individu:0,idea:0,realli:0,"static":0,expect:0,our:0,happen:0,extract:0,special:0,out:0,shown:0,"3rd":0,space:0,miss:0,proxy_pass:0,rel:0,internet:0,got:0,plural:0,factori:0,po2json:0,proxi:0,insid:0,written:0,standard:0,standalon:0,reason:0,element:0,ask:0,succesfulli:0,afterward:0,roominvites:0,fairli:0,blogpost:0,keep:0,thing:[],perhap:0,howev:0,nicknam:0,imposs:0,first:0,origin:0,softwar:0,directli:0,malici:0,onc:0,hoop:0,independ:0,cryptograph:0,number:0,yourself:0,instruct:0,alreadi:0,done:0,owner:0,happi:0,open:0,suffic:0,size:0,differ:0,convent:0,top:0,attack:0,messag:0,cssmin:0,attach:0,stori:0,draft:0,jed:0,privaci:0,recent:0,store:0,listen:0,luckili:0,consol:0,option:0,especi:0,tool:0,copi:0,specifi:0,direct:0,maxim:0,part:0,pars:0,kept:0,ogg:0,exactli:0,than:0,serv:0,wide:[],kind:0,bloat:0,provid:0,remov:0,project:0,bridg:0,bind:0,someothersit:0,browser:0,pre:0,"function":0,sai:0,saa:0,session_kei:[],ani:0,packag:0,properli:0,have:0,moffitt:0,django:0,issu:0,outbound:0,callback:0,latter:0,thorough:[],click:0,note:[],also:0,client:0,take:0,which:0,sure:0,roster:0,unsur:0,previou:0,reach:0,most:0,plai:0,plugin:0,eavesdropp:0,homepag:0,"class":0,don:0,url:0,clear:0,doe:[],runtim:0,statuschang:0,bower:0,usual:0,xdomainrequest:0,devdepend:0,show:0,german:0,text:0,buddystatuschang:0,server_nam:0,protocol:0,longer:0,fine:0,find:0,help:0,xml:0,yoursit:0,onli:0,grunt:0,locat:0,just:0,mute:0,releas:0,stanza:0,haven:[],experiment:0,roominvitereceiv:0,folder:0,local:0,meant:0,stop:0,soon:0,repo:0,nativ:0,cannot:0,cryptographi:0,increas:0,awai:0,enabl:0,emb:0,jasmin:0,mainspec:0,possibl:0,patch:[],remot:0,deploy:0,though:0,contain:0,ban:0,where:0,wiki:[],chatboxclos:0,stroph:0,see:0,bare:0,result:0,close:0,calendar:0,eventnam:0,best:0,concern:0,awar:0,statu:0,said:[],extend:0,inconveni:0,someth:0,particip:0,state:0,muc:0,between:0,"import":0,neither:0,experi:0,approach:0,across:0,attribut:0,altern:0,perfect:0,appreci:[],kei:0,screen:0,were:0,conjunct:0,extens:0,job:0,entir:0,"5e64a30272af065bd72258c565a03f2f":[],group:0,both:0,cor:0,instant:0,shortliv:0,conversej:0,myself:[],etc:0,instanc:0,grain:0,mani:0,login:0,com:0,load:0,simpli:0,within:0,pot:0,sync:0,solv:0,carbon:0,assum:0,malleabl:0,backend:0,quit:[],sucessfulli:0,addition:0,rebuild:0,due:0,been:0,compon:0,json:0,much:0,toolbar:0,interest:0,subscrib:0,modern:0,fire:0,imag:0,xxx:0,rubi:0,convert:0,togeth:0,els:0,otr:0,plausibl:0,present:0,"case":0,multi:0,therefor:0,look:0,gnu:0,servic:0,invit:0,messagesend:0,defin:0,"while":0,match:0,abov:[],observ:0,hightlight:0,engag:0,helper:0,readi:0,non:0,itself:0,incom:0,rid:0,pat:0,harsh:0,minim:0,receiv:0,parti:0,make:0,secreci:0,same:0,read:0,onconnectfacebook:[],html:0,unexpectedli:0,chatroom:0,document:[],medit:[],complet:0,status:0,signon:0,http:0,webserv:0,optim:0,roomview:0,upon:0,someon:[],hand:0,unhandl:0,"50kb":0,user:0,roominvit:0,uncaught:0,php:0,aka:0,forwarded_messag:0,weibel:0,stateless:0,moder:0,bewar:0,firstli:0,markup:0,min:0,well:0,object:0,thought:0,person:0,contact:0,command:[],wherebi:0,thi:0,choos:0,model:0,latest:0,plural_form:0,identifi:0,execut:0,tip:[],xep:0,languag:0,previous:0,web:0,xmlhttprequest:0,expos:0,field:0,extra:0,had:0,desktop:0,chat:[],non_amd:0,versa:0,appli:0,input:0,kick:0,build:0,applic:0,format:0,webpag:0,traffic:0,know:0,press:0,xss:0,like:0,specif:0,should:0,manual:0,benefit:0,api:0,either:0,choic:0,popular:0,output:0,page:0,candi:0,facebookconnect:[],revers:0,chatboxtoggl:0,deal:0,visibl:0,some:0,substitu:0,openfir:0,bottom:0,avoid:0,normal:0,rewriteengin:0,track:0,allow_otr:0,inject:0,speak:0,localhost:[],avatar:0,somehow:0,plu:0,who:[],msg_receiv:0,host:0,toggl:0,although:0,post:0,panel:0,src:0,about:0,actual:0,invitee_jid:0,firstnam:0,controlbox:0,unfortun:0,stand:0,act:0,telephon:0,curiou:0,deploi:0,toggle_particip:0,automat:0,right:0,empti:0,wrap:0,chang:0,merg:[],git:0,log:0,wai:0,pictur:0,aren:0,transfer:0,"long":0,custom:0,avail:0,trigger:0,localstorag:0,includ:0,lot:0,suit:0,forward:0,analysi:0,head:0,nplural:0,form:0,bundl:0,back:0,link:0,buddystatusmessagechang:0,synonym:0,line:0,inlin:0,"true":0,bug:0,congratul:0,requirej:0,info:0,made:0,dirti:[],locale_data:0,reload:0,whether:0,tab:0,asynchron:0,below:0,those:0,indefinit:0,otherwis:0,emit:0,significantli:0,constant:0,creat:0,movim:[],decrypt:0,doesn:0,mode:0,msgmerg:0,exist:0,file:0,face:0,probabl:0,again:0,want:0,when:0,detail:0,gettext:0,statusmessagechang:0,nick:0,valid:0,rememb:0,varieti:[],servernam:0,nice:0,node:0,intend:0,determin:0,duck:0,org:0,consid:0,stai:0,lang:0,fraught:0,vice:0,directori:0,virtualhost:0,getjson:0,rule:0,ignor:0,token:0,potenti:0,time:0},objtypes:{},objnames:{},filenames:["index"],titles:["Quickstart (to get a demo up and running)"],objects:{},titleterms:{roster_group:0,multilingu:0,code:0,xmpp:0,session:0,jshint:0,depend:0,configur:0,apach:0,add:0,anim:0,get:0,end:0,amd:0,nginx:0,facebook:[],front:0,requir:0,introduct:0,troubleshoot:0,authent:0,server:0,play_sound:0,xhr_custom_statu:0,integr:[],debug:0,manag:0,domain:0,set:[],habit:0,xhr_user_search_url:0,request:0,connect:0,pass:0,fullnam:0,event:0,librari:0,variabl:0,allow_muc:0,what:0,jabber:0,bad:0,content:0,use_otr_by_default:0,overcom:0,method:0,run:0,hide_muc_serv:0,javascript:0,visible_toolbar_button:0,bosh:0,css:0,xhr_custom_status_url:0,cache_otr_kei:0,side:0,solut:0,restrict:0,auto_list_room:0,instal:0,storag:0,your:0,script:0,support:0,submit:0,recommend:0,type:0,notif:0,minifi:0,translat:0,i18n:0,sound:0,pull:0,room:0,bugfix:0,record:0,error:0,auto_reconnect:0,problem:0,featur:0,quickstart:0,forward_messag:0,demo:0,auto_subscrib:0,tag:0,chat:0,tabl:0,need:0,check:0,bosh_service_url:0,prebind:0,develop:0,message_carbon:0,minif:0,cross:0,other:0,test:0,expose_rid_and_sid:0,you:0,singl:0,keepal:0,befor:0,allow_contact_request:0,encrypt:0,xhr_user_search:0,off:0,use_vcard:0,show_controlbox_by_default:0,without:0,show_only_online_us:0,exampl:0,command:0,conflict:0}}) \ No newline at end of file +Search.setIndex({envversion:42,terms:{all:0,partial:0,edg:0,queri:0,lack:0,webchat:0,mp3:0,abil:0,follow:0,either:0,row:0,privat:0,typeerror:0,sensit:0,punjab:0,base64:0,readabl:0,send:0,vcard:0,buddi:0,under:0,sens:0,spec:0,sent:0,file:0,global:0,everi:0,string:0,fals:0,voic:0,offlin:0,mechan:0,jack:0,veri:0,join:0,tri:[],button:0,messagetext:0,list:0,virtualhost:0,correct:0,"try":0,item:0,sane:[],subscript:0,pleas:0,prevent:0,almond:0,prosodi:0,focu:0,past:0,second:0,download:0,further:0,port:0,folk:0,even:0,index:0,hide:0,appear:0,section:0,abl:0,current:0,delet:0,version:0,"new":0,net:0,"public":0,widget:0,full:0,themselv:[],messagexml:0,gener:0,here:0,bodi:0,middl:0,let:0,path:0,becom:0,modifi:[],sinc:0,valu:0,box:0,great:0,convers:0,mysit:0,reason:0,fetch:0,implement:0,sorri:0,chanc:0,via:0,retriev:0,although:0,danger:0,primit:0,prefer:0,ask:0,href:0,fake:0,sessionstorag:0,establish:0,from:0,zip:0,commun:0,deop:0,doubl:0,two:0,websit:0,few:[],stylesheet:0,call:0,msg:0,until:0,tightli:0,more:0,emoticon:0,peopl:[],line:0,notic:0,particular:0,known:0,cach:0,must:0,none:0,word:0,room:[],work:0,uniqu:0,dev:0,xhr:0,can:0,lc_messag:0,purpos:0,root:0,blogpost:0,control:0,getsess:[],give:0,challeng:0,share:0,templat:0,topic:0,critic:0,proprietari:0,explor:0,onlin:0,callbuttonclick:0,occup:0,alwai:0,cours:0,multipl:0,goal:0,turn:0,anoth:0,deniabl:0,write:0,how:0,bosh_serv:[],sid:0,roster:0,verifi:0,perspect:0,updat:0,npm:0,map:0,product:0,resourc:0,after:0,usabl:0,mai:0,underscor:0,data:0,demonstr:0,man:0,repo:0,"short":0,attempt:0,practic:0,third:0,bind:0,secur:0,credenti:0,correspond:0,django:0,caus:0,inform:0,maintain:0,allow:0,parti:0,order:0,talk:0,feedback:[],chatbox:0,chatroomopen:0,over:0,move:0,becaus:0,chatboxopen:0,telephon:0,through:0,reconnect:0,still:0,paramet:[],streamlin:0,jid:0,"8147a27e4a7f9b55ffc85c2683f9529a":[],render:0,fit:0,fix:0,better:0,whether:0,window:0,pend:0,persist:0,hidden:0,main:0,might:0,them:0,lastnam:0,"return":0,thei:0,python:0,toggle_particip:0,initi:[],rewriterul:0,mention:0,instead:0,aka:0,now:0,jump:0,name:0,edit:0,drop:0,crypto:0,separ:0,achiev:0,ejabberd:0,each:0,mean:0,subset:0,harm:0,chatboxfocus:0,regener:0,experiment:0,michael:0,individu:0,idea:0,realli:0,"static":0,expect:0,our:0,happen:0,extract:0,special:0,out:0,shown:0,"3rd":0,space:0,open:0,proxy_pass:0,rel:0,internet:0,got:0,plural:0,factori:0,po2json:0,model:0,proxi:0,insid:0,state:0,given:0,standard:0,standalon:0,ajax:0,dictionari:0,put:0,succesfulli:0,afterward:0,roominvites:0,unhandl:0,could:0,keep:0,thing:[],perhap:0,place:0,nicknam:0,imposs:0,first:0,origin:0,softwar:0,directli:0,malici:0,onc:0,hoop:0,independ:0,number:0,yourself:0,instruct:0,alreadi:0,done:0,owner:0,custom:0,miss:0,suffic:0,size:0,differ:0,convent:0,top:0,attack:0,messag:0,attach:0,stori:0,draft:0,jed:0,privaci:0,forwarded_messag:0,store:0,listen:0,luckili:0,assign:0,consol:0,option:0,especi:0,tool:0,copi:0,specifi:0,direct:0,maxim:0,part:0,pars:0,moder:0,ogg:0,exactli:0,than:0,serv:0,wide:[],kind:0,bloat:0,provid:0,remov:0,jqueri:0,bridg:0,seriou:0,someothersit:0,browser:0,pre:0,analysi:0,sai:0,saa:0,session_kei:[],ani:0,packag:0,properli:0,increment:0,moffitt:0,element:0,issu:0,outbound:0,callback:0,latter:0,yoursit:0,thorough:[],click:0,note:[],also:0,contact:0,take:0,which:0,therefor:0,sure:0,normal:0,unsur:0,previou:0,reach:0,most:0,plai:0,eavesdropp:0,homepag:0,"class":0,don:0,url:0,clear:0,doe:[],runtim:0,statuschang:0,bower:0,latest:0,xdomainrequest:0,devdepend:0,show:0,german:0,text:0,buddystatuschang:0,server_nam:0,identifi:0,fine:0,find:0,help:0,xml:0,access:0,onli:0,grunt:0,locat:0,execut:0,mute:0,releas:0,stanza:0,chat_statu:0,haven:[],busi:0,roominvitereceiv:0,folder:0,local:0,meant:0,stop:0,account:[],soon:0,opkod:[],nativ:0,cannot:0,cryptographi:0,increas:0,neither:0,enabl:0,emb:0,approach:0,mainspec:0,multi:0,patch:[],remot:0,though:0,contain:0,ban:0,where:0,wiki:[],chatboxclos:0,stroph:0,see:0,bare:0,result:0,close:0,calendar:0,eventnam:0,best:0,concern:0,awar:0,statu:0,said:[],kei:0,inconveni:0,someth:0,particip:0,written:0,muc:0,between:0,"import":0,awai:0,experi:0,jasmin:0,across:0,attribut:0,altern:0,perfect:0,appreci:[],extend:0,screen:0,were:0,conjunct:0,extens:0,job:0,entir:0,otherwis:0,"5e64a30272af065bd72258c565a03f2f":[],group:0,both:0,cor:0,instant:0,shortliv:0,howev:0,etc:0,instanc:0,grain:0,mani:0,login:0,com:0,load:0,simpli:0,pot:0,sync:0,solv:0,non:0,deploi:0,carbon:0,constant:0,assum:0,malleabl:0,backend:0,quit:[],user_id:0,sucessfulli:0,addition:0,rebuild:0,due:0,been:0,compon:0,json:0,much:0,toolbar:0,interest:0,subscrib:0,modern:0,fire:0,imag:0,xxx:0,rubi:0,convert:0,togeth:0,input:0,last:0,otr:0,plausibl:0,present:0,invit:0,"case":0,myself:[],ident:0,look:0,gnu:0,servic:0,plugin:0,messagesend:0,defin:0,"while":0,kick:0,abov:[],observ:0,hightlight:0,engag:0,helper:0,readi:0,site:0,itself:0,incom:0,rid:0,pat:0,harsh:0,minim:0,receiv:0,media:0,make:0,format:0,same:0,webpag:0,onconnectfacebook:[],html:0,unexpectedli:0,chatroom:0,document:[],medit:[],complet:0,status:0,signon:0,http:0,webserv:0,denot:0,optim:0,roomview:0,upon:0,someon:[],hand:0,fairli:0,"50kb":0,user:0,roominvit:0,uncaught:0,php:0,cssmin:0,recent:0,weibel:0,stateless:0,kept:0,bewar:0,firstli:0,markup:0,min:0,well:0,thought:0,person:0,client:0,command:[],wherebi:0,thi:0,choos:0,everyth:0,usual:0,plural_form:0,protocol:0,just:0,when:0,xep:0,human:0,languag:0,previous:0,web:0,fraught:0,xmlhttprequest:0,expos:0,nick:0,extra:0,had:0,desktop:0,non_amd:0,versa:0,appli:0,els:0,match:0,build:0,applic:0,secreci:0,read:0,traffic:0,know:0,press:0,xss:0,like:0,specif:0,should:0,reload:0,manual:0,benefit:0,api:[],avatar:0,have:0,choic:0,popular:0,output:0,page:0,candi:0,indefinit:0,facebookconnect:[],revers:0,chatboxtoggl:0,who:[],deal:0,visibl:0,some:0,substitu:0,openfir:0,bottom:0,avoid:0,deploy:0,rewriteengin:0,usernam:0,allow_otr:0,inject:0,speak:0,localhost:[],refer:0,somehow:0,plu:0,object:0,msg_receiv:0,host:0,repositori:0,post:0,panel:0,src:0,about:0,actual:0,invitee_jid:0,firstnam:0,controlbox:0,unfortun:0,stand:0,act:0,own:0,curiou:0,within:0,encod:0,automat:0,right:0,empti:0,wrap:0,chang:0,merg:[],git:0,log:0,wai:0,pictur:0,aren:0,transfer:0,"long":0,happi:0,avail:0,trigger:0,localstorag:0,includ:0,lot:0,suit:0,forward:0,"function":0,project:0,head:0,nplural:0,form:0,bundl:0,back:0,link:0,buddystatusmessagechang:0,synonym:0,cryptograph:0,inlin:0,"true":0,bug:0,congratul:0,requirej:0,info:0,made:0,dirti:[],locale_data:0,possibl:0,"default":0,tab:0,asynchron:0,below:0,those:0,toggl:0,legwork:0,emit:0,significantli:0,hash:0,creat:0,movim:[],decrypt:0,doesn:0,mode:0,msgmerg:0,exist:0,chat:[],face:0,probabl:0,again:0,image_typ:0,want:0,tip:[],detail:0,gettext:0,statusmessagechang:0,field:0,valid:0,rememb:0,varieti:[],servernam:0,nice:0,node:0,intend:0,determin:0,duck:0,org:0,vcard_upd:0,elsewher:0,track:0,consid:0,conversej:0,stai:0,lang:0,longer:0,vice:0,directori:0,descript:[],getjson:0,rule:0,ignor:0,token:0,potenti:0,time:0},objtypes:{},objnames:{},filenames:["index"],titles:["Quickstart (to get a demo up and running)"],objects:{},titleterms:{demo:0,roster_group:0,multilingu:0,code:0,xmpp:0,session:0,jshint:0,paramet:[],depend:0,singl:0,configur:0,apach:0,add:0,anim:0,get:0,end:0,amd:0,initi:0,nginx:0,facebook:[],front:0,requir:0,introduct:0,troubleshoot:0,authent:0,server:0,play_sound:0,bad:0,integr:[],debug:0,side:0,domain:0,set:[],habit:0,xhr_user_search_url:0,connect:0,pass:0,fullnam:0,event:0,librari:0,variabl:0,what:0,storag:0,xhr_custom_statu:0,content:0,show_only_online_us:0,use_otr_by_default:0,overcom:0,method:0,run:0,hide_muc_serv:0,javascript:0,visible_toolbar_button:0,bosh:0,xhr_custom_status_url:0,cache_otr_kei:0,manag:0,solut:0,restrict:0,api:0,auto_list_room:0,instal:0,jabber:0,your:0,script:0,support:0,submit:0,getsid:0,recommend:0,type:0,show_controlbox_by_default:0,notif:0,minifi:0,translat:0,i18n:0,getrid:0,sound:0,pull:0,room:0,bugfix:0,exampl:0,record:0,error:0,auto_reconnect:0,problem:0,featur:0,quickstart:0,forward_messag:0,descript:[],auto_subscrib:0,argument:[],tag:0,chat:0,tabl:0,need:0,check:0,bosh_service_url:0,prebind:0,develop:0,message_carbon:0,getbuddi:0,cross:0,other:0,test:0,expose_rid_and_sid:0,you:0,css:0,keepal:0,befor:0,allow_contact_request:0,encrypt:0,minif:0,xhr_user_search:0,off:0,use_vcard:0,request:0,allow_muc:0,without:0,command:0,conflict:0}}) \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index 422756ba4..b91f13b54 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -721,8 +721,8 @@ Converse.js emits events to which you can subscribe from your own Javascript. Concerning events, the following methods are available: -Event Methods -============= +Event API Methods +================= * **on(eventName, callback)**: @@ -808,6 +808,95 @@ Here are the different events that are emitted: | **buddyStatusMessageChanged** | When a chat buddy's custom status message has changed. | ``converse.on('buddyStatusMessageChanged', function (buddy, messageText) { ... });`` | +----------------------------------+---------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------+ +============= +Developer API +============= + +.. Note :: See also the `Event API Methods`_, not listed here. + +initialize +========== + +Initializes converse.js. This method must always be called when using +converse.js. + +The `initialize` method takes a map (also called a hash or dictionary) of +`configuration variables`_. + +Example:: + + converse.initialize({ + allow_otr: true, + auto_list_rooms: false, + auto_subscribe: false, + bosh_service_url: 'https://bind.example.com', + hide_muc_server: false, + i18n: locales['en'], + keepalive: true, + play_sounds: true, + prebind: false, + show_controlbox_by_default: true, + debug: false, + roster_groups: true + }); + + +getBuddy +======== + +Returns a map of attributes for a given buddy (i.e. roster contact), specified +by JID (Jabber ID). + +Example:: + + converse.getBuddy('buddy@example.com') + +The map of attributes: + ++----------------+--------------------------------------------------------------------------------------------------------------------------------------+ +| Attribute | | ++================+======================================================================================================================================+ +| ask | If ask === 'subscribe', then we have asked this person to be our chat buddy. | ++----------------+--------------------------------------------------------------------------------------------------------------------------------------+ +| fullname | The person's full name. | ++----------------+--------------------------------------------------------------------------------------------------------------------------------------+ +| jid | The person's Jabber/XMPP username. | ++----------------+--------------------------------------------------------------------------------------------------------------------------------------+ +| requesting | If true, then this person is asking to be our chat buddy. | ++----------------+--------------------------------------------------------------------------------------------------------------------------------------+ +| subscription | The subscription state between the current user and this chat buddy. Can be `none`, `to`, `from` or `both`. | ++----------------+--------------------------------------------------------------------------------------------------------------------------------------+ +| id | A unique id, same as the jid. | ++----------------+--------------------------------------------------------------------------------------------------------------------------------------+ +| chat_status | The person's chat status. Can be `online`, `offline`, `busy`, `xa` (extended away) or `away`. | ++----------------+--------------------------------------------------------------------------------------------------------------------------------------+ +| user_id | The user id part of the JID (the part before the `@`). | ++----------------+--------------------------------------------------------------------------------------------------------------------------------------+ +| resources | The known resources for this chat buddy. Each resource denotes a separate and connected chat client. | ++----------------+--------------------------------------------------------------------------------------------------------------------------------------+ +| groups | The roster groups in which this chat buddy was placed. | ++----------------+--------------------------------------------------------------------------------------------------------------------------------------+ +| status | Their human readable custom status message. | ++----------------+--------------------------------------------------------------------------------------------------------------------------------------+ +| image_type | The image's file type. | ++----------------+--------------------------------------------------------------------------------------------------------------------------------------+ +| image | The Base64 encoded image data. | ++----------------+--------------------------------------------------------------------------------------------------------------------------------------+ +| url | The buddy's website URL, as specified in their VCard data. | ++----------------+--------------------------------------------------------------------------------------------------------------------------------------+ +| vcard_updated | When last the buddy's VCard was updated. | ++----------------+--------------------------------------------------------------------------------------------------------------------------------------+ + +getRID +====== + +Returns the current RID (request ID) value. + +getSID +====== + +Returns the current SID (Session ID) value. + ============= Configuration ============= @@ -829,6 +918,9 @@ After you have configured *Converse.js*, you'll have to regenerate the minified JS file so that it will include the new settings. Please refer to the `Minification`_ section for more info on how to do this. + + + Configuration variables =======================