Refactor `converse-vcard` and add API method to fetch a VCard

CHANGES.md

@@ -29,6 +29,8 @@
 ### API changes
 - New API method `_converse.disco.supports` to check whether a certain
   service discovery feature is supported by an entity.
+- New API method `_converse.api.vcard.get` which fetches the VCard for a
+  particular JID.
 
 ### UX/UI changes
 - Use CSS3 fade transitions to render various elements.

docs/source/developer_api.rst

@@ -829,6 +829,67 @@ To return an array of chat boxes, provide an array of JIDs:
 | url         | The URL of the chat box heading.                    |
 +-------------+-----------------------------------------------------+
 
+.. _`listen-grouping`:
+
+The **listen** grouping
+-----------------------
+
+Converse.js emits events to which you can subscribe from your own JavaScript.
+
+Concerning events, the following methods are available under the "listen"
+grouping:
+
+* **on(eventName, callback, [context])**:
+
+    Calling the ``on`` method allows you to subscribe to an event.
+    Every time the event fires, the callback method specified by ``callback`` will be
+    called.
+
+    Parameters:
+
+    * ``eventName`` is the event name as a string.
+    * ``callback`` is the callback method to be called when the event is emitted.
+    * ``context`` (optional), the value of the `this` parameter for the callback.
+
+    For example:
+
+.. code-block:: javascript
+
+        _converse.api.listen.on('message', function (messageXML) { ... });
+
+* **once(eventName, callback, [context])**:
+
+    Calling the ``once`` method allows you to listen to an event
+    exactly once.
+
+    Parameters:
+
+    * ``eventName`` is the event name as a string.
+    * ``callback`` is the callback method to be called when the event is emitted.
+    * ``context`` (optional), the value of the `this` parameter for the callback.
+
+    For example:
+
+.. code-block:: javascript
+
+        _converse.api.listen.once('message', function (messageXML) { ... });
+
+* **not(eventName, callback)**
+
+    To stop listening to an event, you can use the ``not`` method.
+
+    Parameters:
+
+    * ``eventName`` is the event name as a string.
+    * ``callback`` refers to the function that is to be no longer executed.
+
+    For example:
+
+.. code-block:: javascript
+
+        _converse.api.listen.not('message', function (messageXML) { ... });
+
+
 The **rooms** grouping
 ----------------------
 
@@ -1130,63 +1191,28 @@ Example:
     });
 
 
-.. _`listen-grouping`:
-
-The **listen** grouping
+The **vcard** grouping
 -----------------------
 
-Converse.js emits events to which you can subscribe from your own JavaScript.
-
-Concerning events, the following methods are available under the "listen"
-grouping:
-
-* **on(eventName, callback, [context])**:
-
-    Calling the ``on`` method allows you to subscribe to an event.
-    Every time the event fires, the callback method specified by ``callback`` will be
-    called.
-
-    Parameters:
-
-    * ``eventName`` is the event name as a string.
-    * ``callback`` is the callback method to be called when the event is emitted.
-    * ``context`` (optional), the value of the `this` parameter for the callback.
-
-    For example:
-
-.. code-block:: javascript
-
-        _converse.api.listen.on('message', function (messageXML) { ... });
-
-* **once(eventName, callback, [context])**:
-
-    Calling the ``once`` method allows you to listen to an event
-    exactly once.
-
-    Parameters:
+get
+~~~
 
-    * ``eventName`` is the event name as a string.
-    * ``callback`` is the callback method to be called when the event is emitted.
-    * ``context`` (optional), the value of the `this` parameter for the callback.
+Returns a Promise which results with the VCard data for a particular JID.
 
-    For example:
+Example:
 
 .. code-block:: javascript
 
-        _converse.api.listen.once('message', function (messageXML) { ... });
-
-* **not(eventName, callback)**
-
-    To stop listening to an event, you can use the ``not`` method.
-
-    Parameters:
-
-    * ``eventName`` is the event name as a string.
-    * ``callback`` refers to the function that is to be no longer executed.
-
-    For example:
-
-.. code-block:: javascript
+    converse.plugins.add('myplugin', {
+        initialize: function () {
 
-        _converse.api.listen.not('message', function (messageXML) { ... });
+            _converse.api.waitUntil('rosterContactsFetched').then(() => {
+                this._converse.api.vcard.get('someone@example.org').then(
+                    (vcard) => {
+                        // Do something with the vcard...
+                    }
+                );
+            });
 
+        }
+    });

spec/controlbox.js

@@ -1146,35 +1146,38 @@
 
                 var stanza = $pres({from: 'data@enterprise/resource', type: 'subscribe'});
                 _converse.connection._dataRecv(test_utils.createRequest(stanza));
