Add, test and document an API method for setting the user's status.

fixes #367

Gemfile.lock

 GEM
   remote: https://rubygems.org/
   specs:
-    bourbon (4.2.3)
-      sass (~> 3.4)
-      thor
     sass (3.4.14)
-    thor (0.19.1)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  bourbon
   sass (~> 3.3)
 
 BUNDLED WITH

converse.js

@@ -139,6 +139,16 @@
         }
     };
 
+    var STATUS_WEIGHTS = {
+        'offline':      6,
+        'unavailable':  5,
+        'xa':           4,
+        'away':         3,
+        'dnd':          2,
+        'chat':         1, // We currently don't differentiate between "chat" and "online"
+        'online':       1
+    };
+
     converse.initialize = function (settings, callback) {
         "use strict";
         var converse = this;
@@ -195,14 +205,6 @@
             ENTER: 13,
             FORWARD_SLASH: 47
         };
-        var STATUS_WEIGHTS = {
-            'offline':      6,
-            'unavailable':  5,
-            'xa':           4,
-            'away':         3,
-            'dnd':          2,
-            'online':       1
-        };
 
         var PRETTY_CONNECTION_STATUS = {
             0: 'ERROR',
@@ -4241,8 +4243,9 @@
                     contact = this.get(bare_jid);
                 if (this.isSelf(bare_jid)) {
                     if ((converse.connection.jid !== jid)&&(presence_type !== 'unavailable')) {
-                        // Another resource has changed it's status, we'll update ours as well.
+                        // Another resource has changed its status, we'll update ours as well.
                         converse.xmppstatus.save({'status': chat_status});
+                        if (status_message.length) { converse.xmppstatus.save({'status_message': status_message}); }
                     }
                     return;
                 } else if (($presence.find('x').attr('xmlns') || '').indexOf(Strophe.NS.MUC) === 0) {
@@ -5938,8 +5941,37 @@
               converse.connection.disconnect();
         },
         'account': {
+            // XXX: Deprecated, will be removed with next non-minor release
             'logout': function () {
                 converse.logOut();
+            }
+        },
+        'user': {
+            'logout': function () {
+                converse.logOut();
+            },
+            'status': {
+                'get': function () {
+                    return converse.xmppstatus.get('status');
+                },
+                'set': function (value, message) {
+                    var data = {'status': value};
+                    if (!_.contains(_.keys(STATUS_WEIGHTS), value)) {
+                        throw new Error('Invalid availability value. See https://xmpp.org/rfcs/rfc3921.html#rfc.section.2.2.2.1');
+                    }
+                    if (typeof message == "string") {
+                        data.status_message = message;
+                    }
+                    converse.xmppstatus.save(data);
+                },
+                'message': {
+                    'get': function () {
+                        return converse.xmppstatus.get('status_message');
+                    },
+                    'set': function (stat) {
+                        converse.xmppstatus.save({'status_message': stat});
+                    }
+                }
             },
         },
         'settings': {

css/converse.css

@@ -223,6 +223,8 @@
     content: "\e01f"; }
   #conversejs .icon-online:before {
     content: "\25fc"; }
+  #conversejs .icon-chat:before {
+    content: "\25fc"; }
   #conversejs .icon-opened:before {
     content: "\25bc"; }
   #conversejs .icon-pencil:before {

docs/CHANGES.rst

@@ -4,7 +4,8 @@ Changelog
 0.9.4 (Unreleased)
 ------------------
 
-* #144 Add Ping funcionnality and Pong Handler [thierrytiti]
+* #144 Add Ping functionality and Pong handler [thierrytiti]
+* #367 API methods for changing chat status (online, busy, away etc.) and status message [jcbrand]
 * #389 Allow login panel placeholders and roster item 'Name' translations. [gbonvehi]
 * #394 Option to allow chatting with pending contacts [thierrytiti]
 * #396 Add automatic Away mode and XEP-0352 support [thierrytiti]
