Skip to content

C
converse.js
Commit a45bd8d1 authored by JC Brand's avatar JC Brand
Browse files
Options

Convert older docstrings to JSDoc syntax

parent 7ed99092
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 1918 additions and 1734 deletions
Makefile
View file @ a45bd8d1
......@@ -261,4 +261,4 @@ html: dev docsdev apidoc
PHONY: apidoc
apidoc:
$(JSDOC) --readme docs/source/jsdoc_intro.md -c docs/source/conf.json -d docs/html/api src/*.js src/utils/*.js src/headless/*.js src/headless/utils/*.js
$(JSDOC) --private --readme docs/source/jsdoc_intro.md -c docs/source/conf.json -d docs/html/api src/*.js src/utils/*.js src/headless/*.js src/headless/utils/*.js
dist/converse.js
View file @ a45bd8d1
This diff is collapsed.
docs/source/development.rst
View file @ a45bd8d1
......@@ -41,6 +41,5 @@ to fix a bug or to add new functionality.
plugin_development
api/index
testing
events
other_frameworks
builds
docs/source/jsdoc_intro.md
View file @ a45bd8d1
......@@ -3,29 +3,31 @@
Welcome to the new Converse API documentation, generated with
[JSDoc](http://usejsdoc.org/).
The old (increasingly out of date and incomplete) API documentation is
currently still [available here](/docs/html/developer_api.html).
This documentation replaces the (increasingly out of date and incomplete) [old API documentation](/docs/html/developer_api.html)
and [old "Events and Promises" documentation](/docs/html/events.html).
## The public and private API
Converse has a public API and a private API.
r
Converse has a public API and a private API only available to plugins.
The reason we make this distinction between public and private is so that API
methods which might can be used to "impersonate" the user, for example by
methods which could be used to "impersonate" the user, for example by
sending messages on their behalf, are not available to random scripts running
in the websites.
in your website.
The public API is accessible via the [window.converse](/docs/html/api/converse.html)
global and is therefore available to any JavaScript running in the page.
The public API is accessible via the `window.converse` global and is therefore
available to all JavaScript running in the page.
The private API is only accessible to plugins, which have been whitelisted and
registered before [converse.initialize](/docs/html/api/converse.html#.initialize)
(which is a public API method) has been called.
Tehe private API is only accessible to plugins, which have been whitelisted and
registered before `converse.initialize` (which is a public API method) has been
called. See the [plugin development](https://conversejs.org/docs/html/plugin_development.html)
See the [plugin development](/docs/html/plugin_development.html)
section for more info on writing plugins.
Inside a plugin, you can get access to the `_converse.api` object. Note the
underscore in front of `_converse`, which indicates that this is a private,
closured object.
Inside a plugin, you can get access to the {@link _converse.api}
object. Note the underscore in front of {@link _converse},
which indicates that this is a private, closured object.
## API Namespaces
......@@ -35,9 +37,26 @@ group relevant methods.
So, for example, all the XEP-0030 service discovery methods are under the
{@link \_converse.api.disco} namespace, in the [private API]{@link \_converse.api}.
Which means that you access it via `_converse.api.disco`.
Which means that you access it via {@link _converse.api.disco}.
### Nested Namespaces
Namespaces can be nested.
Namespaces can be nested. So the {@link \_converse.api.disco} namespace
namespace has {@link \_converse.api.disco.own} as a nested namespace.
{@link _converse.api} is the top-level namespace, of which {@link \_converse.api.disco}
is a nested, child namespace and {@link \_converse.api.disco.own} is nested another
level deeper.
Not all methods are however within a namespace. For example {@link converse.initialize}.
## Stable API versus unstable API
Converse uses [semantic versioning](https://semver.org/) for releases, which means that
we try to maintain a stable API for minor and patch releases and when we do change the
stable API we will make a major release.
In the JSDoc API documentation, all API methods that are **not** marked as *Private*
are considered to be part of the stable API, and you can therefore expect them to
not change between minor and patch releases. If a method is marked as *Private*,
then you could still use it, but we don't provide any guarantee that it won't change
between minor and patch releases.
src/converse-chatview.js
View file @ a45bd8d1
......@@ -586,18 +586,18 @@ converse.plugins.add('converse-chatview', {
);
},
/**
* Inserts an indicator into the chat area, showing the
* day as given by the passed in date.
* The indicator is only inserted if necessary.
* @private
* @method _converse.ChatBoxView#insertDayIndicator
* @param { HTMLElement } next_msg_el - The message element before
* which the day indicator element must be inserted.
* This element must have a "data-isodate" attribute
* which specifies its creation date.
*/
insertDayIndicator (next_msg_el) {
/* Inserts an indicator into the chat area, showing the
* day as given by the passed in date.
*
* The indicator is only inserted if necessary.
*
* Parameters:
* (HTMLElement) next_msg_el - The message element before
* which the day indicator element must be inserted.
* This element must have a "data-isodate" attribute
* which specifies its creation date.
*/
const prev_msg_el = u.getPreviousElement(next_msg_el, ".message:not(.chat-state-notification)"),
prev_msg_date = _.isNull(prev_msg_el) ? null : prev_msg_el.getAttribute('data-isodate'),
next_msg_date = next_msg_el.getAttribute('data-isodate');
......@@ -616,13 +616,14 @@ converse.plugins.add('converse-chatview', {
}
},
/**
* Return the ISO8601 format date of the latest message.
* @private
* @method _converse.ChatBoxView#getLastMessageDate
* @param { object } cutoff - Moment Date cutoff date. The last
* message received cutoff this date will be returned.
*/
getLastMessageDate (cutoff) {
/* Return the ISO8601 format date of the latest message.
*
* Parameters:
* (Object) cutoff: Moment Date cutoff date. The last
* message received cutoff this date will be returned.
*/
const first_msg = u.getFirstChildElement(this.content, '.message:not(.chat-state-notification)'),
oldest_date = first_msg ? first_msg.getAttribute('data-isodate') : null;
if (!_.isNull(oldest_date) && moment(oldest_date).isAfter(cutoff)) {
......@@ -713,13 +714,14 @@ converse.plugins.add('converse-chatview', {
return !u.isVisible(this.el);
},
/**
* Given a view representing a message, insert it into the
* content area of the chat box.
* @private
* @method _converse.ChatBoxView#insertMessage
* @param { Backbone.View } message - The message Backbone.View
*/
insertMessage (view) {
/* Given a view representing a message, insert it into the
* content area of the chat box.
*
* Parameters:
* (Backbone.View) message: The message Backbone.View
*/
if (view.model.get('type') === 'error') {
const previous_msg_el = this.content.querySelector(`[data-msgid="${view.model.get('msgid')}"]`);
if (previous_msg_el) {
......@@ -746,20 +748,22 @@ converse.plugins.add('converse-chatview', {
return this.trigger('messageInserted', view.el);
},
/**
* Given a message element, determine wether it should be
* marked as a followup message to the previous element.
*
* Also determine whether the element following it is a
* followup message or not.
*
* Followup messages are subsequent ones written by the same
* author with no other conversation elements inbetween and
* posted within 10 minutes of one another.
*
* @private
* @method _converse.ChatBoxView#markFollowups
* @param { HTMLElement } el - The message element
*/
markFollowups (el) {
/* Given a message element, determine wether it should be
* marked as a followup message to the previous element.
*
* Also determine whether the element following it is a
* followup message or not.
*
* Followup messages are subsequent ones written by the same
* author with no other conversation elements inbetween and
* posted within 10 minutes of one another.
*
* Parameters:
* (HTMLElement) el - The message element.
*/
const from = el.getAttribute('data-from'),
previous_el = el.previousElementSibling,
date = moment(el.getAttribute('data-isodate')),
......@@ -783,15 +787,14 @@ converse.plugins.add('converse-chatview', {
}
},
/**
* Inserts a chat message into the content area of the chat box.
* Will also insert a new day indicator if the message is on a different day.
* @private
* @method _converse.ChatBoxView#showMessage
* @param { _converse.Message } message - The message object
*/
async showMessage (message) {
/* Inserts a chat message into the content area of the chat box.
*
* Will also insert a new day indicator if the message is on a
* different day.
*
* Parameters:
* (Backbone.Model) message: The message object
*/
if (!u.isNewMessage(message) && u.isEmptyMessage(message)) {
// Handle archived or delayed messages without any message
// text to show.
......@@ -822,12 +825,13 @@ converse.plugins.add('converse-chatview', {
}
},
/**
* Handler that gets called when a new message object is created.
* @private
* @method _converse.ChatBoxView#onMessageAdded
* @param { object } message - The message Backbone object that was added.
*/
onMessageAdded (message) {
/* Handler that gets called when a new message object is created.
*
* Parameters:
* (Object) message - The message Backbone object that was added.
*/
this.showMessage(message);
if (message.get('correcting')) {
this.insertIntoTextArea(message.get('message'), true, true);
......@@ -865,17 +869,18 @@ converse.plugins.add('converse-chatview', {
}
},
/**
* Mutator for setting the chat state of this chat session.
* Handles clearing of any chat state notification timeouts and
* setting new ones if necessary.
* Timeouts are set when the state being set is COMPOSING or PAUSED.
* After the timeout, COMPOSING will become PAUSED and PAUSED will become INACTIVE.
* See XEP-0085 Chat State Notifications.
* @private
* @method _converse.ChatBoxView#setChatState
* @param { string } state - The chat state (consts ACTIVE, COMPOSING, PAUSED, INACTIVE, GONE)
*/
setChatState (state, options) {
/* Mutator for setting the chat state of this chat session.
* Handles clearing of any chat state notification timeouts and
* setting new ones if necessary.
* Timeouts are set when the state being set is COMPOSING or PAUSED.
* After the timeout, COMPOSING will become PAUSED and PAUSED will become INACTIVE.
* See XEP-0085 Chat State Notifications.
*
* Parameters:
* (string) state - The chat state (consts ACTIVE, COMPOSING, PAUSED, INACTIVE, GONE)
*/
if (!_.isUndefined(this.chat_state_timeout)) {
window.clearTimeout(this.chat_state_timeout);
delete this.chat_state_timeout;
......
src/converse-controlbox.js
View file @ a45bd8d1
......@@ -378,11 +378,6 @@ converse.plugins.add('converse-controlbox', {
},
showHelpMessages () {
/* Override showHelpMessages in ChatBoxView, for now do nothing.
*
* Parameters:
* (Array) msgs: Array of messages
*/
return;
}
});
......
src/converse-muc-views.js
View file @ a45bd8d1
......@@ -203,15 +203,12 @@ converse.plugins.add('converse-muc-views', {
};
/* Insert groupchat info (based on returned #disco IQ stanza)
* @function insertRoomInfo
* @param { HTMLElement } el - The HTML DOM element that contains the info.
* @param { XMLElement } stanza - The IQ stanza containing the groupchat info.
*/
function insertRoomInfo (el, stanza) {
/* Insert groupchat info (based on returned #disco IQ stanza)
*
* Parameters:
* (HTMLElement) el: The HTML DOM element that should
* contain the info.
* (XMLElement) stanza: The IQ stanza containing the groupchat
* info.
*/
// All MUC features found here: https://xmpp.org/registrar/disco-features.html
el.querySelector('span.spinner').remove();
el.querySelector('a.room-info').classList.add('selected');
......@@ -1110,12 +1107,13 @@ converse.plugins.add('converse-muc-views', {
this.model.addHandler('message', 'ChatRoomView.showStatusMessages', this.showStatusMessages.bind(this));
},
/**
* Handles all MUC presence stanzas.
* @private
* @method _converse.ChatRoomView#onPresence
* @param { XMLElement } pres - The stanza
*/
onPresence (pres) {
/* Handles all MUC presence stanzas.
*
* Parameters:
* (XMLElement) pres: The stanza
*/
// XXX: Current thinking is that excessive stanza
// processing inside a view is a "code smell".
// Instead stanza processing should happen inside the
......@@ -1138,14 +1136,14 @@ converse.plugins.add('converse-muc-views', {
this.fetchMessages();
},
/**
* Join the groupchat.
* @private
* @method _converse.ChatRoomView#join
* @param { String } nick - The user's nickname
* @param { String } password - Optional password, if required by the groupchat
*/
join (nick, password) {
/* Join the groupchat.
*
* Parameters:
* (String) nick: The user's nickname
* (String) password: Optional password, if required by
* the groupchat.
*/
if (!nick && !this.model.get('nick')) {
this.checkForReservedNick();
return this;
......@@ -1154,17 +1152,16 @@ converse.plugins.add('converse-muc-views', {
return this;
},
/**
* Renders a form given an IQ stanza containing the current
* groupchat configuration.
* Returns a promise which resolves once the user has
* either submitted the form, or canceled it.
* @private
* @method _converse.ChatRoomView#renderConfigurationForm
* @param { XMLElement } stanza: The IQ stanza containing the groupchat config.
*/
renderConfigurationForm (stanza) {
/* Renders a form given an IQ stanza containing the current
* groupchat configuration.
*
* Returns a promise which resolves once the user has
* either submitted the form, or canceled it.
*
* Parameters:
* (XMLElement) stanza: The IQ stanza containing the groupchat
* config.
*/
const container_el = this.el.querySelector('.chatroom-body');
_.each(container_el.querySelectorAll('.chatroom-form-container'), u.removeElement);
_.each(container_el.children, u.hideElement);
......@@ -1420,13 +1417,14 @@ converse.plugins.add('converse-muc-views', {
u.showElement(container);
},
/**
* @private
* @method _converse.ChatRoomView#getMessageFromStatus
* @param { XMLElement } stat: A <status> element
* @param { Boolean } is_self: Whether the element refers to the current user
* @param { XMLElement } stanza: The original stanza received
*/
getMessageFromStatus (stat, stanza, is_self) {
/* Parameters:
* (XMLElement) stat: A <status> element.
* (Boolean) is_self: Whether the element refers to the
* current user.
* (XMLElement) stanza: The original stanza received.
*/
const code = stat.getAttribute('code');
if (code === '110' || (code === '100' && !is_self)) { return; }
if (code in _converse.muc.info_messages) {
......@@ -1697,14 +1695,14 @@ converse.plugins.add('converse-muc-views', {
this.scrollDown();
},
/**
* Check for status codes and communicate their purpose to the user.
* See: https://xmpp.org/registrar/mucstatus.html
* @private
* @method _converse.ChatRoomView#showStatusMessages
* @param { XMLElement } stanza - The message or presence stanza containing the status codes
*/
showStatusMessages (stanza) {
/* Check for status codes and communicate their purpose to the user.
* See: https://xmpp.org/registrar/mucstatus.html
*
* Parameters:
* (XMLElement) stanza: The message or presence stanza
* containing the status codes.
*/
const elements = sizzle(`x[xmlns="${Strophe.NS.MUC_USER}"]`, stanza);
const is_self = stanza.querySelectorAll("status[code='110']").length;
const iteratee = _.partial(this.parseXUserElement.bind(this), _, stanza, is_self);
......
src/converse-register.js
View file @ a45bd8d1
This diff is collapsed.
src/headless/converse-chatboxes.js
View file @ a45bd8d1
......@@ -442,13 +442,13 @@ converse.plugins.add('converse-chatboxes', {
return false;
},
/**
* Given a {@link _converse.Message} return the XML stanza that represents it.
* @private
* @method _converse.ChatBox#createMessageStanza
* @param { _converse.Message } message - The message object
*/
createMessageStanza (message) {
/* Given a _converse.Message Backbone.Model, return the XML
* stanza that represents it.
*
* Parameters:
* (Object) message - The Backbone.Model representing the message
*/
const stanza = $msg({
'from': _converse.connection.jid,
'to': this.get('jid'),
......@@ -630,13 +630,14 @@ converse.plugins.add('converse-chatboxes', {
});
},
/**
* Extract the XEP-0359 stanza IDs from the passed in stanza
* and return a map containing them.
* @private
* @method _converse.ChatBox#getStanzaIDs
* @param { XMLElement } stanza - The message stanza
*/
getStanzaIDs (stanza) {
/* Extract the XEP-0359 stanza IDs from the passed in stanza
* and return a map containing them.
*
* Parameters:
* (XMLElement) stanza - The message stanza
*/
const attrs = {};
const stanza_ids = sizzle(`stanza-id[xmlns="${Strophe.NS.SID}"]`, stanza);
if (stanza_ids.length) {
......@@ -659,18 +660,17 @@ converse.plugins.add('converse-chatboxes', {
return !_.isNil(sizzle(`result[xmlns="${Strophe.NS.MAM}"]`, original_stanza).pop());
},
/**
* Parses a passed in message stanza and returns an object
* of attributes.
* @private
* @method _converse.ChatBox#getMessageAttributesFromStanza
* @param { XMLElement } stanza - The message stanza
* @param { XMLElement } delay - The <delay> node from the stanza, if there was one.
* @param { XMLElement } original_stanza - The original stanza, that contains the
* message stanza, if it was contained, otherwise it's the message stanza itself.
*/
getMessageAttributesFromStanza (stanza, original_stanza) {
/* Parses a passed in message stanza and returns an object
* of attributes.
*
* Parameters:
* (XMLElement) stanza - The message stanza
* (XMLElement) delay - The <delay> node from the
* stanza, if there was one.
* (XMLElement) original_stanza - The original stanza,
* that contains the message stanza, if it was
* contained, otherwise it's the message stanza itself.
*/
const spoiler = sizzle(`spoiler[xmlns="${Strophe.NS.SPOILER}"]`, original_stanza).pop(),
delay = sizzle(`delay[xmlns="${Strophe.NS.DELAY}"]`, original_stanza).pop(),
text = _converse.chatboxes.getMessageBody(stanza) || undefined,
......@@ -864,13 +864,13 @@ converse.plugins.add('converse-chatboxes', {
}
},
/**
* Handler method for all incoming single-user chat "message" stanzas.
* @private
* @method _converse.ChatBox#onMessage
* @param { XMLElement } stanza - The incoming message stanza
*/
async onMessage (stanza) {
/* Handler method for all incoming single-user chat "message"
* stanzas.
*
* Parameters:
* (XMLElement) stanza - The incoming message stanza
*/
let to_jid = stanza.getAttribute('to');
const to_resource = Strophe.getResourceFromJid(to_jid);
......@@ -970,15 +970,16 @@ converse.plugins.add('converse-chatboxes', {
_converse.api.trigger('message', {'stanza': original_stanza, 'chatbox': chatbox});
},
/**
* Returns a chat box or optionally return a newly
* created one if one doesn't exist.
* @private
* @method _converse.ChatBox#getChatBox
* @param { string } jid - The JID of the user whose chat box we want
* @param { boolean } create - Should a new chat box be created if none exists?
* @param { object } attrs - Optional chat box atributes.
*/
getChatBox (jid, attrs={}, create) {
/* Returns a chat box or optionally return a newly
* created one if one doesn't exist.
*
* Parameters:
* (String) jid - The JID of the user whose chat box we want
* (Boolean) create - Should a new chat box be created if none exists?
* (Object) attrs - Optional chat box atributes.
*/
if (_.isObject(jid)) {
create = attrs;
attrs = jid;
......
src/headless/converse-core.js
View file @ a45bd8d1
......@@ -225,20 +225,19 @@ _converse.default_settings = {
};
/**
* Logs messages to the browser's developer console.
* Available loglevels are 0 for 'debug', 1 for 'info', 2 for 'warn',
* 3 for 'error' and 4 for 'fatal'.
* When using the 'error' or 'warn' loglevels, a full stacktrace will be
* logged as well.
* @method log
* @private
* @memberOf _converse
* @param { string } message - The message to be logged
* @param { integer } level - The loglevel which allows for filtering of log messages
*/
_converse.log = function (message, level, style='') {
/* Logs messages to the browser's developer console.
*
* Parameters:
* (String) message - The message to be logged.
* (Integer) level - The loglevel which allows for filtering of log
* messages.
*
* Available loglevels are 0 for 'debug', 1 for 'info', 2 for 'warn',
* 3 for 'error' and 4 for 'fatal'.
*
* When using the 'error' or 'warn' loglevels, a full stacktrace will be
* logged as well.
*/
if (level === Strophe.LogLevel.ERROR || level === Strophe.LogLevel.FATAL) {
style = style || 'color: maroon';
}
......@@ -275,12 +274,15 @@ Strophe.log = function (level, msg) { _converse.log(level+' '+msg, level); };
Strophe.error = function (msg) { _converse.log(msg, Strophe.LogLevel.ERROR); };
/**
* Translate the given string based on the current locale.
* Handles all MUC presence stanzas.
* @method __
* @private
* @memberOf _converse
* @param { String } str - The string to translate
*/
_converse.__ = function (str) {
/* Translate the given string based on the current locale.
*
* Parameters:
* (String) str - The string to translate.
*/
if (_.isUndefined(i18n)) {
return str;
}
......@@ -565,12 +567,14 @@ _converse.initialize = async function (settings, callback) {
this.generateResource = () => `/converse.js-${Math.floor(Math.random()*139749528).toString()}`;
/**
* Send out a Chat Status Notification (XEP-0352)
* @private
* @method sendCSI
* @memberOf _converse
* @param { String } stat - The user's chat status
*/
this.sendCSI = function (stat) {
/* Send out a Chat Status Notification (XEP-0352)
*
* Parameters:
* (String) stat: The user's chat status
*/
_converse.api.send($build(stat, {xmlns: Strophe.NS.CSI}));
_converse.inactive = (stat === _converse.INACTIVE) ? true : false;
};
......@@ -661,14 +665,15 @@ _converse.initialize = async function (settings, callback) {
});
};
/**
* Reject or cancel another user's subscription to our presence updates.
* @method rejectPresenceSubscription
* @private
* @memberOf _converse
* @param { String } jid - The Jabber ID of the user whose subscription is being canceled
* @param { String } message - An optional message to the user
*/
this.rejectPresenceSubscription = function (jid, message) {
/* Reject or cancel another user's subscription to our presence updates.
*
* Parameters:
* (String) jid - The Jabber ID of the user whose subscription
* is being canceled.
* (String) message - An optional message to the user
*/
const pres = $pres({to: jid, type: "unsubscribed"});
if (message && message !== "") { pres.c("status").t(message); }
_converse.api.send(pres);
......
src/headless/converse-disco.js
View file @ a45bd8d1
......@@ -23,6 +23,11 @@ converse.plugins.add('converse-disco', {
_converse.api.promises.add('discoInitialized');
/**
* @class
* @namespace _converse.DiscoEntity
* @memberOf _converse
*/
_converse.DiscoEntity = Backbone.Model.extend({
/* A Disco Entity is a JID addressable entity that can be queried
* for features.
......@@ -64,14 +69,15 @@ converse.plugins.add('converse-disco', {
this.items.fetch();
},
/**
* Returns a Promise which resolves with a map indicating
* whether a given identity is provided by this entity.
* @private
* @method _converse.DiscoEntity#getIdentity
* @param { String } category - The identity category
* @param { String } type - The identity type
*/
async getIdentity (category, type) {
/* Returns a Promise which resolves with a map indicating
* whether a given identity is provided by this entity.
*
* Parameters:
* (String) category - The identity category
* (String) type - The identity type
*/
await this.waitUntilFeaturesDiscovered;
return this.identities.findWhere({
'category': category,
......@@ -79,13 +85,14 @@ converse.plugins.add('converse-disco', {
});
},
/**
* Returns a Promise which resolves with a map indicating
* whether a given feature is supported.
* @private
* @method _converse.DiscoEntity#hasFeature
* @param { String } feature - The feature that might be supported.
*/
async hasFeature (feature) {
/* Returns a Promise which resolves with a map indicating
* whether a given feature is supported.
*
* Parameters:
* (String) feature - The feature that might be supported.
*/
await this.waitUntilFeaturesDiscovered
if (this.features.findWhere({'var': feature})) {
return this;
......
src/headless/converse-muc.js
View file @ a45bd8d1
This diff is collapsed.
src/headless/converse-roster.js
View file @ a45bd8d1
This diff is collapsed.
src/headless/converse-vcard.js
View file @ a45bd8d1
......@@ -100,12 +100,6 @@ converse.plugins.add('converse-vcard', {
}
async function getVCard (_converse, jid) {
/* Request the VCard of another user. Returns a promise.
*
* Parameters:
* (String) jid - The Jabber ID of the user whose VCard
* is being requested.
*/
const to = Strophe.getBareJidFromJid(jid) === _converse.bare_jid ? null : jid;
let iq;
try {
......
src/headless/dist/converse-headless.js
View file @ a45bd8d1
This diff is collapsed.
src/headless/i18n.js
View file @ a45bd8d1
......@@ -44,10 +44,8 @@ import moment from "moment";
function detectLocale (library_check) {
/* Determine which locale is supported by the user's system as well
* as by the relevant library (e.g. converse.js or moment.js).
*
* Parameters:
* (Function) library_check - Returns a boolean indicating whether
* the locale is supported.
* @param { Function } library_check - Returns a boolean indicating whether
* the locale is supported.
*/
var locale, i;
if (window.navigator.userLanguage) {
......@@ -87,13 +85,11 @@ function getLocale (preferred_locale, isSupportedByLibrary) {
return detectLocale(isSupportedByLibrary) || 'en';
}
/* Check whether the locale or sub locale (e.g. en-US, en) is supported.
* @param { String } locale - The locale to check for
* @param { Function } available - Returns a boolean indicating whether the locale is supported
*/
function isLocaleAvailable (locale, available) {
/* Check whether the locale or sub locale (e.g. en-US, en) is supported.
*
* Parameters:
* (String) locale - The locale to check for
* (Function) available - returns a boolean indicating whether the locale is supported
*/
if (available(locale)) {
return locale;
} else {
......@@ -106,6 +102,9 @@ function isLocaleAvailable (locale, available) {
let jed_instance;
/**
* @namespace i18n
*/
export default {
setLocales (preferred_locale, _converse) {
......@@ -120,23 +119,23 @@ export default {
if (_.isNil(jed_instance)) {
return Jed.sprintf.apply(Jed, arguments);
}
var t = jed_instance.translate(str);
if (arguments.length>1) {
const t = jed_instance.translate(str);
if (arguments.length > 1) {
return t.fetch.apply(t, [].slice.call(arguments, 1));
} else {
return t.fetch();
}
},
/**
* Fetch the translations for the given local at the given URL.
* @private
* @method i18n#fetchTranslations
* @param { String } locale -The given i18n locale
* @param { Array } supported_locales - List of locales supported
* @param { String } locale_url - The URL from which the translations should be fetched
*/
fetchTranslations (locale, supported_locales, locale_url) {
/* Fetch the translations for the given local at the given URL.
*
* Parameters:
* (String) locale: The given i18n locale
* (Array) supported_locales: List of locales supported
* (String) locale_url: The URL from which the translations
* should be fetched.
*/
return new Promise((resolve, reject) => {
if (!isConverseLocale(locale, supported_locales) || locale === 'en') {
return resolve();
......
src/headless/utils/core.js
View file @ a45bd8d1
......@@ -14,6 +14,11 @@ import { Strophe } from "strophe.js";
import _ from "../lodash.noconflict";
import sizzle from "sizzle";
/**
* The utils object
* @namespace u
*/
const u = {};
u.toStanza = function (string) {
......@@ -147,14 +152,15 @@ u.applyUserSettings = function applyUserSettings (context, settings, user_settin
}
};
/**
* Converts an HTML string into a DOM Node.
* Expects that the HTML string has only one top-level element,
* i.e. not multiple ones.
* @private
* @method u#stringToNode
* @param { String } s - The HTML string
*/
u.stringToNode = function (s) {
/* Converts an HTML string into a DOM Node.
* Expects that the HTML string has only one top-level element,
* i.e. not multiple ones.
*
* Parameters:
* (String) s - The HTML string
*/
var div = document.createElement('div');
div.innerHTML = s;
return div.firstElementChild;
......@@ -170,26 +176,28 @@ u.getOuterWidth = function (el, include_margin=false) {
return width;
};
/**
* Converts an HTML string into a DOM element.
* Expects that the HTML string has only one top-level element,
* i.e. not multiple ones.
* @private
* @method u#stringToElement
* @param { String } s - The HTML string
*/
u.stringToElement = function (s) {
/* Converts an HTML string into a DOM element.
* Expects that the HTML string has only one top-level element,
* i.e. not multiple ones.
*
* Parameters:
* (String) s - The HTML string
*/
var div = document.createElement('div');
div.innerHTML = s;
return div.firstElementChild;
};
/**
* Checks whether the DOM element matches the given selector.
* @private
* @method u#matchesSelector
* @param { DOMElement } el - The DOM element
* @param { String } selector - The selector
*/
u.matchesSelector = function (el, selector) {
/* Checks whether the DOM element matches the given selector.
*
* Parameters:
* (DOMElement) el - The DOM element
* (String) selector - The selector
*/
const match = (
el.matches ||
el.matchesSelector ||
......@@ -201,15 +209,14 @@ u.matchesSelector = function (el, selector) {
return match ? match.call(el, selector) : false;
};
/**
* Returns a list of children of the DOM element that match the selector.
* @private
* @method u#queryChildren
* @param { DOMElement } el - the DOM element
* @param { String } selector - the selector they should be matched against
*/
u.queryChildren = function (el, selector) {
/* Returns a list of children of the DOM element that match the
* selector.
*
* Parameters:
* (DOMElement) el - the DOM element
* (String) selector - the selector they should be matched
* against.
*/
return _.filter(el.childNodes, _.partial(u.matchesSelector, _, selector));
};
......@@ -296,16 +303,17 @@ u.interpolate = function (string, o) {
});
};
/**
* Call the callback once all the events have been triggered
* @private
* @method u#onMultipleEvents
* @param { Array } events: An array of objects, with keys `object` and
* `event`, representing the event name and the object it's
* triggered upon.
* @param { Function } callback: The function to call once all events have
* been triggered.
*/
u.onMultipleEvents = function (events=[], callback) {
/* Call the callback once all the events have been triggered
*
* Parameters:
* (Array) events: An array of objects, with keys `object` and
* `event`, representing the event name and the object it's
* triggered upon.
* (Function) callback: The function to call once all events have
* been triggered.
*/
let triggered = [];
function handler (result) {
......
src/headless/utils/form.js
View file @ a45bd8d1
......@@ -10,12 +10,13 @@ import _ from "../lodash.noconflict";
import tpl_field from "../templates/field.html";
import u from "./core";
/**
* Takes an HTML DOM and turns it into an XForm field.
* @private
* @method u#webForm2xForm
* @param { DOMElement } field - the field to convert
*/
u.webForm2xForm = function (field) {
/* Takes an HTML DOM and turns it into an XForm field.
*
* Parameters:
* (DOMElement) field - the field to convert
*/
let value;
if (field.getAttribute('type') === 'checkbox') {
value = field.checked && 1 || 0;
......
src/headless/utils/muc.js
View file @ a45bd8d1
......@@ -15,33 +15,34 @@ import u from "./core";
const { Strophe, sizzle, _ } = converse.env;
/**
* Given two lists of objects with 'jid', 'affiliation' and
* 'reason' properties, return a new list containing
* those objects that are new, changed or removed
* (depending on the 'remove_absentees' boolean).
*
* The affiliations for new and changed members stay the
* same, for removed members, the affiliation is set to 'none'.
*
* The 'reason' property is not taken into account when
* comparing whether affiliations have been changed.
* @private
* @method u#computeAffiliationsDelta
* @param { boolean } exclude_existing - Indicates whether JIDs from
* the new list which are also in the old list
* (regardless of affiliation) should be excluded
* from the delta. One reason to do this
* would be when you want to add a JID only if it
* doesn't have *any* existing affiliation at all.
* @param { boolean } remove_absentees - Indicates whether JIDs
* from the old list which are not in the new list
* should be considered removed and therefore be
* included in the delta with affiliation set
* to 'none'.
* @param { array } new_list - Array containing the new affiliations
* @param { array } old_list - Array containing the old affiliations
*/
u.computeAffiliationsDelta = function computeAffiliationsDelta (exclude_existing, remove_absentees, new_list, old_list) {
/* Given two lists of objects with 'jid', 'affiliation' and
* 'reason' properties, return a new list containing
* those objects that are new, changed or removed
* (depending on the 'remove_absentees' boolean).
*
* The affiliations for new and changed members stay the
* same, for removed members, the affiliation is set to 'none'.
*
* The 'reason' property is not taken into account when
* comparing whether affiliations have been changed.
*
* Parameters:
* (Boolean) exclude_existing: Indicates whether JIDs from
* the new list which are also in the old list
* (regardless of affiliation) should be excluded
* from the delta. One reason to do this
* would be when you want to add a JID only if it
* doesn't have *any* existing affiliation at all.
* (Boolean) remove_absentees: Indicates whether JIDs
* from the old list which are not in the new list
* should be considered removed and therefore be
* included in the delta with affiliation set
* to 'none'.
* (Array) new_list: Array containing the new affiliations
* (Array) old_list: Array containing the old affiliations
*/
const new_jids = _.map(new_list, 'jid');
const old_jids = _.map(old_list, 'jid');
......
src/utils/html.js
View file @ a45bd8d1
......@@ -304,13 +304,14 @@ u.nextUntil = function (el, selector, include_self=false) {
return matches;
}
/**
* Helper method that replace HTML-escaped symbols with equivalent characters
* (e.g. transform occurrences of '&amp;' to '&')
* @private
* @method u#unescapeHTML
* @param { String } string - a String containing the HTML-escaped symbols.
*/
u.unescapeHTML = function (string) {
/* Helper method that replace HTML-escaped symbols with equivalent characters
* (e.g. transform occurrences of '&amp;' to '&')
*
* Parameters:
* (String) string: a String containing the HTML-escaped symbols.
*/
var div = document.createElement('div');
div.innerHTML = string;
return div.innerText;
......@@ -381,13 +382,14 @@ u.slideToggleElement = function (el, duration) {
};
/**
* Shows/expands an element by sliding it out of itself
* @private
* @method u#slideOut
* @param { HTMLElement } el - The HTML string
* @param { Number } duration - The duration amount in milliseconds
*/
u.slideOut = function (el, duration=200) {
/* Shows/expands an element by sliding it out of itself
*
* Parameters:
* (HTMLElement) el - The HTML string
* (Number) duration - The duration amount in milliseconds
*/
return new Promise((resolve, reject) => {
if (_.isNil(el)) {
const err = "Undefined or null element passed into slideOut"
......@@ -528,16 +530,15 @@ u.fadeIn = function (el, callback) {
};
/**
* Takes a field in XMPP XForm (XEP-004: Data Forms) format
* and turns it into an HTML field.
* Returns either text or a DOM element (which is not ideal, but fine for now).
* @private
* @method u#xForm2webForm
* @param { XMLElement } field - the field to convert
*/
u.xForm2webForm = function (field, stanza, domain) {
/* Takes a field in XMPP XForm (XEP-004: Data Forms) format
* and turns it into an HTML field.
*
* Returns either text or a DOM element (which is not ideal, but fine
* for now).
*
* Parameters:
* (XMLElement) field - the field to convert
*/
if (field.getAttribute('type') === 'list-single' ||
field.getAttribute('type') === 'list-multi') {
......
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
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7