From 05ad27e8b07dc41eb53ae133f44abbe421f01b97 Mon Sep 17 00:00:00 2001 From: Artur Arseniev Date: Tue, 12 Oct 2021 16:38:30 +0200 Subject: [PATCH] Update SelectorManager docs --- docs/api/selector.md | 10 +--- docs/api/selector_manager.md | 107 ++++++++++++++-------------------- src/common/module.js | 4 ++ src/selector_manager/index.js | 52 ++++++++--------- 4 files changed, 74 insertions(+), 99 deletions(-) diff --git a/docs/api/selector.md b/docs/api/selector.md index 9788bced3..4bca935eb 100644 --- a/docs/api/selector.md +++ b/docs/api/selector.md @@ -13,19 +13,15 @@ * `private` **[Boolean][3]?** If true, it can't be seen by the Style Manager, but it will be rendered in the canvas and in export code. * `protected` **[Boolean][3]?** If true, it can't be removed from the attacched component. -### getFullName +### toString -Get full selector name. - -#### Parameters - -* `opts` (optional, default `{}`) +Get selector as a string. #### Examples ```javascript // Given such selector: { name: 'my-selector', type: 2 } -console.log(selector.getFullName()); +console.log(selector.toString()); // -> `#my-selector` ``` diff --git a/docs/api/selector_manager.md b/docs/api/selector_manager.md index f825d5487..a618238fe 100644 --- a/docs/api/selector_manager.md +++ b/docs/api/selector_manager.md @@ -58,126 +58,107 @@ sm.add(...); * [getConfig][2] * [add][3] -* [addClass][4] -* [get][5] +* [get][4] +* [remove][5] * [getAll][6] * [setState][7] * [getState][8] [Selector]: selector.html -## init +## getConfig Get configuration object -### Parameters - -* `conf` (optional, default `{}`) - Returns **[Object][9]** -## setState +## add -Change the selector state +Add a new selector to the collection if it does not already exist. +You can pass selectors properties or string identifiers. ### Parameters -* `value` **[String][10]** State value +* `props` **([Object][9] | [String][10])** Selector properties or string identifiers, eg. `{ name: 'my-class', label: 'My class' }`, `.my-cls` +* `opts` **[Object][9]?** Selector options (optional, default `{}`) ### Examples ```javascript -selectorManager.setState('hover'); +const selector = selectorManager.add({ name: 'my-class', label: 'My class' }); +console.log(selector.toString()) // `.my-class` +// Same as +const selector = selectorManager.add('.my-class'); +console.log(selector.toString()) // `.my-class` ``` -Returns **this** +Returns **[Selector]** -## getState - -Get the current selector state - -Returns **[String][10]** - -## add +## get -Add a new selector to collection if it's not already exists. Class type is a default one +Get the selector by its name/type ### Parameters -* `name` **([String][10] | [Array][11])** Selector/s name -* `opts` **[Object][9]** Selector options (optional, default `{}`) - - * `opts.label` **[String][10]** Label for the selector, if it's not provided the label will be the same as the name (optional, default `''`) - * `opts.type` **[String][10]** Type of the selector. At the moment, only 'class' (1) is available (optional, default `1`) +* `name` **[String][10]** Selector name or string identifier +* `type` ### Examples ```javascript -const selector = selectorManager.add('selectorName'); -// Same as -const selector = selectorManager.add('selectorName', { - type: 1, - label: 'selectorName' -}); -// Multiple selectors -const selectors = selectorManager.add(['.class1', '.class2', '#id1']); +const selector = selectorManager.get('.my-class'); +// Get Id +const selectorId = selectorManager.get('#my-id'); ``` -Returns **(Model | [Array][11])** +Returns **([Selector] | null)** -## addClass +## remove -Add class selectors +Remove Selector. ### Parameters -* `classes` **([Array][11] | [string][10])** Array or string of classes +* `selector` **([String][10] | [Selector])** Selector instance or Selector string identifier +* `opts` ### Examples ```javascript -sm.addClass('class1'); -sm.addClass('class1 class2'); -sm.addClass(['class1', 'class2']); -// -> [SelectorObject, ...] +const removed = selectorManager.remove('.myclass'); +// or by passing the Selector +selectorManager.remove(selectorManager.get('.myclass')); ``` -Returns **[Array][11]** Array of added selectors +Returns **[Selector]** Removed Selector -## get +## setState -Get the selector by its name +Change the selector state ### Parameters -* `name` **([String][10] | [Array][11])** Selector name -* `type` **[String][10]** Selector type +* `value` **[String][10]** State value ### Examples ```javascript -const selector = selectorManager.get('selectorName'); -// or get an array -const selectors = selectorManager.get(['class1', 'class2']); +selectorManager.setState('hover'); ``` -Returns **(Model | [Array][11])** - -## getAll - -Get all selectors +Returns **this** -Returns **Collection** +## getState -## escapeName +Get the current selector state -Return escaped selector name +Returns **[String][10]** -### Parameters +## getAll -* `name` **[String][10]** Selector name to escape +Get all selectors -Returns **[String][10]** Escaped name +Returns **Collection<[Selector]>** [1]: https://github.com/artf/grapesjs/blob/master/src/selector_manager/config/config.js @@ -185,9 +166,9 @@ Returns **[String][10]** Escaped name [3]: #add -[4]: #addclass +[4]: #get -[5]: #get +[5]: #remove [6]: #getall @@ -198,5 +179,3 @@ Returns **[String][10]** Escaped name [9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object [10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String - -[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array diff --git a/src/common/module.js b/src/common/module.js index 76365a5be..645599852 100644 --- a/src/common/module.js +++ b/src/common/module.js @@ -3,6 +3,10 @@ import { createId } from 'utils/mixins'; export default { getConfig(name) { + return this.__getConfig(name); + }, + + __getConfig(name) { const res = this.config || {}; return name ? res[name] : res; }, diff --git a/src/selector_manager/index.js b/src/selector_manager/index.js index 422b48155..00a70f771 100644 --- a/src/selector_manager/index.js +++ b/src/selector_manager/index.js @@ -102,15 +102,11 @@ export default () => { /** * Get configuration object + * @name getConfig + * @function * @return {Object} */ - /** - * Initialize module. Automatically called with a new instance of the editor - * @param {Object} config Configurations - * @return {this} - * @private - */ init(conf = {}) { this.__initConfig(defaults, conf); const config = this.getConfig(); @@ -165,26 +161,6 @@ export default () => { return this; }, - /** - * Change the selector state - * @param {String} value State value - * @returns {this} - * @example - * selectorManager.setState('hover'); - */ - setState(value) { - this.em.setState(value); - return this; - }, - - /** - * Get the current selector state - * @returns {String} - */ - getState() { - return this.em.getState(); - }, - addSelector(name, opts = {}, cOpts = {}) { let props = { ...opts }; @@ -231,7 +207,7 @@ export default () => { }, /** - * Add a new selector to collection if it's not already exists. + * Add a new selector to the collection if it does not already exist. * You can pass selectors properties or string identifiers. * @param {Object|String} props Selector properties or string identifiers, eg. `{ name: 'my-class', label: 'My class' }`, `.my-cls` * @param {Object} [opts] Selector options @@ -313,11 +289,31 @@ export default () => { return this.__remove(selector, opts); }, + /** + * Change the selector state + * @param {String} value State value + * @returns {this} + * @example + * selectorManager.setState('hover'); + */ + setState(value) { + this.em.setState(value); + return this; + }, + + /** + * Get the current selector state + * @returns {String} + */ + getState() { + return this.em.getState(); + }, + /** * Get all selectors * @name getAll * @function - * @return {Collection} + * @return {Collection<[Selector]>} * */ /**