-                expect(_converse.roster.pluck('jid').length).toBe(1);
-                expect(_.includes(_converse.roster.pluck('jid'), 'data@enterprise')).toBeTruthy();
-
-                // Taken from the spec
-                // http://xmpp.org/rfcs/rfc3921.html#rfc.section.7.3
-                stanza = $iq({
-                    to: _converse.connection.jid,
-                    type: 'result',
-                    id: 'roster_1'
-                }).c('query', {
-                    xmlns: 'jabber:iq:roster',
-                }).c('item', {
-                    jid: 'romeo@example.net',
-                    name: 'Romeo',
-                    subscription:'both'
-                }).c('group').t('Friends').up().up()
-                .c('item', {
-                    jid: 'mercutio@example.org',
-                    name: 'Mercutio',
-                    subscription:'from'
-                }).c('group').t('Friends').up().up()
-                .c('item', {
-                    jid: 'benvolio@example.org',
-                    name: 'Benvolio',
-                    subscription:'both'
-                }).c('group').t('Friends');
-                _converse.roster.onReceivedFromServer(stanza.tree());
-                expect(_.includes(_converse.roster.pluck('jid'), 'data@enterprise')).toBeTruthy();
-                done();
+                test_utils.waitUntil(function () {
+                    return $('a:contains("Contact requests")').length;
+                }).then(function () {
+                    expect(_converse.roster.pluck('jid').length).toBe(1);
+                    expect(_.includes(_converse.roster.pluck('jid'), 'data@enterprise')).toBeTruthy();
+                    // Taken from the spec
+                    // http://xmpp.org/rfcs/rfc3921.html#rfc.section.7.3
+                    stanza = $iq({
+                        to: _converse.connection.jid,
+                        type: 'result',
+                        id: 'roster_1'
+                    }).c('query', {
+                        xmlns: 'jabber:iq:roster',
+                    }).c('item', {
+                        jid: 'romeo@example.net',
+                        name: 'Romeo',
+                        subscription:'both'
+                    }).c('group').t('Friends').up().up()
+                    .c('item', {
+                        jid: 'mercutio@example.org',
+                        name: 'Mercutio',
+                        subscription:'from'
+                    }).c('group').t('Friends').up().up()
+                    .c('item', {
+                        jid: 'benvolio@example.org',
+                        name: 'Benvolio',
+                        subscription:'both'
+                    }).c('group').t('Friends');
+                    _converse.roster.onReceivedFromServer(stanza.tree());
+                    expect(_.includes(_converse.roster.pluck('jid'), 'data@enterprise')).toBeTruthy();
+                    done();
+                });
             }));
         });
 

spec/protocol.js

@@ -64,7 +64,7 @@
                 spyOn(_converse.roster, "addAndSubscribe").and.callThrough();
                 spyOn(_converse.roster, "addContact").and.callThrough();
                 spyOn(_converse.roster, "sendContactAddIQ").and.callThrough();
-                spyOn(_converse, "getVCard").and.callThrough();
+                spyOn(_converse.api.vcard, "get").and.callThrough();
                 var sendIQ = _converse.connection.sendIQ;
                 spyOn(_converse.connection, 'sendIQ').and.callFake(function (iq, callback, errback) {
                     sent_stanza = iq;
@@ -172,7 +172,7 @@
                 // A contact should now have been created
                 expect(_converse.roster.get('contact@example.org') instanceof _converse.RosterContact).toBeTruthy();
                 expect(contact.get('jid')).toBe('contact@example.org');
-                expect(_converse.getVCard).toHaveBeenCalled();
+                expect(_converse.api.vcard.get).toHaveBeenCalled();
 
                 /* To subscribe to the contact's presence information,
                 * the user's client MUST send a presence stanza of
@@ -525,9 +525,9 @@
                 null, ['rosterGroupsFetched'], {},
                 function (done, _converse) {
 
+                spyOn(_converse, "emit");
                 test_utils.openControlBox(_converse);
                 test_utils.createContacts(_converse, 'current'); // Create some contacts so that we can test positioning
-                spyOn(_converse, "emit");
                 /* <presence
                  *     from='user@example.com'
                  *     to='contact@example.org'
@@ -541,10 +541,10 @@
                     'xmlns': Strophe.NS.NICK,
                 }).t('Clint Contact');
                 _converse.connection._dataRecv(test_utils.createRequest(stanza));
-                expect(_converse.emit).toHaveBeenCalledWith('contactRequest', jasmine.any(Object));
                 test_utils.waitUntil(function () {
                     return $('a:contains("Contact requests")').length;
                 }).then(function () {
+                    expect(_converse.emit).toHaveBeenCalledWith('contactRequest', jasmine.any(Object));
                     var $header = $('a:contains("Contact requests")');
                     expect($header.length).toBe(1);
                     expect($header.is(":visible")).toBeTruthy();