diff --git a/docs/api.js b/docs/api.js index 4f1ac2d00..e3d77e0a1 100644 --- a/docs/api.js +++ b/docs/api.js @@ -25,6 +25,7 @@ async function generateDocs () { ['device_manager/index.js', 'device_manager.md'], ['device_manager/model/Device.js', 'device.md'], ['selector_manager/index.js', 'selector_manager.md'], + ['selector_manager/model/Selector.js', 'selector.md'], ['css_composer/index.js', 'css_composer.md'], ['css_composer/model/CssRule.js', 'css_rule.md'], ['modal_dialog/index.js', 'modal_dialog.md'], diff --git a/docs/api/editor.md b/docs/api/editor.md index abd42ee9f..087ac2f4d 100644 --- a/docs/api/editor.md +++ b/docs/api/editor.md @@ -79,13 +79,6 @@ editor.on('EVENT-NAME', (some, argument) => { By changing `result.content` you're able to customize what is dropped -### Selectors - -* `selector:add` - New selector is add. Passes the new selector as an argument -* `selector:remove` - Selector removed. Passes the removed selector as an argument -* `selector:update` - Selector updated. Passes the updated selector as an argument -* `selector:state` - State changed. Passes the new state value as an argument - ### RTE * `rte:enable` - RTE enabled. The view, on which RTE is enabled, is passed as an argument @@ -101,29 +94,33 @@ By changing `result.content` you're able to customize what is dropped * `run` - Triggered on run of any command. The id and the result are passed as arguments to the callback * `stop` - Triggered on stop of any command. The id and the result are passed as arguments to the callback +### Selectors + +Check the [Selectors][2] module. + ### Blocks -Check the [Blocks][2] module. +Check the [Blocks][3] module. ### Assets -Check the [Assets][3] module. +Check the [Assets][4] module. ### Modal -Check the [Modal][4] module. +Check the [Modal][5] module. ### Devices -Check the [Devices][5] module. +Check the [Devices][6] module. ### Parser -Check the [Parser][6] module. +Check the [Parser][7] module. ### Pages -Check the [Pages][7] module. +Check the [Pages][8] module. ### General @@ -139,7 +136,7 @@ Returns configuration object ### Parameters -* `prop` **[string][8]?** Property name +* `prop` **[string][9]?** Property name Returns **any** Returns the configuration object or the value of the specified property @@ -150,12 +147,12 @@ Returns HTML built inside canvas ### Parameters -* `opts` **[Object][9]** Options (optional, default `{}`) +* `opts` **[Object][10]** Options (optional, default `{}`) * `opts.component` **Component?** Return the HTML of a specific Component - * `opts.cleanId` **[Boolean][10]** Remove unnecessary IDs (eg. those created automatically) (optional, default `false`) + * `opts.cleanId` **[Boolean][11]** Remove unnecessary IDs (eg. those created automatically) (optional, default `false`) -Returns **[string][8]** HTML string +Returns **[string][9]** HTML string ## getCss @@ -163,13 +160,13 @@ Returns CSS built inside canvas ### Parameters -* `opts` **[Object][9]** Options (optional, default `{}`) +* `opts` **[Object][10]** Options (optional, default `{}`) * `opts.component` **Component?** Return the CSS of a specific Component - * `opts.json` **[Boolean][10]** Return an array of CssRules instead of the CSS string (optional, default `false`) - * `opts.avoidProtected` **[Boolean][10]** Don't include protected CSS (optional, default `false`) + * `opts.json` **[Boolean][11]** Return an array of CssRules instead of the CSS string (optional, default `false`) + * `opts.avoidProtected` **[Boolean][11]** Don't include protected CSS (optional, default `false`) -Returns **([String][8] | [Array][11]\)** CSS string or array of CssRules +Returns **([String][9] | [Array][12]\)** CSS string or array of CssRules ## getJs @@ -177,11 +174,11 @@ Returns JS of all components ### Parameters -* `opts` **[Object][9]** Options (optional, default `{}`) +* `opts` **[Object][10]** Options (optional, default `{}`) * `opts.component` **Component?** Get the JS of a specific component -Returns **[String][8]** JS string +Returns **[String][9]** JS string ## getComponents @@ -201,8 +198,8 @@ Set components inside editor's canvas. This method overrides actual components ### Parameters -* `components` **([Array][11]<[Object][9]> | [Object][9] | [string][8])** HTML string or components model -* `opt` **[Object][9]** the options object to be used by the \[setComponents][em#setComponents][12] method (optional, default `{}`) +* `components` **([Array][12]<[Object][10]> | [Object][10] | [string][9])** HTML string or components model +* `opt` **[Object][10]** the options object to be used by the \[setComponents][em#setComponents][13] method (optional, default `{}`) ### Examples @@ -224,10 +221,10 @@ Add components ### Parameters -* `components` **([Array][11]<[Object][9]> | [Object][9] | [string][8])** HTML string or components model -* `opts` **[Object][9]** Options +* `components` **([Array][12]<[Object][10]> | [Object][10] | [string][9])** HTML string or components model +* `opts` **[Object][10]** Options - * `opts.avoidUpdateStyle` **[Boolean][10]** If the HTML string contains styles, + * `opts.avoidUpdateStyle` **[Boolean][11]** If the HTML string contains styles, by default, they will be created and, if already exist, updated. When this option is true, styles already created will not be updated. (optional, default `false`) @@ -243,13 +240,13 @@ editor.addComponents({ }); ``` -Returns **[Array][11]\** +Returns **[Array][12]\** ## getStyle Returns style in JSON format object -Returns **[Object][9]** +Returns **[Object][10]** ## setStyle @@ -257,7 +254,7 @@ Set style inside editor's canvas. This method overrides actual style ### Parameters -* `style` **([Array][11]<[Object][9]> | [Object][9] | [string][8])** CSS string or style model +* `style` **([Array][12]<[Object][10]> | [Object][10] | [string][9])** CSS string or style model * `opt` (optional, default `{}`) ### Examples @@ -279,7 +276,7 @@ Add styles to the editor ### Parameters -* `style` **([Array][11]<[Object][9]> | [Object][9] | [string][8])** CSS string or style model +* `style` **([Array][12]<[Object][10]> | [Object][10] | [string][9])** CSS string or style model * `opts` (optional, default `{}`) ### Examples @@ -288,7 +285,7 @@ Add styles to the editor editor.addStyle('.cls{color: red}'); ``` -Returns **[Array][11]\** Array of created CssRule instances +Returns **[Array][12]\** Array of created CssRule instances ## getSelected @@ -300,7 +297,7 @@ Returns **Model** Returns an array of all selected components -Returns **[Array][11]** +Returns **[Array][12]** ## getSelectedToStyle @@ -318,10 +315,10 @@ Select a component ### Parameters -* `el` **(Component | [HTMLElement][13])** Component to select -* `opts` **[Object][9]?** Options +* `el` **(Component | [HTMLElement][14])** Component to select +* `opts` **[Object][10]?** Options - * `opts.scroll` **[Boolean][10]?** Scroll canvas to the selected element + * `opts.scroll` **[Boolean][11]?** Scroll canvas to the selected element ### Examples @@ -340,7 +337,7 @@ Add component to selection ### Parameters -* `el` **(Component | [HTMLElement][13] | [Array][11])** Component to select +* `el` **(Component | [HTMLElement][14] | [Array][12])** Component to select ### Examples @@ -356,7 +353,7 @@ Remove component from selection ### Parameters -* `el` **(Component | [HTMLElement][13] | [Array][11])** Component to select +* `el` **(Component | [HTMLElement][14] | [Array][12])** Component to select ### Examples @@ -372,7 +369,7 @@ Toggle component selection ### Parameters -* `el` **(Component | [HTMLElement][13] | [Array][11])** Component to select +* `el` **(Component | [HTMLElement][14] | [Array][12])** Component to select ### Examples @@ -404,7 +401,7 @@ change the canvas to the proper width ### Parameters -* `name` **[string][8]** Name of the device +* `name` **[string][9]** Name of the device ### Examples @@ -426,7 +423,7 @@ console.log(device); // 'Tablet' ``` -Returns **[string][8]** Device name +Returns **[string][9]** Device name ## runCommand @@ -434,8 +431,8 @@ Execute command ### Parameters -* `id` **[string][8]** Command ID -* `options` **[Object][9]** Custom options (optional, default `{}`) +* `id` **[string][9]** Command ID +* `options` **[Object][10]** Custom options (optional, default `{}`) ### Examples @@ -451,8 +448,8 @@ Stop the command if stop method was provided ### Parameters -* `id` **[string][8]** Command ID -* `options` **[Object][9]** Custom options (optional, default `{}`) +* `id` **[string][9]** Command ID +* `options` **[Object][10]** Custom options (optional, default `{}`) ### Examples @@ -468,9 +465,9 @@ Store data to the current storage ### Parameters -* `clb` **[Function][14]** Callback function +* `clb` **[Function][15]** Callback function -Returns **[Object][9]** Stored data +Returns **[Object][10]** Stored data ## storeData @@ -483,7 +480,7 @@ console.log(editor.storeData()); // { pages: [...], styles: [...], ... } ``` -Returns **[Object][9]** +Returns **[Object][10]** ## load @@ -491,9 +488,9 @@ Load data from the current storage ### Parameters -* `clb` **[Function][14]** Callback function +* `clb` **[Function][15]** Callback function -Returns **[Object][9]** Stored data +Returns **[Object][10]** Stored data ## loadData @@ -501,7 +498,7 @@ Load data from the JSON data object ### Parameters -* `data` **[Object][9]** Data to load +* `data` **[Object][10]** Data to load ### Examples @@ -509,21 +506,21 @@ Load data from the JSON data object editor.loadData({ pages: [...], styles: [...], ... }) ``` -Returns **[Object][9]** Loaded object +Returns **[Object][10]** Loaded object ## getContainer Returns container element. The one which was indicated as 'container' on init method -Returns **[HTMLElement][13]** +Returns **[HTMLElement][14]** ## getDirtyCount Return the count of changes made to the content and not yet stored. This count resets at any `store()` -Returns **[number][15]** +Returns **[number][16]** ## refresh @@ -536,9 +533,9 @@ refresh you'll get misleading position of tools ### Parameters * `opts` -* `options` **[Object][9]?** Options +* `options` **[Object][10]?** Options - * `options.tools` **[Boolean][10]** Update the position of tools (eg. rich text editor, component highlighter, etc.) (optional, default `false`) + * `options.tools` **[Boolean][11]** Update the position of tools (eg. rich text editor, component highlighter, etc.) (optional, default `false`) ## setCustomRte @@ -546,7 +543,7 @@ Replace the built-in Rich Text Editor with a custom one. ### Parameters -* `obj` **[Object][9]** Custom RTE Interface +* `obj` **[Object][10]** Custom RTE Interface ### Examples @@ -586,7 +583,7 @@ custom parser, pass `null` as the argument ### Parameters -* `parser` **([Function][14] | null)** Parser function +* `parser` **([Function][15] | null)** Parser function ### Examples @@ -608,11 +605,11 @@ Returns **this** ## setDragMode Change the global drag mode of components. -To get more about this feature read: [https://github.com/artf/grapesjs/issues/1936][16] +To get more about this feature read: [https://github.com/artf/grapesjs/issues/1936][17] ### Parameters -* `value` **[String][8]** Drag mode, options: 'absolute' | 'translate' +* `value` **[String][9]** Drag mode, options: 'absolute' | 'translate' Returns **this** @@ -623,10 +620,10 @@ Trigger event log message ### Parameters * `msg` **any** Message to log -* `opts` **[Object][9]** Custom options (optional, default `{}`) +* `opts` **[Object][10]** Custom options (optional, default `{}`) - * `opts.ns` **[String][8]** Namespace of the log (eg. to use in plugins) (optional, default `''`) - * `opts.level` **[String][8]** Level of the log, `debug`, `info`, `warning`, `error` (optional, default `'debug'`) + * `opts.ns` **[String][9]** Namespace of the log (eg. to use in plugins) (optional, default `''`) + * `opts.level` **[String][9]** Level of the log, `debug`, `info`, `warning`, `error` (optional, default `'debug'`) ### Examples @@ -648,11 +645,11 @@ Translate label ### Parameters * `args` **...any** -* `key` **[String][8]** Label to translate -* `opts` **[Object][9]?** Options for the translation +* `key` **[String][9]** Label to translate +* `opts` **[Object][10]?** Options for the translation - * `opts.params` **[Object][9]?** Params for the translation - * `opts.noWarn` **[Boolean][10]?** Avoid warnings in case of missing resources + * `opts.params` **[Object][10]?** Params for the translation + * `opts.noWarn` **[Boolean][11]?** Avoid warnings in case of missing resources ### Examples @@ -664,7 +661,7 @@ editor.t('msg2', { params: { test: 'hello' } }); editor.t('msg2', { params: { test: 'hello' }, l: 'it' }); ``` -Returns **[String][8]** +Returns **[String][9]** ## on @@ -672,8 +669,8 @@ Attach event ### Parameters -* `event` **[string][8]** Event name -* `callback` **[Function][14]** Callback function +* `event` **[string][9]** Event name +* `callback` **[Function][15]** Callback function Returns **this** @@ -683,8 +680,8 @@ Attach event and detach it after the first run ### Parameters -* `event` **[string][8]** Event name -* `callback` **[Function][14]** Callback function +* `event` **[string][9]** Event name +* `callback` **[Function][15]** Callback function Returns **this** @@ -694,8 +691,8 @@ Detach event ### Parameters -* `event` **[string][8]** Event name -* `callback` **[Function][14]** Callback function +* `event` **[string][9]** Event name +* `callback` **[Function][15]** Callback function Returns **this** @@ -705,7 +702,7 @@ Trigger event ### Parameters -* `event` **[string][8]** Event to trigger +* `event` **[string][9]** Event to trigger Returns **this** @@ -717,7 +714,7 @@ Destroy the editor Render editor -Returns **[HTMLElement][13]** +Returns **[HTMLElement][14]** ## onReady @@ -726,7 +723,7 @@ The callback will be executed immediately if the method is called on the already ### Parameters -* `clb` **[Function][14]** Callback to trigger +* `clb` **[Function][15]** Callback to trigger ### Examples @@ -742,8 +739,8 @@ Print safe HTML by using ES6 tagged template strings. ### Parameters -* `literals` **[Array][11]<[String][8]>** -* `substs` **[Array][11]<[String][8]>** +* `literals` **[Array][12]<[String][9]>** +* `substs` **[Array][12]<[String][9]>** ### Examples @@ -754,36 +751,38 @@ const safeStr = 'Hello'; const strHtml = editor.html`Escaped ${unsafeStr}, unescaped $${safeStr}`; ``` -Returns **[String][8]** +Returns **[String][9]** [1]: https://github.com/artf/grapesjs/blob/master/src/editor/config/config.js -[2]: /api/block_manager.html +[2]: /api/selector_manager.html + +[3]: /api/block_manager.html -[3]: /api/assets.html +[4]: /api/assets.html -[4]: /api/modal_dialog.html +[5]: /api/modal_dialog.html -[5]: /api/device_manager.html +[6]: /api/device_manager.html -[6]: /api/parser.html +[7]: /api/parser.html -[7]: /api/pages.html +[8]: /api/pages.html -[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String +[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String -[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object +[10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object -[10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean +[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean -[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array +[12]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array -[12]: em#setComponents +[13]: em#setComponents -[13]: https://developer.mozilla.org/docs/Web/HTML/Element +[14]: https://developer.mozilla.org/docs/Web/HTML/Element -[14]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function +[15]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function -[15]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number +[16]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number -[16]: https://github.com/artf/grapesjs/issues/1936 +[17]: https://github.com/artf/grapesjs/issues/1936 diff --git a/docs/api/page.md b/docs/api/page.md index 117f81ff1..9a3dea999 100644 --- a/docs/api/page.md +++ b/docs/api/page.md @@ -1,5 +1,31 @@ +## getId + +Get page id + +Returns **[String][1]** + +## getName + +Get page name + +Returns **[String][1]** + +## setName + +Update page name + +### Parameters + +* `name` **[String][1]** New page name + +### Examples + +```javascript +page.setName('New name'); +``` + ## getAllFrames Get all frames @@ -10,7 +36,7 @@ Get all frames const arrayOfFrames = page.getAllFrames(); ``` -Returns **[Array][1]\** +Returns **[Array][2]\** ## getMainFrame @@ -37,4 +63,6 @@ console.log(rootComponent.toHTML()); Returns **Component** -[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array +[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String + +[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array diff --git a/docs/api/selector.md b/docs/api/selector.md new file mode 100644 index 000000000..9788bced3 --- /dev/null +++ b/docs/api/selector.md @@ -0,0 +1,38 @@ + + +## Selector + + + +### Properties + +* `name` **[String][1]** Selector name, eg. `my-class` +* `label` **[String][1]** Selector label, eg. `My Class` +* `type` **[Number][2]?** Type of the selector. 1 (class) | 2 (id) +* `active` **[Boolean][3]?** If not active, it's not selectable by the Style Manager. +* `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 + +Get full selector name. + +#### Parameters + +* `opts` (optional, default `{}`) + +#### Examples + +```javascript +// Given such selector: { name: 'my-selector', type: 2 } +console.log(selector.getFullName()); +// -> `#my-selector` +``` + +Returns **[String][1]** + +[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String + +[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number + +[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean diff --git a/docs/api/selector_manager.md b/docs/api/selector_manager.md index a6855fd19..f825d5487 100644 --- a/docs/api/selector_manager.md +++ b/docs/api/selector_manager.md @@ -35,12 +35,27 @@ const editor = grapesjs.init({ }) ``` -Once the editor is instantiated you can use its API. Before using these methods you should get the module from the instance +Once the editor is instantiated you can use its API and listen to its events. Before using these methods, you should get the module from the instance. ```js -const selectorManager = editor.SelectorManager; +// Listen to events +editor.on('selector:add', (selector) => { ... }); + +// Use the API +const sm = editor.Selectors; +sm.add(...); ``` +## Available Events + +* `selector:add` - Selector added. The [Selector] is passed as an argument to the callback. +* `selector:remove` - Selector removed. The [Selector] is passed as an argument to the callback. +* `selector:update` - Selector updated. The [Selector] and the object containing changes are passed as arguments to the callback. +* `selector:state` - State changed. Passes the new state value as an argument. +* `selector` - Catch-all event for all the events mentioned above. An object containing all the available data about the triggered event is passed as an argument to the callback. + +## Methods + * [getConfig][2] * [add][3] * [addClass][4] @@ -49,10 +64,16 @@ const selectorManager = editor.SelectorManager; * [setState][7] * [getState][8] -## getConfig +[Selector]: selector.html + +## init Get configuration object +### Parameters + +* `conf` (optional, default `{}`) + Returns **[Object][9]** ## setState