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 @@
- 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)
- 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
- #1213: Switch roster filter input and icons
- #1327: fix False mentions positives in URLs and Email addresses
......@@ -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`
## 4.1.2 (2019-02-22)
- 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
_converse_headless_utils_emoji__WEBPACK_IMPORTED_MODULE_21__["default"].addClass('disabled', textarea);
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 = '';
textarea.value = '';
_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
/**
* Retrieves the controlbox view.
*
* @method _converse.api.controlbox.get
*
* @example
* const view = _converse.api.controlbox.get();
*
......@@ -56723,11 +56725,10 @@ _converse_headless_converse_core__WEBPACK_IMPORTED_MODULE_0__["default"].plugins
}
},
async sendMessage(attrs) {
const _converse = this.__super__._converse,
__ = _converse.__;
if (this.get('omemo_active') && attrs.message) {
async sendMessage(text, spoiler_hint) {
if (this.get('omemo_active') && text) {
const _converse = this.__super__._converse;
const attrs = this.getOutgoingMessageAttributes(text, spoiler_hint);
attrs['is_encrypted'] = true;
attrs['plaintext'] = attrs.message;
......@@ -62134,6 +62135,13 @@ _converse_core__WEBPACK_IMPORTED_MODULE_2__["default"].plugins.add('converse-cha
model: _converse.Message,
comparator: 'time'
});
/**
* The "_converse.ChatBox" namespace
*
* @namespace _converse.ChatBox
* @memberOf _converse
*/
_converse.ChatBox = Backbone.Model.extend({
defaults() {
return {
......@@ -62489,12 +62497,22 @@ _converse_core__WEBPACK_IMPORTED_MODULE_2__["default"].plugins.add('converse-cha
});
},
sendMessage(attrs) {
/* Responsible for sending off a text message.
*
* Parameters:
* (Message) message - The chat message
*/
/**
* Responsible for sending off a text message inside an ongoing
* chat conversation.
*
* @method _converse.ChatBox#sendMessage
* @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');
if (message) {
......@@ -63130,7 +63148,7 @@ _converse_core__WEBPACK_IMPORTED_MODULE_2__["default"].plugins.add('converse-cha
*
* @method _converse.api.chats.get
* @param {String|string[]} name - e.g. 'buddy@example.com' or ['buddy1@example.com', 'buddy2@example.com']
* @returns {Backbone.Model}
* @returns {_converse.ChatBox}
*
* @example
* // To return a single chat, provide the JID of the contact you're chatting with in that chat:
......@@ -2495,23 +2495,12 @@
await test_utils.openAndEnterChatRoom(_converse, 'room', 'muc.example.com', 'dummy');
const view = _converse.chatboxviews.get('room@muc.example.com');
const attrs = {
'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);
view.model.sendMessage('hello world');
await test_utils.waitUntil(() => _converse.api.chats.get().length);
await test_utils.waitUntil(() => view.model.messages.length === 1);
expect(view.model.messages.at(0).get('stanza_id')).toBeUndefined();
expect(view.model.messages.at(0).get('origin_id')).toBe(attrs.origin_id);
const msg = view.model.messages.at(0);
expect(msg.get('stanza_id')).toBeUndefined();
expect(msg.get('origin_id')).toBe(msg.get('origin_id'));
const stanza = u.toStanza(`
<message xmlns="jabber:client"
......@@ -2522,14 +2511,14 @@
<stanza-id xmlns="urn:xmpp:sid:0"
id="5f3dbc5e-e1d3-4077-a492-693f3769c7ad"
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>`);
spyOn(view.model, 'updateMessage').and.callThrough();
_converse.connection._dataRecv(test_utils.createRequest(stanza));
await test_utils.waitUntil(() => view.model.updateMessage.calls.count() === 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('origin_id')).toBe(attrs.origin_id);
expect(view.model.messages.at(0).get('origin_id')).toBe(msg.get('origin_id'));
done();
}));
......
......@@ -872,7 +872,7 @@ converse.plugins.add('converse-chatview', {
u.addClass('disabled', textarea);
textarea.setAttribute('disabled', 'disabled');
if (this.parseMessageForCommands(message) ||
await this.model.sendMessage(this.model.getOutgoingMessageAttributes(message, spoiler_hint))) {
await this.model.sendMessage(message, spoiler_hint)) {
hint_el.value = '';
textarea.value = '';
......
......@@ -664,6 +664,8 @@ converse.plugins.add('converse-controlbox', {
/**
* Retrieves the controlbox view.
*
* @method _converse.api.controlbox.get
*
* @example
* const view = _converse.api.controlbox.get();
*
......
......@@ -343,11 +343,10 @@ converse.plugins.add('converse-omemo', {
}
},
async sendMessage (attrs) {
const { _converse } = this.__super__,
{ __ } = _converse;
if (this.get('omemo_active') && attrs.message) {
async sendMessage (text, spoiler_hint) {
if (this.get('omemo_active') && text) {
const { _converse } = this.__super__;
const attrs = this.getOutgoingMessageAttributes(text, spoiler_hint);
attrs['is_encrypted'] = true;
attrs['plaintext'] = attrs.message;
try {
......
......@@ -219,6 +219,12 @@ converse.plugins.add('converse-chatboxes', {
});
/**
* The "_converse.ChatBox" namespace
*
* @namespace _converse.ChatBox
* @memberOf _converse
*/
_converse.ChatBox = Backbone.Model.extend({
defaults () {
return {
......@@ -506,12 +512,22 @@ converse.plugins.add('converse-chatboxes', {
});
},
sendMessage (attrs) {
/* Responsible for sending off a text message.
*
* Parameters:
* (Message) message - The chat message
*/
/**
* Responsible for sending off a text message inside an ongoing
* chat conversation.
*
* @method _converse.ChatBox#sendMessage
* @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')
if (message) {
const older_versions = message.get('older_versions') || [];
......@@ -1097,7 +1113,7 @@ converse.plugins.add('converse-chatboxes', {
*
* @method _converse.api.chats.get
* @param {String|string[]} name - e.g. 'buddy@example.com' or ['buddy1@example.com', 'buddy2@example.com']
* @returns {Backbone.Model}
* @returns {_converse.ChatBox}
*
* @example
* // 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
model: _converse.Message,
comparator: 'time'
});
/**
* The "_converse.ChatBox" namespace
*
* @namespace _converse.ChatBox
* @memberOf _converse
*/
_converse.ChatBox = Backbone.Model.extend({
defaults() {
return {
......@@ -40762,12 +40769,22 @@ _converse_core__WEBPACK_IMPORTED_MODULE_2__["default"].plugins.add('converse-cha
});
},
sendMessage(attrs) {
/* Responsible for sending off a text message.
*
* Parameters:
* (Message) message - The chat message
*/
/**
* Responsible for sending off a text message inside an ongoing
* chat conversation.
*
* @method _converse.ChatBox#sendMessage
* @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');
if (message) {
......@@ -41403,7 +41420,7 @@ _converse_core__WEBPACK_IMPORTED_MODULE_2__["default"].plugins.add('converse-cha
*
* @method _converse.api.chats.get
* @param {String|string[]} name - e.g. 'buddy@example.com' or ['buddy1@example.com', 'buddy2@example.com']
* @returns {Backbone.Model}
* @returns {_converse.ChatBox}
*
* @example
* // 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