@@ -31,7 +32,7 @@ Changelog
 * CSS: Fonts Path: editabable $font-path via sass/variables.scss [thierrytiti]
 * Add offline pretty status to enable translation [thierrytiti]
 * With keepalive, don't send out a presence stanza on each page load [jcbrand]
-* Chat boxes returned by the API now have an ``is_chatroom`` attribute [jcbrand]
+* Chat boxes returned by the API now have an `is_chatroom` attribute [jcbrand]
 
 0.9.3 (2015-05-01)
 ------------------

docs/source/_static/style.css

@@ -6,6 +6,15 @@ h1 {
     font-size: 50px;
 }
 
+h4 {
+    font-weight: bold;
+}
+
+h5 {
+    font-size: 16px;
+    font-weight: bold;
+}
+
 .navbar-brand {
     padding-top: 7px;
 }

sass/_core.scss

@@ -192,6 +192,7 @@
   .icon-notebook:before           { content: "\2710"; }
   .icon-notification:before       { content: "\e01f"; }
   .icon-online:before             { content: "\25fc"; }
+  .icon-chat:before               { content: "\25fc"; }
   .icon-opened:before             { content: "\25bc"; }
   .icon-pencil:before             { content: "\270e"; }
   .icon-phone-hang-up:before      { content: "\260e"; }

spec/converse.js

@@ -130,6 +130,57 @@
             });
         });
 
+        describe("The \"user\" grouping", function () {
+
+            describe("The \"status\" API", function () {
+                beforeEach(function () {
+                    test_utils.closeAllChatBoxes();
+                    test_utils.clearBrowserStorage();
+                    converse.rosterview.model.reset();
+                });
+
+                it("has a method for getting the user's availability", function () {
+                    converse.xmppstatus.set('status', 'online');
+                    expect(converse_api.user.status.get()).toBe('online');
+                    converse.xmppstatus.set('status', 'dnd');
+                    expect(converse_api.user.status.get()).toBe('dnd');
+                });
+
+                it("has a method for setting the user's availability", function () {
+                    converse_api.user.status.set('away');
+                    expect(converse.xmppstatus.get('status')).toBe('away');
+                    converse_api.user.status.set('dnd');
+                    expect(converse.xmppstatus.get('status')).toBe('dnd');
+                    converse_api.user.status.set('xa');
+                    expect(converse.xmppstatus.get('status')).toBe('xa');
+                    converse_api.user.status.set('chat');
+                    expect(converse.xmppstatus.get('status')).toBe('chat');
+                    expect(_.partial(converse_api.user.status.set, 'invalid')).toThrow(
+                        new Error('Invalid availability value. See https://xmpp.org/rfcs/rfc3921.html#rfc.section.2.2.2.1')
+                    );
+                });
+
+                it("allows setting the status message as well", function () {
+                    converse_api.user.status.set('away', "I'm in a meeting");
+                    expect(converse.xmppstatus.get('status')).toBe('away');
+                    expect(converse.xmppstatus.get('status_message')).toBe("I'm in a meeting");
+                });
+
+                it("has a method for getting the user's status message", function () {
+                    converse.xmppstatus.set('status_message', undefined);
+                    expect(converse_api.user.status.message.get()).toBe(undefined);
+                    converse.xmppstatus.set('status_message', "I'm in a meeting");
+                    expect(converse_api.user.status.message.get()).toBe("I'm in a meeting");
+                });
+
+                it("has a method for setting the user's status message", function () {
+                    converse.xmppstatus.set('status_message', undefined);
+                    converse_api.user.status.message.set("I'm in a meeting");
+                    expect(converse.xmppstatus.get('status_message')).toBe("I'm in a meeting");
+                });
+            });
+        });
+
         describe("The \"tokens\" API", $.proxy(function () {
             beforeEach(function () {
                 test_utils.closeAllChatBoxes();