Update `vcard.get` API method to accept either a JID string or a model

CHANGES.md

@@ -1,25 +1,25 @@
 # Changelog
 
-## Http-File-Upload
+## 4.0.0 (Unreleased)
 
 ## New Features
 
-- Support for rendering URLs sent according to XEP-0066 Out of Band Data.
-- MP4 and MP3 files when sent as XEP-0066 Out of Band Data, are now playable directly in chat
-- Automatically grow/shrink input as text is entered/removed
 - #161 XEP-0363: HTTP File Upload
+- Automatically grow/shrink input as text is entered/removed
+- MP4 and MP3 files when sent as XEP-0066 Out of Band Data, are now playable directly in chat
+- Support for rendering URLs sent according to XEP-0066 Out of Band Data.
+- Geo-URIs (e.g. from Conversations) are now replaced by links to openstreetmap (works in reverse also)
 
-## 4.0.0 (Unreleased)
+### API changes
+- `_converse.api.vcard.get` now also accepts a `Backbone.Model` instance and
+  has an additional `force` parameter to force fetching the vcard even if it
+  has already been fetched.
 
 ## UI changes
 
 - The UI is now based on Bootstrap4 and Flexbox is used extensively.
 - #956 Conversation pane should show my own identity in pane header 
 
-## New Features
-
-- geo-URIs (e.g. from Conversations) are now replaced by links to openstreetmap (works in reverse also)
-
 ## Configuration changes 
 
 - Removed the `xhr_custom_status` and `xhr_custom_status_url` configuration
@@ -94,7 +94,7 @@
     - Maintain MUC session upon page reload
 
 ### API changes
-- New API method `_converse.disco.getIdentity` to check whether a JID has a given identity.
+- New API method `_converse.api.disco.getIdentity` to check whether a JID has a given identity.
 
 ### Configuration settings
 - `auto_reconnect` is now set to `true` by default.

docs/source/developer_api.rst

@@ -1262,7 +1262,18 @@ The **vcard** grouping
 get
 ~~~
 
-Returns a Promise which results with the VCard data for a particular JID.
+Parameters:
+
+* ``model`` either a `Backbone.Model` instance, or a string JID.
+* ``force`` (optional), a boolean indicating whether the vcard should be
+  fetched even if it's been fetched before.
+
+Returns a Promise which results with the VCard data for a particular JID or for
+a `Backbone.Model` instance which represents an entity with a JID (such as a roster contact,
+chatbox or chatroom occupant).
+
+If a `Backbone.Model` instance is passed in, then it must have either a `jid`
+attribute or a `muc_jid` attribute.
 
 Example:
 

src/converse-vcard.js

@@ -175,29 +175,33 @@
             });
 
             _converse.on('initialized', () => {
-                _converse.roster.on("add", (contact) => {
-                    if (!contact.get('vcard_updated')) {
-                        _converse.api.vcard.get(contact.get('jid'));
-                    }
-                });
+                _converse.roster.on("add", (contact) => _converse.api.vcard.get(contact));
             });
 
             _converse.on('statusInitialized', function fetchOwnVCard () {
-                if (_.isNil(_converse.xmppstatus.get('vcard_updated'))) {
-                    _converse.api.disco.supports(Strophe.NS.VCARD, _converse.domain)
-                        .then((result) => {
-                            if (result.length) {
-                                _converse.api.vcard.get(_converse.bare_jid)
-                                    .then((vcard) => _converse.xmppstatus.save(vcard));
-                            }})
-                        .catch(_.partial(_converse.log, _, Strophe.LogLevel.FATAL));
-                }
+                _converse.api.disco.supports(Strophe.NS.VCARD, _converse.domain)
+                    .then((result) => {
+                        if (result.length) {
+                            _converse.api.vcard.get(_converse.xmppstatus)
+                                .then((vcard) => _converse.xmppstatus.save(vcard));
+                        }})
+                    .catch(_.partial(_converse.log, _, Strophe.LogLevel.FATAL));
             });
 
             _.extend(_converse.api, {
                 'vcard': {
-                    'get' (jid) {
-                        return getVCard(_converse, jid);
+                    'get' (model, force) {
+                        if (_.isString(model)) {
+                            return getVCard(_converse, model);
+                        } else if (!model.get('vcard_updated') || force) {
+                            const jid = model.get('jid') || model.get('muc_jid');
+                            if (!jid) {
+                                throw new Error("No JID to get vcard for!");
+                            }
+                            return getVCard(_converse, jid);
+                        } else {
+                            return {};
+                        }
                     }
                 }
             });