developer_api.rst 35 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126
  1. .. raw:: html
  2. <div id="banner"><a href="https://github.com/jcbrand/converse.js/blob/master/docs/source/theming.rst">Edit me on GitHub</a></div>
  3. =============================
  4. The converse.js developer API
  5. =============================
  6. .. contents:: Table of Contents
  7. :depth: 2
  8. :local:
  9. .. note:: The API documented here is available in Converse.js 0.8.4 and higher.
  10. Earlier versions of Converse.js might have different API methods or none at all.
  11. .. note:: From version 3.0.0 and onwards many API methods have been made
  12. private and available to plugins only. This means that if you want to
  13. use the API, you'll first need to create a plugin from which you can
  14. access it. This change is done to avoid leakage of sensitive data to
  15. malicious or non-whitelisted scripts.
  16. The Converse.js API is broken up into different logical "groupings" (for
  17. example ``converse.plugins`` or ``converse.contacts``).
  18. There are some exceptions to this, like ``converse.initialize``, which aren't
  19. groupings but single methods.
  20. The groupings logically group methods, such as standardised accessors and
  21. mutators::
  22. .get
  23. .set
  24. .add
  25. .remove
  26. So for example, to get a contact, you would do the following::
  27. _converse.api.contacts.get('jid@example.com');
  28. To get multiple contacts, just pass in an array of jids::
  29. _converse.api.contacts.get(['jid1@example.com', 'jid2@example.com']);
  30. To get all contacts, simply call ``get`` without any jids::
  31. _converse.api.contacts.get();
  32. Public API methods
  33. ==================
  34. Publich API methods are those methods that are accessible on the global
  35. ``window.converse`` object. They are public, because any Javascript in the page
  36. can call them. Public methods therefore don't expose any sensitive or closured
  37. data. To do that, you'll need to create a plugin, which has access to the
  38. private API method.
  39. .. _`initialize`:
  40. initialize
  41. ----------
  42. .. note:: This method is the one exception of a method which is not logically grouped as explained above.
  43. Publich API method which initializes converse.js.
  44. This method must always be called when using converse.js.
  45. The `initialize` method takes a map of :ref:`configuration-settings`.
  46. Example:
  47. .. code-block:: javascript
  48. converse.initialize({
  49. allow_otr: true,
  50. auto_list_rooms: false,
  51. auto_subscribe: false,
  52. bosh_service_url: 'https://bind.example.com',
  53. hide_muc_server: false,
  54. i18n: locales['en'],
  55. keepalive: true,
  56. play_sounds: true,
  57. prebind: false,
  58. show_controlbox_by_default: true,
  59. debug: false,
  60. roster_groups: true
  61. });
  62. The **plugin** grouping
  63. ------------------------
  64. Exposes methods for adding and removing plugins. You'll need to write a plugin
  65. if you want to have access to the private API methods defined further down below.
  66. For more information on plugins, read the section :ref:`writing-a-plugin`.
  67. add
  68. ~~~
  69. Registers a new plugin.
  70. .. code-block:: javascript
  71. var plugin = {
  72. initialize: function () {
  73. // method on any plugin (if it exists) as soon as the plugin has
  74. // been loaded.
  75. // Inside this method, you have access to the closured
  76. // _converse object, which contains the core logic and data
  77. // structures of converse.js
  78. }
  79. }
  80. converse.plugins.add('myplugin', plugin);
  81. Private API methods
  82. ===================
  83. The private API methods are only accessible via the closured ``_converse``
  84. object, which is only available to plugins.
  85. These methods are kept private (i.e. not global) because they may return
  86. sensitive data which should be kept off-limits to other 3rd-party scripts
  87. that might be running in the page.
  88. .. note:: The example code snippets shown below are a bit contrived. I've added
  89. the minimum plugin boilerplace around the actual example, to show that
  90. these API methods can only be called inside a plugin where the
  91. ``_converse`` object is available. However, sometimes other considerations
  92. need to be made as well. For example, for certain API methods it is
  93. necessary to first wait until the data has been received from the XMPP
  94. server (or from the browser's sessionStorage cache). Due to
  95. time-constriaints these limitations are ignored in the examples below. For
  96. a fuller picture, refer to the section :ref:`events-API` as well.
  97. emit
  98. ----
  99. This method allows you to emit events, which can be listened to via
  100. ``_converse.api.listen.on`` or ``_converse.api.listen.once``.
  101. For example:
  102. .. code-block:: javascript
  103. _converse.emit('foo-completed');
  104. Additionally, if a promise has been registered under the same name
  105. (via ``_converse.api.promises.add``), then that promise will also be resolved
  106. when calling ``emit``.
  107. send
  108. ----
  109. Allows you to send XML stanzas.
  110. For example, to send a message stanza:
  111. .. code-block:: javascript
  112. converse.plugins.add('myplugin', {
  113. initialize: function () {
  114. var msg = converse.env.$msg({
  115. from: 'juliet@example.com/balcony',
  116. to:'romeo@example.net',
  117. type:'chat'
  118. });
  119. this._converse.api.send(msg);
  120. }
  121. });
  122. .. _`waituntil-grouping`:
  123. waitUntil
  124. ---------
  125. This method can be used to wait for promises. Promises are similar to events
  126. (for event handling, refer to the :ref:`listen-grouping`), but they differ in
  127. two important ways:
  128. * A promise gets resolved only once, whereas events can fire multiple times.
  129. * A handler registered for a promise, will still fire *after* the promise has
  130. been resolved, which is not the case with an event handler.
  131. Converse.js has the following promises:
  132. * cachedRoster
  133. * chatBoxesFetched
  134. * connected
  135. * pluginsInitialized
  136. * roster
  137. * rosterContactsFetched
  138. * rosterGroupsFetched
  139. * rosterInitialized
  140. * statusInitialized
  141. * roomsPanelRendered (only via the `converse-muc` plugin)
  142. Below is an example from `converse-muc.js <https://github.com/jcbrand/converse.js/blob/master/src/converse-muc.js>`_
  143. where the `rosterContactsFetched` promise is waited on. The method
  144. `this.initInviteWidget` will initialize the chatroom invitation widget.
  145. .. code-block:: javascript
  146. _converse.api.waitUntil('rosterContactsFetched').then(this.initInviteWidget.bind(this));
  147. The line above executes only once a chatroom has been opened and entered, so
  148. using an event handler here would not work, since the event might have fired
  149. already by that time.
  150. The **archive** grouping
  151. ------------------------
  152. Converse.js supports the *Message Archive Management*
  153. (`XEP-0313 <https://xmpp.org/extensions/xep-0313.html>`_) protocol,
  154. through which it is able to query an XMPP server for archived messages.
  155. See also the **message_archiving** option in the :ref:`configuration-settings` section, which you'll usually
  156. want to in conjunction with this API.
  157. query
  158. ~~~~~
  159. The ``query`` method is used to query for archived messages.
  160. It accepts the following optional parameters:
  161. * **options** an object containing the query parameters. Valid query parameters
  162. are ``with``, ``start``, ``end``, ``first``, ``last``, ``after``, ``before``, ``index`` and ``count``.
  163. * **callback** is the callback method that will be called when all the messages
  164. have been received.
  165. * **errback** is the callback method to be called when an error is returned by
  166. the XMPP server, for example when it doesn't support message archiving.
  167. Examples
  168. ^^^^^^^^
  169. **Requesting all archived messages**
  170. The simplest query that can be made is to simply not pass in any parameters.
  171. Such a query will return all archived messages for the current user.
  172. Generally, you'll however always want to pass in a callback method, to receive
  173. the returned messages.
  174. .. code-block:: javascript
  175. converse.plugins.add('myplugin', {
  176. initialize: function () {
  177. var errback = function (iq) {
  178. // The query was not successful, perhaps inform the user?
  179. // The IQ stanza returned by the XMPP server is passed in, so that you
  180. // may inspect it and determine what the problem was.
  181. }
  182. var callback = function (messages) {
  183. // Do something with the messages, like showing them in your webpage.
  184. }
  185. this._converse.api.archive.query(callback, errback))
  186. }
  187. });
  188. **Waiting until server support has been determined**
  189. The query method will only work if converse.js has been able to determine that
  190. the server supports MAM queries, otherwise the following error will be raised:
  191. - *This server does not support XEP-0313, Message Archive Management*
  192. The very first time converse.js loads in a browser tab, if you call the query
  193. API too quickly, the above error might appear because service discovery has not
  194. yet been completed.
  195. To work solve this problem, you can first listen for the ``serviceDiscovered`` event,
  196. through which you can be informed once support for MAM has been determined.
  197. For example:
  198. .. code-block:: javascript
  199. converse.plugins.add('myplugin', {
  200. initialize: function () {
  201. var _converse = this._converse;
  202. _converse.api.listen.on('serviceDiscovered', function (feature) {
  203. if (feature.get('var') === converse.env.Strophe.NS.MAM) {
  204. _converse.api.archive.query()
  205. }
  206. });
  207. converse.listen.on('serviceDiscovered', function (feature) {
  208. if (feature.get('var') === converse.env.Strophe.NS.MAM) {
  209. converse.archive.query()
  210. }
  211. });
  212. **Requesting all archived messages for a particular contact or room**
  213. To query for messages sent between the current user and another user or room,
  214. the query options need to contain the the JID (Jabber ID) of the user or
  215. room under the ``with`` key.
  216. .. code-block:: javascript
  217. converse.plugins.add('myplugin', {
  218. initialize: function () {
  219. // For a particular user
  220. this._converse.api.archive.query({'with': 'john@doe.net'}, callback, errback);)
  221. // For a particular room
  222. this._converse.api.archive.query({'with': 'discuss@conference.doglovers.net'}, callback, errback);)
  223. }
  224. });
  225. **Requesting all archived messages before or after a certain date**
  226. The ``start`` and ``end`` parameters are used to query for messages
  227. within a certain timeframe. The passed in date values may either be ISO8601
  228. formatted date strings, or Javascript Date objects.
  229. .. code-block:: javascript
  230. converse.plugins.add('myplugin', {
  231. initialize: function () {
  232. var options = {
  233. 'with': 'john@doe.net',
  234. 'start': '2010-06-07T00:00:00Z',
  235. 'end': '2010-07-07T13:23:54Z'
  236. };
  237. this._converse.api.archive.query(options, callback, errback);
  238. }
  239. });
  240. **Limiting the amount of messages returned**
  241. The amount of returned messages may be limited with the ``max`` parameter.
  242. By default, the messages are returned from oldest to newest.
  243. .. code-block:: javascript
  244. converse.plugins.add('myplugin', {
  245. initialize: function () {
  246. // Return maximum 10 archived messages
  247. this._converse.api.archive.query({'with': 'john@doe.net', 'max':10}, callback, errback);
  248. }
  249. });
  250. **Paging forwards through a set of archived messages**
  251. When limiting the amount of messages returned per query, you might want to
  252. repeatedly make a further query to fetch the next batch of messages.
  253. To simplify this usecase for you, the callback method receives not only an array
  254. with the returned archived messages, but also a special RSM (*Result Set
  255. Management*) object which contains the query parameters you passed in, as well
  256. as two utility methods ``next``, and ``previous``.
  257. When you call one of these utility methods on the returned RSM object, and then
  258. pass the result into a new query, you'll receive the next or previous batch of
  259. archived messages. Please note, when calling these methods, pass in an integer
  260. to limit your results.
  261. .. code-block:: javascript
  262. converse.plugins.add('myplugin', {
  263. initialize: function () {
  264. var _converse = this._converse;
  265. var callback = function (messages, rsm) {
  266. // Do something with the messages, like showing them in your webpage.
  267. // ...
  268. // You can now use the returned "rsm" object, to fetch the next batch of messages:
  269. _converse.api.archive.query(rsm.next(10), callback, errback))
  270. }
  271. _converse.api.archive.query({'with': 'john@doe.net', 'max':10}, callback, errback);
  272. }
  273. });
  274. **Paging backwards through a set of archived messages**
  275. To page backwards through the archive, you need to know the UID of the message
  276. which you'd like to page backwards from and then pass that as value for the
  277. ``before`` parameter. If you simply want to page backwards from the most recent
  278. message, pass in the ``before`` parameter with an empty string value ``''``.
  279. .. code-block:: javascript
  280. converse.plugins.add('myplugin', {
  281. initialize: function () {
  282. var _converse = this._converse;
  283. _converse.api.archive.query({'before': '', 'max':5}, function (message, rsm) {
  284. // Do something with the messages, like showing them in your webpage.
  285. // ...
  286. // You can now use the returned "rsm" object, to fetch the previous batch of messages:
  287. rsm.previous(5); // Call previous method, to update the object's parameters,
  288. // passing in a limit value of 5.
  289. // Now we query again, to get the previous batch.
  290. _converse.api.archive.query(rsm, callback, errback);
  291. }
  292. }
  293. });
  294. The **connection** grouping
  295. ---------------------------
  296. This grouping collects API functions related to the XMPP connection.
  297. connected
  298. ~~~~~~~~~
  299. A boolean attribute (i.e. not a callable) which is set to `true` or `false` depending
  300. on whether there is an established connection.
  301. disconnect
  302. ~~~~~~~~~~
  303. Terminates the connection.
  304. The **user** grouping
  305. ---------------------
  306. This grouping collects API functions related to the current logged in user.
  307. jid
  308. ~~~
  309. Return's the current user's full JID (Jabber ID).
  310. .. code-block:: javascript
  311. converse.plugins.add('myplugin', {
  312. initialize: function () {
  313. alert(this._converse.api.user.jid());
  314. }
  315. });
  316. login
  317. ~~~~~
  318. Logs the user in. This method can accept a map with the credentials, like this:
  319. .. code-block:: javascript
  320. converse.plugins.add('myplugin', {
  321. initialize: function () {
  322. this._converse.api.user.login({
  323. 'jid': 'dummy@example.com',
  324. 'password': 'secret'
  325. });
  326. }
  327. });
  328. or it can be called without any parameters, in which case converse.js will try
  329. to log the user in by calling the `prebind_url` or `credentials_url` depending
  330. on whether prebinding is used or not.
  331. logout
  332. ~~~~~~
  333. Log the user out of the current XMPP session.
  334. .. code-block:: javascript
  335. converse.plugins.add('myplugin', {
  336. initialize: function () {
  337. this._converse.api.user.logout();
  338. }
  339. });
  340. The **status** sub-grouping
  341. ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  342. Set and get the user's chat status, also called their *availability*.
  343. get
  344. ^^^
  345. Return the current user's availability status:
  346. .. code-block:: javascript
  347. converse.plugins.add('myplugin', {
  348. initialize: function () {
  349. alert(this._converse.api.user.status.get()); // For example "dnd"
  350. }
  351. });
  352. set
  353. ^^^
  354. The user's status can be set to one of the following values:
  355. * **away**
  356. * **dnd**
  357. * **offline**
  358. * **online**
  359. * **unavailable**
  360. * **xa**
  361. For example:
  362. .. code-block:: javascript
  363. converse.plugins.add('myplugin', {
  364. initialize: function () {
  365. this._converse.api.user.status.set('dnd');
  366. }
  367. });
  368. Because the user's availability is often set together with a custom status
  369. message, this method also allows you to pass in a status message as a
  370. second parameter:
  371. .. code-block:: javascript
  372. converse.plugins.add('myplugin', {
  373. initialize: function () {
  374. this._converse.api.user.status.set('dnd', 'In a meeting');
  375. }
  376. });
  377. The **message** sub-grouping
  378. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  379. The ``user.status.message`` sub-grouping exposes methods for setting and
  380. retrieving the user's custom status message.
  381. .. code-block:: javascript
  382. converse.plugins.add('myplugin', {
  383. initialize: function () {
  384. this._converse.api.user.status.message.set('In a meeting');
  385. // Returns "In a meeting"
  386. return this._converse.api.user.status.message.get();
  387. }
  388. });
  389. The **contacts** grouping
  390. -------------------------
  391. get
  392. ~~~
  393. This method is used to retrieve roster contacts.
  394. To get a single roster contact, call the method with the contact's JID (Jabber ID):
  395. .. code-block:: javascript
  396. converse.plugins.add('myplugin', {
  397. initialize: function () {
  398. var _converse = this._converse;
  399. _converse.api.listen.on('rosterContactsFetched', function () {
  400. var contact = _converse.api.contacts.get('buddy@example.com')
  401. });
  402. }
  403. });
  404. To get multiple contacts, pass in an array of JIDs:
  405. .. code-block:: javascript
  406. converse.plugins.add('myplugin', {
  407. initialize: function () {
  408. var _converse = this._converse;
  409. _converse.api.listen.on('rosterContactsFetched', function () {
  410. var contacts = _converse.api.contacts.get(
  411. ['buddy1@example.com', 'buddy2@example.com']
  412. )
  413. });
  414. }
  415. });
  416. To return all contacts, simply call ``get`` without any parameters:
  417. .. code-block:: javascript
  418. converse.plugins.add('myplugin', {
  419. initialize: function () {
  420. var _converse = this._converse;
  421. _converse.api.listen.on('rosterContactsFetched', function () {
  422. var contacts = _converse.api.contacts.get();
  423. });
  424. }
  425. });
  426. The returned roster contact objects have these attributes:
  427. +----------------+-----------------------------------------------------------------------------------------------------------------+
  428. | Attribute | |
  429. +================+=================================================================================================================+
  430. | ask | If ask === 'subscribe', then we have asked this person to be our chat buddy. |
  431. +----------------+-----------------------------------------------------------------------------------------------------------------+
  432. | fullname | The person's full name. |
  433. +----------------+-----------------------------------------------------------------------------------------------------------------+
  434. | jid | The person's Jabber/XMPP username. |
  435. +----------------+-----------------------------------------------------------------------------------------------------------------+
  436. | requesting | If true, then this person is asking to be our chat buddy. |
  437. +----------------+-----------------------------------------------------------------------------------------------------------------+
  438. | subscription | The subscription state between the current user and this chat buddy. Can be `none`, `to`, `from` or `both`. |
  439. +----------------+-----------------------------------------------------------------------------------------------------------------+
  440. | id | A unique id, same as the jid. |
  441. +----------------+-----------------------------------------------------------------------------------------------------------------+
  442. | chat_status | The person's chat status. Can be `online`, `offline`, `busy`, `xa` (extended away) or `away`. |
  443. +----------------+-----------------------------------------------------------------------------------------------------------------+
  444. | user_id | The user id part of the JID (the part before the `@`). |
  445. +----------------+-----------------------------------------------------------------------------------------------------------------+
  446. | resources | The known resources for this chat buddy. Each resource denotes a separate and connected chat client. |
  447. +----------------+-----------------------------------------------------------------------------------------------------------------+
  448. | groups | The roster groups in which this chat buddy was placed. |
  449. +----------------+-----------------------------------------------------------------------------------------------------------------+
  450. | status | Their human readable custom status message. |
  451. +----------------+-----------------------------------------------------------------------------------------------------------------+
  452. | image_type | The image's file type. |
  453. +----------------+-----------------------------------------------------------------------------------------------------------------+
  454. | image | The Base64 encoded image data. |
  455. +----------------+-----------------------------------------------------------------------------------------------------------------+
  456. | url | The buddy's website URL, as specified in their VCard data. |
  457. +----------------+-----------------------------------------------------------------------------------------------------------------+
  458. | vcard_updated | When last the buddy's VCard was updated. |
  459. +----------------+-----------------------------------------------------------------------------------------------------------------+
  460. add
  461. ~~~
  462. Add a contact.
  463. Provide the JID of the contact you want to add:
  464. .. code-block:: javascript
  465. _converse.api.contacts.add('buddy@example.com')
  466. You may also provide the fullname. If not present, we use the jid as fullname:
  467. .. code-block:: javascript
  468. _converse.api.contacts.add('buddy@example.com', 'Buddy')
  469. The **chats** grouping
  470. ----------------------
  471. Note, for MUC chat rooms, you need to use the "rooms" grouping instead.
  472. get
  473. ~~~
  474. Returns an object representing a chat box.
  475. To return a single chat box, provide the JID of the contact you're chatting
  476. with in that chat box:
  477. .. code-block:: javascript
  478. _converse.api.chats.get('buddy@example.com')
  479. To return an array of chat boxes, provide an array of JIDs:
  480. .. code-block:: javascript
  481. _converse.api.chats.get(['buddy1@example.com', 'buddy2@example.com'])
  482. To return all open chat boxes, call the method without any JIDs::
  483. _converse.api.chats.get()
  484. open
  485. ~~~~
  486. Opens a chat box and returns a Backbone.View object representing a chat box.
  487. To open a single chat box, provide the JID of the contact:
  488. .. code-block:: javascript
  489. converse.plugins.add('myplugin', {
  490. initialize: function () {
  491. this._converse.api.chats.open('buddy@example.com')
  492. }
  493. });
  494. To return an array of chat boxes, provide an array of JIDs:
  495. .. code-block:: javascript
  496. converse.plugins.add('myplugin', {
  497. initialize: function () {
  498. this._converse.api.chats.open(['buddy1@example.com', 'buddy2@example.com'])
  499. }
  500. });
  501. *The returned chat box object contains the following methods:*
  502. +-------------------+------------------------------------------+
  503. | Method | Description |
  504. +===================+==========================================+
  505. | close | Close the chat box. |
  506. +-------------------+------------------------------------------+
  507. | focus | Focuses the chat box textarea |
  508. +-------------------+------------------------------------------+
  509. | model.endOTR | End an OTR (Off-the-record) session. |
  510. +-------------------+------------------------------------------+
  511. | model.get | Get an attribute (i.e. accessor). |
  512. +-------------------+------------------------------------------+
  513. | model.initiateOTR | Start an OTR (off-the-record) session. |
  514. +-------------------+------------------------------------------+
  515. | model.maximize | Minimize the chat box. |
  516. +-------------------+------------------------------------------+
  517. | model.minimize | Maximize the chat box. |
  518. +-------------------+------------------------------------------+
  519. | model.set | Set an attribute (i.e. mutator). |
  520. +-------------------+------------------------------------------+
  521. | show | Opens/shows the chat box. |
  522. +-------------------+------------------------------------------+
  523. *The get and set methods can be used to retrieve and change the following attributes:*
  524. +-------------+-----------------------------------------------------+
  525. | Attribute | Description |
  526. +=============+=====================================================+
  527. | height | The height of the chat box. |
  528. +-------------+-----------------------------------------------------+
  529. | url | The URL of the chat box heading. |
  530. +-------------+-----------------------------------------------------+
  531. The **rooms** grouping
  532. ----------------------
  533. get
  534. ~~~
  535. Returns an object representing a multi user chat box (room).
  536. It takes 3 parameters:
  537. * the room JID (if not specified, all rooms will be returned).
  538. * a map (object) containing any extra room attributes For example, if you want
  539. to specify the nickname, use ``{'nick': 'bloodninja'}``. Previously (before
  540. version 1.0.7, the second parameter only accepted the nickname (as a string
  541. value). This is currently still accepted, but then you can't pass in any
  542. other room attributes. If the nickname is not specified then the node part of
  543. the user's JID will be used.
  544. * a boolean, indicating whether the room should be created if not found (default: `false`)
  545. .. code-block:: javascript
  546. converse.plugins.add('myplugin', {
  547. initialize: function () {
  548. var nick = 'dread-pirate-roberts';
  549. var create_if_not_found = true;
  550. this._converse.api.rooms.open(
  551. 'group@muc.example.com',
  552. {'nick': nick},
  553. create_if_not_found
  554. )
  555. }
  556. });
  557. open
  558. ~~~~
  559. Opens a multi user chat box and returns an object representing it.
  560. Similar to the ``chats.get`` API.
  561. It takes 2 parameters:
  562. * The room JID or JIDs (if not specified, all currently open rooms will be returned).
  563. * A map (object) containing any extra room attributes. For example, if you want
  564. to specify the nickname, use ``{'nick': 'bloodninja'}``.
  565. To open a single multi user chat box, provide the JID of the room:
  566. .. code-block:: javascript
  567. converse.plugins.add('myplugin', {
  568. initialize: function () {
  569. this._converse.api.rooms.open('group@muc.example.com')
  570. }
  571. });
  572. To return an array of rooms, provide an array of room JIDs:
  573. .. code-block:: javascript
  574. converse.plugins.add('myplugin', {
  575. initialize: function () {
  576. this._converse.api.rooms.open(['group1@muc.example.com', 'group2@muc.example.com'])
  577. }
  578. });
  579. To setup a custom nickname when joining the room, provide the optional nick argument:
  580. .. code-block:: javascript
  581. converse.plugins.add('myplugin', {
  582. initialize: function () {
  583. this._converse.api.rooms.open('group@muc.example.com', {'nick': 'mycustomnick'})
  584. }
  585. });
  586. Room attributes that may be passed in:
  587. * *nick*: The nickname to be used
  588. * *auto_configure*: A boolean, indicating whether the room should be configured
  589. automatically or not. If set to ``true``, then it makes sense to pass in
  590. configuration settings.
  591. * *roomconfig*: A map of configuration settings to be used when the room gets
  592. configured automatically. Currently it doesn't make sense to specify
  593. ``roomconfig`` values if ``auto_configure`` is set to ``false``.
  594. For a list of configuration values that can be passed in, refer to these values
  595. in the `XEP-0045 MUC specification <http://xmpp.org/extensions/xep-0045.html#registrar-formtype-owner>`_.
  596. The values should be named without the ``muc#roomconfig_`` prefix.
  597. * *maximize*: A boolean, indicating whether minimized rooms should also be
  598. maximized, when opened. Set to ``false`` by default.
  599. For example, opening a room with a specific default configuration:
  600. .. code-block:: javascript
  601. converse.plugins.add('myplugin', {
  602. initialize: function () {
  603. this._converse.api.rooms.open(
  604. 'myroom@conference.example.org',
  605. { 'nick': 'coolguy69',
  606. 'auto_configure': true,
  607. 'roomconfig': {
  608. 'changesubject': false,
  609. 'membersonly': true,
  610. 'persistentroom': true,
  611. 'publicroom': true,
  612. 'roomdesc': 'Comfy room for hanging out',
  613. 'whois': 'anyone'
  614. }
  615. },
  616. true
  617. );
  618. }
  619. });
  620. .. note:: `multi-list` configuration values are not yet supported.
  621. close
  622. ~~~~~
  623. Lets you close open chat rooms. You can call this method without any arguments
  624. to close all open chat rooms, or you can specify a single JID or an array of
  625. JIDs.
  626. .. _`promises-grouping`:
  627. The **promises** grouping
  628. -------------------------
  629. Converse.js and its plugins emit various events which you can listen to via the
  630. :refs:`listen-grouping`.
  631. These events can also be turned into promises, and by default some already
  632. are.
  633. The core events, which are also promises are:
  634. * cachedRoster
  635. * chatBoxesFetched
  636. * connected
  637. * pluginsInitialized
  638. * roster
  639. * rosterContactsFetched
  640. * rosterGroupsFetched
  641. * rosterInitialized
  642. * statusInitialized
  643. The various plugins might also provide promises, and they do this by using the
  644. ``promises.add`` api method.
  645. add(promises)
  646. ~~~~~~~~~~~~~
  647. By calling ``promises.add``, a new promise is made available for other code or
  648. plugins to depend on via the ``_converse.api.waitUntil`` method.
  649. This method accepts either a string or list of strings which specify the
  650. promise(s) to be added.
  651. For example:
  652. .. code-block:: javascript
  653. converse.plugins.add('myplugin', {
  654. initialize: function () {
  655. this._converse.api.promises.add('foo-completed');
  656. }
  657. });
  658. Generally, it's the responsibility of the plugin which adds the promise to
  659. also resolve it.
  660. This is done by calling ``_converse.api.emit``, which not only resolve the
  661. promise, but also emit an event with the same name (which can be listened to
  662. via ``_converse.api.listen``).
  663. For example:
  664. .. code-block:: javascript
  665. _converse.api.emit('foo-completed');
  666. The **settings** grouping
  667. -------------------------
  668. This grouping allows access to the configuration settings of converse.js.
  669. .. _`settings-update`:
  670. update(settings)
  671. ~~~~~~~~~~~~~~~~
  672. Allows new configuration settings to be specified, or new default values for
  673. existing configuration settings to be specified.
  674. For example:
  675. .. code-block:: javascript
  676. converse.plugins.add('myplugin', {
  677. initialize: function () {
  678. this._converse.api.settings.update({
  679. 'enable_foo': true
  680. });
  681. }
  682. });
  683. The user can then override the default value of the configuration setting when
  684. calling `converse.initialize`.
  685. For example:
  686. .. code-block:: javascript
  687. converse.initialize({
  688. 'enable_foo': false
  689. });
  690. get(key)
  691. ~~~~~~~~
  692. Returns the value of a configuration settings. For example:
  693. .. code-block:: javascript
  694. converse.plugins.add('myplugin', {
  695. initialize: function () {
  696. // default value would be false;
  697. alert(this._converse.api.settings.get("play_sounds"));
  698. }
  699. });
  700. set(key, value) or set(object)
  701. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  702. Set one or many configuration settings. For example:
  703. .. code-block:: javascript
  704. converse.plugins.add('myplugin', {
  705. initialize: function () {
  706. this._converse.api.settings.set("play_sounds", true);
  707. }
  708. });
  709. or :
  710. .. code-block:: javascript
  711. converse.plugins.add('myplugin', {
  712. initialize: function () {
  713. this._converse.api.settings.set({
  714. "play_sounds", true,
  715. "hide_offline_users" true
  716. });
  717. }
  718. });
  719. Note, this is not an alternative to calling ``converse.initialize``, which still needs
  720. to be called. Generally, you'd use this method after converse.js is already
  721. running and you want to change the configuration on-the-fly.
  722. The **tokens** grouping
  723. -----------------------
  724. get
  725. ~~~
  726. Returns a token, either the RID or SID token depending on what's asked for.
  727. Example:
  728. .. code-block:: javascript
  729. converse.plugins.add('myplugin', {
  730. initialize: function () {
  731. alert(this._converse.api.tokens.get('rid'));
  732. }
  733. });
  734. .. _`listen-grouping`:
  735. The **listen** grouping
  736. -----------------------
  737. Converse.js emits events to which you can subscribe from your own Javascript.
  738. Concerning events, the following methods are available under the "listen"
  739. grouping:
  740. * **on(eventName, callback, [context])**:
  741. Calling the ``on`` method allows you to subscribe to an event.
  742. Every time the event fires, the callback method specified by ``callback`` will be
  743. called.
  744. Parameters:
  745. * ``eventName`` is the event name as a string.
  746. * ``callback`` is the callback method to be called when the event is emitted.
  747. * ``context`` (optional), the value of the `this` parameter for the callback.
  748. For example:
  749. .. code-block:: javascript
  750. _converse.api.listen.on('message', function (messageXML) { ... });
  751. * **once(eventName, callback, [context])**:
  752. Calling the ``once`` method allows you to listen to an event
  753. exactly once.
  754. Parameters:
  755. * ``eventName`` is the event name as a string.
  756. * ``callback`` is the callback method to be called when the event is emitted.
  757. * ``context`` (optional), the value of the `this` parameter for the callback.
  758. For example:
  759. .. code-block:: javascript
  760. _converse.api.listen.once('message', function (messageXML) { ... });
  761. * **not(eventName, callback)**
  762. To stop listening to an event, you can use the ``not`` method.
  763. Parameters:
  764. * ``eventName`` is the event name as a string.
  765. * ``callback`` refers to the function that is to be no longer executed.
  766. For example:
  767. .. code-block:: javascript
  768. _converse.api.listen.not('message', function (messageXML) { ... });