Commit 27557d6a authored by JC Brand's avatar JC Brand

Document `_converse.ChatBox.prototype.sendMessage` as an API method

Until now, we've only been explicitly documenting the `_converse.api`
namespace and only considered the methods under it as forming the API
contract (which determines how we do semver releases).

It appears as if we've reached a point where trying to keep everything
under the `_converse.api` namespace no longer makes sense. Certain
methods are applicable to particular models and trying to shoehorn them
into the `_converse.api` namespace seems clunky and non-intuitive.

I've therefore decided to slightly refactor `sendMessage` to let it take
two simple parameters and to document it with JSDoc so that it's
presented as an API method, albeit only available on a chat model.

updates #1496
updates #1504
parent 675692df
...@@ -11,6 +11,7 @@ ...@@ -11,6 +11,7 @@
- New config setting [locked_muc_domain](https://conversejs.org/docs/html/configuration.html#locked-muc-domain) - New config setting [locked_muc_domain](https://conversejs.org/docs/html/configuration.html#locked-muc-domain)
- New config setting [show_client_info](https://conversejs.org/docs/html/configuration.html#show-client-info) - New config setting [show_client_info](https://conversejs.org/docs/html/configuration.html#show-client-info)
- Render inline images served over HTTP if Converse itself was loaded on an unsecured (HTTP) page. - Render inline images served over HTTP if Converse itself was loaded on an unsecured (HTTP) page.
- Document new API method [sendMessage](https://conversejs.org/docs/html/api/-_converse.ChatBox.html#sendMessage)
- #1149: With `xhr_user_search_url`, contact requests are not being sent out - #1149: With `xhr_user_search_url`, contact requests are not being sent out
- #1213: Switch roster filter input and icons - #1213: Switch roster filter input and icons
- #1327: fix False mentions positives in URLs and Email addresses - #1327: fix False mentions positives in URLs and Email addresses
...@@ -24,7 +25,6 @@ ...@@ -24,7 +25,6 @@
- #1501: Don't prompt for a reason if [auto_join_on_invite](https://conversejs.org/docs/html/configuration.html#auto-join-on-invite) is `true` - #1501: Don't prompt for a reason if [auto_join_on_invite](https://conversejs.org/docs/html/configuration.html#auto-join-on-invite) is `true`
## 4.1.2 (2019-02-22) ## 4.1.2 (2019-02-22)
- Updated translations: af, cz, de, es, he, it, nl, nl_BE, pt_BR, zh_CN - Updated translations: af, cz, de, es, he, it, nl, nl_BE, pt_BR, zh_CN
......
...@@ -50312,7 +50312,7 @@ _converse_headless_converse_core__WEBPACK_IMPORTED_MODULE_5__["default"].plugins ...@@ -50312,7 +50312,7 @@ _converse_headless_converse_core__WEBPACK_IMPORTED_MODULE_5__["default"].plugins
_converse_headless_utils_emoji__WEBPACK_IMPORTED_MODULE_21__["default"].addClass('disabled', textarea); _converse_headless_utils_emoji__WEBPACK_IMPORTED_MODULE_21__["default"].addClass('disabled', textarea);
textarea.setAttribute('disabled', 'disabled'); textarea.setAttribute('disabled', 'disabled');
if (this.parseMessageForCommands(message) || (await this.model.sendMessage(this.model.getOutgoingMessageAttributes(message, spoiler_hint)))) { if (this.parseMessageForCommands(message) || (await this.model.sendMessage(message, spoiler_hint))) {
hint_el.value = ''; hint_el.value = '';
textarea.value = ''; textarea.value = '';
_converse_headless_utils_emoji__WEBPACK_IMPORTED_MODULE_21__["default"].removeClass('correcting', textarea); _converse_headless_utils_emoji__WEBPACK_IMPORTED_MODULE_21__["default"].removeClass('correcting', textarea);
...@@ -51598,6 +51598,8 @@ _converse_headless_converse_core__WEBPACK_IMPORTED_MODULE_5__["default"].plugins ...@@ -51598,6 +51598,8 @@ _converse_headless_converse_core__WEBPACK_IMPORTED_MODULE_5__["default"].plugins
/** /**
* Retrieves the controlbox view. * Retrieves the controlbox view.
* *
* @method _converse.api.controlbox.get
*
* @example * @example
* const view = _converse.api.controlbox.get(); * const view = _converse.api.controlbox.get();
* *
...@@ -56723,11 +56725,10 @@ _converse_headless_converse_core__WEBPACK_IMPORTED_MODULE_0__["default"].plugins ...@@ -56723,11 +56725,10 @@ _converse_headless_converse_core__WEBPACK_IMPORTED_MODULE_0__["default"].plugins
} }
}, },
async sendMessage(attrs) { async sendMessage(text, spoiler_hint) {
const _converse = this.__super__._converse, if (this.get('omemo_active') && text) {
__ = _converse.__; const _converse = this.__super__._converse;
const attrs = this.getOutgoingMessageAttributes(text, spoiler_hint);
if (this.get('omemo_active') && attrs.message) {
attrs['is_encrypted'] = true; attrs['is_encrypted'] = true;
attrs['plaintext'] = attrs.message; attrs['plaintext'] = attrs.message;
...@@ -62134,6 +62135,13 @@ _converse_core__WEBPACK_IMPORTED_MODULE_2__["default"].plugins.add('converse-cha ...@@ -62134,6 +62135,13 @@ _converse_core__WEBPACK_IMPORTED_MODULE_2__["default"].plugins.add('converse-cha
model: _converse.Message, model: _converse.Message,
comparator: 'time' comparator: 'time'
}); });
/**
* The "_converse.ChatBox" namespace
*
* @namespace _converse.ChatBox
* @memberOf _converse
*/
_converse.ChatBox = Backbone.Model.extend({ _converse.ChatBox = Backbone.Model.extend({
defaults() { defaults() {
return { return {
...@@ -62489,12 +62497,22 @@ _converse_core__WEBPACK_IMPORTED_MODULE_2__["default"].plugins.add('converse-cha ...@@ -62489,12 +62497,22 @@ _converse_core__WEBPACK_IMPORTED_MODULE_2__["default"].plugins.add('converse-cha
}); });
}, },
sendMessage(attrs) { /**
/* Responsible for sending off a text message. * Responsible for sending off a text message inside an ongoing
* chat conversation.
* *
* Parameters: * @method _converse.ChatBox#sendMessage
* (Message) message - The chat message * @memberOf _converse.ChatBox
*
* @param {String} text - The chat message text
* @param {String} spoiler_hint - An optional hint, if the message being sent is a spoiler
*
* @example
* const chat = _converse.api.chats.get('buddy1@example.com');
* chat.sendMessage('hello world');
*/ */
sendMessage(text, spoiler_hint) {
const attrs = this.getOutgoingMessageAttributes(text, spoiler_hint);
let message = this.messages.findWhere('correcting'); let message = this.messages.findWhere('correcting');
if (message) { if (message) {
...@@ -63130,7 +63148,7 @@ _converse_core__WEBPACK_IMPORTED_MODULE_2__["default"].plugins.add('converse-cha ...@@ -63130,7 +63148,7 @@ _converse_core__WEBPACK_IMPORTED_MODULE_2__["default"].plugins.add('converse-cha
* *
* @method _converse.api.chats.get * @method _converse.api.chats.get
* @param {String|string[]} name - e.g. 'buddy@example.com' or ['buddy1@example.com', 'buddy2@example.com'] * @param {String|string[]} name - e.g. 'buddy@example.com' or ['buddy1@example.com', 'buddy2@example.com']
* @returns {Backbone.Model} * @returns {_converse.ChatBox}
* *
* @example * @example
* // To return a single chat, provide the JID of the contact you're chatting with in that chat: * // To return a single chat, provide the JID of the contact you're chatting with in that chat:
...@@ -2495,23 +2495,12 @@ ...@@ -2495,23 +2495,12 @@
await test_utils.openAndEnterChatRoom(_converse, 'room', 'muc.example.com', 'dummy'); await test_utils.openAndEnterChatRoom(_converse, 'room', 'muc.example.com', 'dummy');
const view = _converse.chatboxviews.get('room@muc.example.com'); const view = _converse.chatboxviews.get('room@muc.example.com');
const attrs = { view.model.sendMessage('hello world');
'id': _converse.connection.getUniqueId(),
'origin_id': _converse.connection.getUniqueId(),
'fullname': 'dummy',
'references': [],
'from': _converse.connection.jid,
'sender': 'me',
'time': moment().format(),
'message': 'Hello world',
'is_spoiler': false,
'type': 'groupchat'
}
view.model.sendMessage(attrs);
await test_utils.waitUntil(() => _converse.api.chats.get().length); await test_utils.waitUntil(() => _converse.api.chats.get().length);
await test_utils.waitUntil(() => view.model.messages.length === 1); await test_utils.waitUntil(() => view.model.messages.length === 1);
expect(view.model.messages.at(0).get('stanza_id')).toBeUndefined(); const msg = view.model.messages.at(0);
expect(view.model.messages.at(0).get('origin_id')).toBe(attrs.origin_id); expect(msg.get('stanza_id')).toBeUndefined();
expect(msg.get('origin_id')).toBe(msg.get('origin_id'));
const stanza = u.toStanza(` const stanza = u.toStanza(`
<message xmlns="jabber:client" <message xmlns="jabber:client"
...@@ -2522,14 +2511,14 @@ ...@@ -2522,14 +2511,14 @@
<stanza-id xmlns="urn:xmpp:sid:0" <stanza-id xmlns="urn:xmpp:sid:0"
id="5f3dbc5e-e1d3-4077-a492-693f3769c7ad" id="5f3dbc5e-e1d3-4077-a492-693f3769c7ad"
by="room@muc.example.com"/> by="room@muc.example.com"/>
<origin-id xmlns="urn:xmpp:sid:0" id="${attrs.origin_id}"/> <origin-id xmlns="urn:xmpp:sid:0" id="${msg.get('origin_id')}"/>
</message>`); </message>`);
spyOn(view.model, 'updateMessage').and.callThrough(); spyOn(view.model, 'updateMessage').and.callThrough();
_converse.connection._dataRecv(test_utils.createRequest(stanza)); _converse.connection._dataRecv(test_utils.createRequest(stanza));
await test_utils.waitUntil(() => view.model.updateMessage.calls.count() === 1); await test_utils.waitUntil(() => view.model.updateMessage.calls.count() === 1);
expect(view.model.messages.length).toBe(1); expect(view.model.messages.length).toBe(1);
expect(view.model.messages.at(0).get('stanza_id room@muc.example.com')).toBe("5f3dbc5e-e1d3-4077-a492-693f3769c7ad"); expect(view.model.messages.at(0).get('stanza_id room@muc.example.com')).toBe("5f3dbc5e-e1d3-4077-a492-693f3769c7ad");
expect(view.model.messages.at(0).get('origin_id')).toBe(attrs.origin_id); expect(view.model.messages.at(0).get('origin_id')).toBe(msg.get('origin_id'));
done(); done();
})); }));
......
...@@ -872,7 +872,7 @@ converse.plugins.add('converse-chatview', { ...@@ -872,7 +872,7 @@ converse.plugins.add('converse-chatview', {
u.addClass('disabled', textarea); u.addClass('disabled', textarea);
textarea.setAttribute('disabled', 'disabled'); textarea.setAttribute('disabled', 'disabled');
if (this.parseMessageForCommands(message) || if (this.parseMessageForCommands(message) ||
await this.model.sendMessage(this.model.getOutgoingMessageAttributes(message, spoiler_hint))) { await this.model.sendMessage(message, spoiler_hint)) {
hint_el.value = ''; hint_el.value = '';
textarea.value = ''; textarea.value = '';
......
...@@ -664,6 +664,8 @@ converse.plugins.add('converse-controlbox', { ...@@ -664,6 +664,8 @@ converse.plugins.add('converse-controlbox', {
/** /**
* Retrieves the controlbox view. * Retrieves the controlbox view.
* *
* @method _converse.api.controlbox.get
*
* @example * @example
* const view = _converse.api.controlbox.get(); * const view = _converse.api.controlbox.get();
* *
......
...@@ -343,11 +343,10 @@ converse.plugins.add('converse-omemo', { ...@@ -343,11 +343,10 @@ converse.plugins.add('converse-omemo', {
} }
}, },
async sendMessage (attrs) { async sendMessage (text, spoiler_hint) {
const { _converse } = this.__super__, if (this.get('omemo_active') && text) {
{ __ } = _converse; const { _converse } = this.__super__;
const attrs = this.getOutgoingMessageAttributes(text, spoiler_hint);
if (this.get('omemo_active') && attrs.message) {
attrs['is_encrypted'] = true; attrs['is_encrypted'] = true;
attrs['plaintext'] = attrs.message; attrs['plaintext'] = attrs.message;
try { try {
......
...@@ -219,6 +219,12 @@ converse.plugins.add('converse-chatboxes', { ...@@ -219,6 +219,12 @@ converse.plugins.add('converse-chatboxes', {
}); });
/**
* The "_converse.ChatBox" namespace
*
* @namespace _converse.ChatBox
* @memberOf _converse
*/
_converse.ChatBox = Backbone.Model.extend({ _converse.ChatBox = Backbone.Model.extend({
defaults () { defaults () {
return { return {
...@@ -506,12 +512,22 @@ converse.plugins.add('converse-chatboxes', { ...@@ -506,12 +512,22 @@ converse.plugins.add('converse-chatboxes', {
}); });
}, },
sendMessage (attrs) { /**
/* Responsible for sending off a text message. * Responsible for sending off a text message inside an ongoing
* chat conversation.
* *
* Parameters: * @method _converse.ChatBox#sendMessage
* (Message) message - The chat message * @memberOf _converse.ChatBox
*
* @param {String} text - The chat message text
* @param {String} spoiler_hint - An optional hint, if the message being sent is a spoiler
*
* @example
* const chat = _converse.api.chats.get('buddy1@example.com');
* chat.sendMessage('hello world');
*/ */
sendMessage (text, spoiler_hint) {
const attrs = this.getOutgoingMessageAttributes(text, spoiler_hint);
let message = this.messages.findWhere('correcting') let message = this.messages.findWhere('correcting')
if (message) { if (message) {
const older_versions = message.get('older_versions') || []; const older_versions = message.get('older_versions') || [];
...@@ -1097,7 +1113,7 @@ converse.plugins.add('converse-chatboxes', { ...@@ -1097,7 +1113,7 @@ converse.plugins.add('converse-chatboxes', {
* *
* @method _converse.api.chats.get * @method _converse.api.chats.get
* @param {String|string[]} name - e.g. 'buddy@example.com' or ['buddy1@example.com', 'buddy2@example.com'] * @param {String|string[]} name - e.g. 'buddy@example.com' or ['buddy1@example.com', 'buddy2@example.com']
* @returns {Backbone.Model} * @returns {_converse.ChatBox}
* *
* @example * @example
* // To return a single chat, provide the JID of the contact you're chatting with in that chat: * // To return a single chat, provide the JID of the contact you're chatting with in that chat:
......
...@@ -40407,6 +40407,13 @@ _converse_core__WEBPACK_IMPORTED_MODULE_2__["default"].plugins.add('converse-cha ...@@ -40407,6 +40407,13 @@ _converse_core__WEBPACK_IMPORTED_MODULE_2__["default"].plugins.add('converse-cha
model: _converse.Message, model: _converse.Message,
comparator: 'time' comparator: 'time'
}); });
/**
* The "_converse.ChatBox" namespace
*
* @namespace _converse.ChatBox
* @memberOf _converse
*/
_converse.ChatBox = Backbone.Model.extend({ _converse.ChatBox = Backbone.Model.extend({
defaults() { defaults() {
return { return {
...@@ -40762,12 +40769,22 @@ _converse_core__WEBPACK_IMPORTED_MODULE_2__["default"].plugins.add('converse-cha ...@@ -40762,12 +40769,22 @@ _converse_core__WEBPACK_IMPORTED_MODULE_2__["default"].plugins.add('converse-cha
}); });
}, },
sendMessage(attrs) { /**
/* Responsible for sending off a text message. * Responsible for sending off a text message inside an ongoing
* chat conversation.
* *
* Parameters: * @method _converse.ChatBox#sendMessage
* (Message) message - The chat message * @memberOf _converse.ChatBox
*
* @param {String} text - The chat message text
* @param {String} spoiler_hint - An optional hint, if the message being sent is a spoiler
*
* @example
* const chat = _converse.api.chats.get('buddy1@example.com');
* chat.sendMessage('hello world');
*/ */
sendMessage(text, spoiler_hint) {
const attrs = this.getOutgoingMessageAttributes(text, spoiler_hint);
let message = this.messages.findWhere('correcting'); let message = this.messages.findWhere('correcting');
if (message) { if (message) {
...@@ -41403,7 +41420,7 @@ _converse_core__WEBPACK_IMPORTED_MODULE_2__["default"].plugins.add('converse-cha ...@@ -41403,7 +41420,7 @@ _converse_core__WEBPACK_IMPORTED_MODULE_2__["default"].plugins.add('converse-cha
* *
* @method _converse.api.chats.get * @method _converse.api.chats.get
* @param {String|string[]} name - e.g. 'buddy@example.com' or ['buddy1@example.com', 'buddy2@example.com'] * @param {String|string[]} name - e.g. 'buddy@example.com' or ['buddy1@example.com', 'buddy2@example.com']
* @returns {Backbone.Model} * @returns {_converse.ChatBox}
* *
* @example * @example
* // To return a single chat, provide the JID of the contact you're chatting with in that chat: * // To return a single chat, provide the JID of the contact you're chatting with in that chat:
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment