Document the update to the rooms API.

This commit is contained in:
JC Brand 2016-08-21 11:09:08 +00:00
parent b8aaf751d2
commit b0de7948f3
2 changed files with 16 additions and 4 deletions

View File

@ -2,6 +2,7 @@
## 1.0.7 (Unreleased) ## 1.0.7 (Unreleased)
- Continuously attempt to resurrect dead connections when `auto_reconnect` is `true`. [jcbrand] - Continuously attempt to resurrect dead connections when `auto_reconnect` is `true`. [jcbrand]
- Update the 'rooms' API to allow user to pass in room attributes. [jcbrand]
- Add new configuration setting [message_storage](https://conversejs.org/docs/html/configuration.html#message_storage) [jcbrand] - Add new configuration setting [message_storage](https://conversejs.org/docs/html/configuration.html#message_storage) [jcbrand]
- Hardcode the storage for roster contacts and chatroom occupants to `sessionStorage`. [jcbrand] - Hardcode the storage for roster contacts and chatroom occupants to `sessionStorage`. [jcbrand]

View File

@ -656,14 +656,19 @@ Returns an object representing a multi user chat box (room).
It takes 3 parameters: It takes 3 parameters:
* the room JID (if not specified, all rooms will be returned). * the room JID (if not specified, all rooms will be returned).
* the user's nickname (if not specified, the node part of the user's JID will be used). * a map (object) containing any extra room attributes For example, if you want
* boolean, indicating whether the room should be created if not found (default: `false`) to specify the nickname, use ``{'nick': 'bloodninja'}``. Previously (before
version 1.0.7, the second parameter only accepted the nickname (as a string
value). This is currently still accepted, but then you can't pass in any
other room attributes. If the nickname is not specified then the node part of
the user's JID will be used.
* a boolean, indicating whether the room should be created if not found (default: `false`)
.. code-block:: javascript .. code-block:: javascript
var nick = 'dread-pirate-roberts'; var nick = 'dread-pirate-roberts';
var create_if_not_found = true; var create_if_not_found = true;
converse.rooms.open('group@muc.example.com', nick, create_if_not_found) converse.rooms.open('group@muc.example.com', {'nick': nick}, create_if_not_found)
open open
~~~~ ~~~~
@ -671,6 +676,12 @@ open
Opens a multi user chat box and returns an object representing it. Opens a multi user chat box and returns an object representing it.
Similar to chats.get API Similar to chats.get API
It takes 2 parameters:
* the room JID (if not specified, all rooms will be returned).
* a map (object) containing any extra room attributes. For example, if you want
to specify the nickname, use ``{'nick': 'bloodninja'}``.
To open a single multi user chat box, provide the JID of the room: To open a single multi user chat box, provide the JID of the room:
.. code-block:: javascript .. code-block:: javascript
@ -687,7 +698,7 @@ To setup a custom nickname when joining the room, provide the optional nick argu
.. code-block:: javascript .. code-block:: javascript
converse.rooms.open('group@muc.example.com', 'mycustomnick') converse.rooms.open('group@muc.example.com', {'nick': 'mycustomnick'})
close close
~~~~~ ~~~~~