From 077dd51e8a57c2b8d0ba5f56a0917e3639a142e2 Mon Sep 17 00:00:00 2001 From: Yuri Kuznetsov Date: Thu, 9 Jun 2022 19:06:04 +0300 Subject: [PATCH] docs --- client/src/collection.js | 56 ++++++++++++++++++++++- client/src/controller.js | 1 + client/src/model.js | 96 ++++++++++++++++++++++++++++++++++++---- client/src/router.js | 49 ++++++++++++++++++-- 4 files changed, 188 insertions(+), 14 deletions(-) diff --git a/client/src/collection.js b/client/src/collection.js index 294a972f89..ccb82eda95 100644 --- a/client/src/collection.js +++ b/client/src/collection.js @@ -28,11 +28,49 @@ define('collection', [], function () { + /** + * Add a model or models. Firing an `add` event for each model, and an `update` event afterwards. + * + * @function add + * @memberof Backbone.Collection + * @param {Backbone.Model|Backbone.Model[]} models A model or models. + * @param {Object} [options] Options. + */ + + /** + * Remove a model or models. Fires a `remove` event for each model, and a single `update` event afterwards, + * unless `{silent: true}`. + * + * @function remove + * @memberof Backbone.Collection + * @param {Backbone.Model|Backbone.Model[]|string|string[]} models A model, models, ID or IDs. + * @param {Object} [options] Options. + */ + + /** + * Append a model. + * + * @function push + * @memberof Backbone.Collection + * @param {Backbone.Model} model A model. + * @param {Object} [options] Options. + */ + + /** + * Remove and return the last model from the collection. + * + * @function pop + * @memberof Backbone.Collection + * @param {Object} [options] Options. + */ + /** * @class Espo.Collection * @extends Backbone.Collection + * @mixes Backbone.Events * * @property {number} length - A number of records. + * @property {Espo.Model[]} models - Models. */ var Collection = Backbone.Collection.extend(/** @lends Espo.Collection */ { @@ -158,6 +196,7 @@ define('collection', [], function () { }, /** + * Next page. */ nextPage: function () { var offset = this.offset + this.maxSize; @@ -166,6 +205,7 @@ define('collection', [], function () { }, /** + * Previous page. */ previousPage: function () { var offset = this.offset - this.maxSize; @@ -174,12 +214,14 @@ define('collection', [], function () { }, /** + * First page. */ firstPage: function () { this.setOffset(0); }, /** + * Last page. */ lastPage: function () { let offset = this.total - this.total % this.maxSize; @@ -192,7 +234,9 @@ define('collection', [], function () { }, /** - * @param {number} offset + * Set an offset. + * + * @param {number} offset Offset. */ setOffset: function (offset) { if (offset < 0) { @@ -221,7 +265,9 @@ define('collection', [], function () { }, /** - * @param {Object} options + * Fetches from the backend. + * + * @param {Object} options Options. * @returns {Promise} */ fetch: function (options) { @@ -269,6 +315,7 @@ define('collection', [], function () { }, /** + * Abort the last fetch. */ abortLastFetch: function () { if (this.lastXhr && this.lastXhr.readyState < 4) { @@ -277,6 +324,8 @@ define('collection', [], function () { }, /** + * Get a where clause. + * * @returns {Array.{Object}} */ getWhere: function () { @@ -301,6 +350,7 @@ define('collection', [], function () { }, /** + * Reset the order to default. */ resetOrderToDefault: function () { this.orderBy = this.defaultOrderBy; @@ -308,6 +358,8 @@ define('collection', [], function () { }, /** + * Set an order. + * * @param {string} orderBy * @param {boolean} [order] * @param {boolean} [setDefault] diff --git a/client/src/controller.js b/client/src/controller.js index ed7c4d8b4a..2b56f374e9 100644 --- a/client/src/controller.js +++ b/client/src/controller.js @@ -32,6 +32,7 @@ define('controller', [], function () { * Controller. Views, Models and Collections are created here. * * @class Espo.Controller + * @mixes Backbone.Events * * @param {Object} params * @param {Object} injections diff --git a/client/src/model.js b/client/src/model.js index 76f71bd5f3..e62073f2be 100644 --- a/client/src/model.js +++ b/client/src/model.js @@ -30,15 +30,54 @@ define('model', [], function () { let Dep = Backbone.Model; + /** + * Save values to the backend. + * + * @function save + * @memberof Backbone.Model + * @param {Object} [attributes] Attribute values. + * @param {Object} [options] Options. + * @returns {Promise} + */ + + /** + * Whether an attribute is changed. To be used only within a callback of a 'change' event listener. + * + * @function changed + * @memberof Backbone.Model + * @param {string} attribute An attribute name. + * @returns {boolean} + */ + + /** + * Removes all attributes from the model, including the `id` attribute. + * Fires a `change` event unless `silent` is passed as an option. + * + * @function clear + * @memberof Backbone.Model + * @param {Object} [options] Options. + */ + /** * @class Espo.Model * @extends Backbone.Model + * @mixes Backbone.Events + * + * @property {string|null} id - An ID. + * @property {Object} attributes - Attribute values. + * @property {string} cid - An ID unique among all models. */ let Model = Dep.extend(/** @lends Espo.Model */{ + /** + * A root URL. + * @property {string|null} + */ + urlRoot: null, + /** * An entity type. - * @property {string} name + * @property {string} */ name: null, @@ -46,6 +85,10 @@ define('model', [], function () { _user: null, + /** + * Definitions. + * @property {Object|null} + */ defs: null, initialize: function () { @@ -74,9 +117,11 @@ define('model', [], function () { }, /** - * @param {string|Object} key - * @param {*} val - * @param {Object} options + * Set an attribute value or multiple values. + * + * @param {string|Object} key An attribute name or a {key => value} object. + * @param {*} [val] A value or options if the first argument is an object. + * @param {Object} [options] Options. `silent` won't trigger a `change` event. * @returns {this} */ set: function (key, val, options) { @@ -95,7 +140,9 @@ define('model', [], function () { }, /** - * @param {string} key + * Get an attribute value. + * + * @param {string} key An attribute name. * @returns {*} */ get: function (key) { @@ -107,7 +154,9 @@ define('model', [], function () { }, /** - * @param {string} key + * Whether attribute is set. + * + * @param {string} key An attribute name. * @returns {boolean} */ has: function (key) { @@ -117,6 +166,8 @@ define('model', [], function () { }, /** + * Is new. + * * @returns {boolean} */ isNew: function () { @@ -133,6 +184,8 @@ define('model', [], function () { }, /** + * Get cloned attribute values. + * * @returns {Object} */ getClonedAttributes: function () { @@ -146,6 +199,7 @@ define('model', [], function () { }, /** + * Populate default values. */ populateDefaults: function () { var defaultHash = {}; @@ -205,6 +259,8 @@ define('model', [], function () { }, /** + * Get a link multiple column value. + * * @param {string} field * @param {string} column * @param {string} id @@ -268,6 +324,8 @@ define('model', [], function () { }, /** + * Get a field type. + * * @param {string} field * @returns {string|null} */ @@ -280,6 +338,8 @@ define('model', [], function () { }, /** + * Get a field param. + * * @param {string} field * @param {string} param * @returns {*} @@ -295,6 +355,8 @@ define('model', [], function () { }, /** + * Get a link type. + * * @param {string} link * @returns {string|null} */ @@ -307,6 +369,8 @@ define('model', [], function () { }, /** + * Get a link param. + * * @param {string} link * @param {string} param * @returns {*} @@ -322,6 +386,8 @@ define('model', [], function () { }, /** + * Is a field read-only. + * * @param {string} field * @returns {bool} */ @@ -330,6 +396,8 @@ define('model', [], function () { }, /** + * If a field required. + * * @param {string} field * @returns {bool} */ @@ -338,6 +406,8 @@ define('model', [], function () { }, /** + * Get IDs of a link-multiple field. + * * @param {type} field * @returns {string[]} */ @@ -346,6 +416,8 @@ define('model', [], function () { }, /** + * Get team IDs. + * * @param {type} field * @returns {string[]} */ @@ -362,6 +434,8 @@ define('model', [], function () { }, /** + * Whether has a field. + * * @param {string} field * @returns {boolean} */ @@ -370,6 +444,8 @@ define('model', [], function () { }, /** + * Whether has a link. + * * @param {string} field * @returns {boolean} */ @@ -392,6 +468,8 @@ define('model', [], function () { }, /** + * Get an entity type. + * * @returns {string} */ getEntityType: function () { @@ -399,8 +477,9 @@ define('model', [], function () { }, /** - * @param {Object} options - * @returns {Promise} + * Fetch values from the backend. + * @param {Object} options Options. + * @returns {Promise} */ fetch: function (options) { this.lastXhr = Dep.prototype.fetch.call(this, options); @@ -409,6 +488,7 @@ define('model', [], function () { }, /** + * Abort the last fetch. */ abortLastFetch: function () { if (this.lastXhr && this.lastXhr.readyState < 4) { diff --git a/client/src/router.js b/client/src/router.js index 095cf90486..dbddf63adb 100644 --- a/client/src/router.js +++ b/client/src/router.js @@ -28,7 +28,11 @@ define('router', [], function () { - let Router = Backbone.Router.extend({ + /** + * @class Espo.Router + * @mixes Espo.Events + */ + let Router = Backbone.Router.extend(/** @lends Espo.Router */ { routeList: [ { @@ -190,10 +194,22 @@ define('router', [], function () { }); }, + /** + * Get a current URL. + * + * @returns {string} + */ getCurrentUrl: function () { return '#' + Backbone.history.fragment; }, + /** + * Process confirm-leave-out. + * + * @param {Function} callback Proceed if confirmed. + * @param {Object|null} [context] A context. + * @param {boolean} [navigateBack] To navigate back if not confirmed. + */ checkConfirmLeaveOut: function (callback, context, navigateBack) { if (this.confirmLeaveOutDisplayed) { this.navigateBack({trigger: false}); @@ -232,10 +248,11 @@ define('router', [], function () { } } ); + + return; } - else { - callback.call(context); - } + + callback.call(context); }, route: function (route, name, callback) { @@ -299,12 +316,23 @@ define('router', [], function () { }, null, true); }, + /** + * Navigate. + * + * @param {string} fragment + * @param {Options} options Options: trigger, replace. + */ navigate: function (fragment, options) { this.history.push(fragment); return Backbone.Router.prototype.navigate.call(this, fragment, options); }, + /** + * Navigate back. + * + * @param {Options} options Options: trigger, replace. + */ navigateBack: function (options) { let url; @@ -393,6 +421,14 @@ define('router', [], function () { this.dispatch(null, 'clearCache'); }, + /** + * Dispatch a controller action. + * + * @param {string} controller A controller. + * @param {string} action An action. + * @param {Object} options Options. + * @returns {undefined} + */ dispatch: function (controller, action, options) { let o = { controller: controller, @@ -405,6 +441,11 @@ define('router', [], function () { this.trigger('routed', o); }, + /** + * Get the last route data. + * + * @returns {Object} + */ getLast: function () { return this._last; },