From 14709193f7889b278479cbdd3e6eb26b5dee5d5f Mon Sep 17 00:00:00 2001 From: Artur Arseniev Date: Mon, 13 Sep 2021 16:17:34 +0200 Subject: [PATCH] Improved Modal API docs and moved related events --- docs/api/editor.md | 175 +++++++++++++++++++------------------- docs/api/modal_dialog.md | 82 ++++++++++++++++-- src/editor/index.js | 5 +- src/modal_dialog/index.js | 6 +- 4 files changed, 170 insertions(+), 98 deletions(-) diff --git a/docs/api/editor.md b/docs/api/editor.md index 03e39cc14..9fef85370 100644 --- a/docs/api/editor.md +++ b/docs/api/editor.md @@ -108,11 +108,6 @@ By changing `result.content` you're able to customize what is dropped * `rte:enable` - RTE enabled. The view, on which RTE is enabled, is passed as an argument * `rte:disable` - RTE disabled. The view, on which RTE is disabled, is passed as an argument -### Modal - -* `modal:open` - Modal is opened -* `modal:close` - Modal is closed - ### Commands * `run:{commandName}` - Triggered when some command is called to run (eg. editor.runCommand('preview')) @@ -123,17 +118,21 @@ 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 +### Modal + +Check the [Modal][2] module. + ### Devices -Check the [Devices][2] module. +Check the [Devices][3] module. ### Parser -Check the [Parser][3] module. +Check the [Parser][4] module. ### Pages -Check the [Pages][4] module. +Check the [Pages][5] module. ### General @@ -149,7 +148,7 @@ Returns configuration object ### Parameters -* `prop` **[string][5]?** Property name +* `prop` **[string][6]?** Property name Returns **any** Returns the configuration object or the value of the specified property @@ -160,12 +159,12 @@ Returns HTML built inside canvas ### Parameters -* `opts` **[Object][6]** Options (optional, default `{}`) +* `opts` **[Object][7]** Options (optional, default `{}`) * `opts.component` **Component?** Return the HTML of a specific Component - * `opts.cleanId` **[Boolean][7]** Remove unnecessary IDs (eg. those created automatically) (optional, default `false`) + * `opts.cleanId` **[Boolean][8]** Remove unnecessary IDs (eg. those created automatically) (optional, default `false`) -Returns **[string][5]** HTML string +Returns **[string][6]** HTML string ## getCss @@ -173,13 +172,13 @@ Returns CSS built inside canvas ### Parameters -* `opts` **[Object][6]** Options (optional, default `{}`) +* `opts` **[Object][7]** Options (optional, default `{}`) * `opts.component` **Component?** Return the CSS of a specific Component - * `opts.json` **[Boolean][7]** Return an array of CssRules instead of the CSS string (optional, default `false`) - * `opts.avoidProtected` **[Boolean][7]** Don't include protected CSS (optional, default `false`) + * `opts.json` **[Boolean][8]** Return an array of CssRules instead of the CSS string (optional, default `false`) + * `opts.avoidProtected` **[Boolean][8]** Don't include protected CSS (optional, default `false`) -Returns **([String][5] | [Array][8]\)** CSS string or array of CssRules +Returns **([String][6] | [Array][9]\)** CSS string or array of CssRules ## getJs @@ -187,11 +186,11 @@ Returns JS of all components ### Parameters -* `opts` **[Object][6]** Options (optional, default `{}`) +* `opts` **[Object][7]** Options (optional, default `{}`) * `opts.component` **Component?** Get the JS of a specific component -Returns **[String][5]** JS string +Returns **[String][6]** JS string ## getComponents @@ -211,8 +210,8 @@ Set components inside editor's canvas. This method overrides actual components ### Parameters -* `components` **([Array][8]<[Object][6]> | [Object][6] | [string][5])** HTML string or components model -* `opt` **[Object][6]** the options object to be used by the \[setComponents][em#setComponents][9] method (optional, default `{}`) +* `components` **([Array][9]<[Object][7]> | [Object][7] | [string][6])** HTML string or components model +* `opt` **[Object][7]** the options object to be used by the \[setComponents][em#setComponents][10] method (optional, default `{}`) ### Examples @@ -234,10 +233,10 @@ Add components ### Parameters -* `components` **([Array][8]<[Object][6]> | [Object][6] | [string][5])** HTML string or components model -* `opts` **[Object][6]** Options +* `components` **([Array][9]<[Object][7]> | [Object][7] | [string][6])** HTML string or components model +* `opts` **[Object][7]** Options - * `opts.avoidUpdateStyle` **[Boolean][7]** If the HTML string contains styles, + * `opts.avoidUpdateStyle` **[Boolean][8]** 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`) @@ -253,13 +252,13 @@ editor.addComponents({ }); ``` -Returns **[Array][8]\** +Returns **[Array][9]\** ## getStyle Returns style in JSON format object -Returns **[Object][6]** +Returns **[Object][7]** ## setStyle @@ -267,7 +266,7 @@ Set style inside editor's canvas. This method overrides actual style ### Parameters -* `style` **([Array][8]<[Object][6]> | [Object][6] | [string][5])** CSS string or style model +* `style` **([Array][9]<[Object][7]> | [Object][7] | [string][6])** CSS string or style model * `opt` (optional, default `{}`) ### Examples @@ -289,7 +288,7 @@ Add styles to the editor ### Parameters -* `style` **([Array][8]<[Object][6]> | [Object][6] | [string][5])** CSS string or style model +* `style` **([Array][9]<[Object][7]> | [Object][7] | [string][6])** CSS string or style model * `opts` (optional, default `{}`) ### Examples @@ -298,7 +297,7 @@ Add styles to the editor editor.addStyle('.cls{color: red}'); ``` -Returns **[Array][8]\** Array of created CssRule instances +Returns **[Array][9]\** Array of created CssRule instances ## getSelected @@ -310,7 +309,7 @@ Returns **Model** Returns an array of all selected components -Returns **[Array][8]** +Returns **[Array][9]** ## getSelectedToStyle @@ -328,10 +327,10 @@ Select a component ### Parameters -* `el` **(Component | [HTMLElement][10])** Component to select -* `opts` **[Object][6]?** Options +* `el` **(Component | [HTMLElement][11])** Component to select +* `opts` **[Object][7]?** Options - * `opts.scroll` **[Boolean][7]?** Scroll canvas to the selected element + * `opts.scroll` **[Boolean][8]?** Scroll canvas to the selected element ### Examples @@ -350,7 +349,7 @@ Add component to selection ### Parameters -* `el` **(Component | [HTMLElement][10] | [Array][8])** Component to select +* `el` **(Component | [HTMLElement][11] | [Array][9])** Component to select ### Examples @@ -366,7 +365,7 @@ Remove component from selection ### Parameters -* `el` **(Component | [HTMLElement][10] | [Array][8])** Component to select +* `el` **(Component | [HTMLElement][11] | [Array][9])** Component to select ### Examples @@ -382,7 +381,7 @@ Toggle component selection ### Parameters -* `el` **(Component | [HTMLElement][10] | [Array][8])** Component to select +* `el` **(Component | [HTMLElement][11] | [Array][9])** Component to select ### Examples @@ -414,7 +413,7 @@ change the canvas to the proper width ### Parameters -* `name` **[string][5]** Name of the device +* `name` **[string][6]** Name of the device ### Examples @@ -436,7 +435,7 @@ console.log(device); // 'Tablet' ``` -Returns **[string][5]** Device name +Returns **[string][6]** Device name ## runCommand @@ -444,8 +443,8 @@ Execute command ### Parameters -* `id` **[string][5]** Command ID -* `options` **[Object][6]** Custom options (optional, default `{}`) +* `id` **[string][6]** Command ID +* `options` **[Object][7]** Custom options (optional, default `{}`) ### Examples @@ -461,8 +460,8 @@ Stop the command if stop method was provided ### Parameters -* `id` **[string][5]** Command ID -* `options` **[Object][6]** Custom options (optional, default `{}`) +* `id` **[string][6]** Command ID +* `options` **[Object][7]** Custom options (optional, default `{}`) ### Examples @@ -478,9 +477,9 @@ Store data to the current storage ### Parameters -* `clb` **[Function][11]** Callback function +* `clb` **[Function][12]** Callback function -Returns **[Object][6]** Stored data +Returns **[Object][7]** Stored data ## storeData @@ -493,7 +492,7 @@ console.log(editor.storeData()); // { pages: [...], styles: [...], ... } ``` -Returns **[Object][6]** +Returns **[Object][7]** ## load @@ -501,9 +500,9 @@ Load data from the current storage ### Parameters -* `clb` **[Function][11]** Callback function +* `clb` **[Function][12]** Callback function -Returns **[Object][6]** Stored data +Returns **[Object][7]** Stored data ## loadData @@ -511,7 +510,7 @@ Load data from the JSON data object ### Parameters -* `data` **[Object][6]** Data to load +* `data` **[Object][7]** Data to load ### Examples @@ -519,21 +518,21 @@ Load data from the JSON data object editor.loadData({ pages: [...], styles: [...], ... }) ``` -Returns **[Object][6]** Loaded object +Returns **[Object][7]** Loaded object ## getContainer Returns container element. The one which was indicated as 'container' on init method -Returns **[HTMLElement][10]** +Returns **[HTMLElement][11]** ## getDirtyCount Return the count of changes made to the content and not yet stored. This count resets at any `store()` -Returns **[number][12]** +Returns **[number][13]** ## refresh @@ -546,9 +545,9 @@ refresh you'll get misleading position of tools ### Parameters * `opts` -* `options` **[Object][6]?** Options +* `options` **[Object][7]?** Options - * `options.tools` **[Boolean][7]** Update the position of tools (eg. rich text editor, component highlighter, etc.) (optional, default `false`) + * `options.tools` **[Boolean][8]** Update the position of tools (eg. rich text editor, component highlighter, etc.) (optional, default `false`) ## setCustomRte @@ -556,7 +555,7 @@ Replace the built-in Rich Text Editor with a custom one. ### Parameters -* `obj` **[Object][6]** Custom RTE Interface +* `obj` **[Object][7]** Custom RTE Interface ### Examples @@ -596,7 +595,7 @@ custom parser, pass `null` as the argument ### Parameters -* `parser` **([Function][11] | null)** Parser function +* `parser` **([Function][12] | null)** Parser function ### Examples @@ -618,11 +617,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][13] +To get more about this feature read: [https://github.com/artf/grapesjs/issues/1936][14] ### Parameters -* `value` **[String][5]** Drag mode, options: 'absolute' | 'translate' +* `value` **[String][6]** Drag mode, options: 'absolute' | 'translate' Returns **this** @@ -633,10 +632,10 @@ Trigger event log message ### Parameters * `msg` **any** Message to log -* `opts` **[Object][6]** Custom options (optional, default `{}`) +* `opts` **[Object][7]** Custom options (optional, default `{}`) - * `opts.ns` **[String][5]** Namespace of the log (eg. to use in plugins) (optional, default `''`) - * `opts.level` **[String][5]** Level of the log, `debug`, `info`, `warning`, `error` (optional, default `'debug'`) + * `opts.ns` **[String][6]** Namespace of the log (eg. to use in plugins) (optional, default `''`) + * `opts.level` **[String][6]** Level of the log, `debug`, `info`, `warning`, `error` (optional, default `'debug'`) ### Examples @@ -658,11 +657,11 @@ Translate label ### Parameters * `args` **...any** -* `key` **[String][5]** Label to translate -* `opts` **[Object][6]?** Options for the translation +* `key` **[String][6]** Label to translate +* `opts` **[Object][7]?** Options for the translation - * `opts.params` **[Object][6]?** Params for the translation - * `opts.noWarn` **[Boolean][7]?** Avoid warnings in case of missing resources + * `opts.params` **[Object][7]?** Params for the translation + * `opts.noWarn` **[Boolean][8]?** Avoid warnings in case of missing resources ### Examples @@ -674,7 +673,7 @@ editor.t('msg2', { params: { test: 'hello' } }); editor.t('msg2', { params: { test: 'hello' }, l: 'it' }); ``` -Returns **[String][5]** +Returns **[String][6]** ## on @@ -682,8 +681,8 @@ Attach event ### Parameters -* `event` **[string][5]** Event name -* `callback` **[Function][11]** Callback function +* `event` **[string][6]** Event name +* `callback` **[Function][12]** Callback function Returns **this** @@ -693,8 +692,8 @@ Attach event and detach it after the first run ### Parameters -* `event` **[string][5]** Event name -* `callback` **[Function][11]** Callback function +* `event` **[string][6]** Event name +* `callback` **[Function][12]** Callback function Returns **this** @@ -704,8 +703,8 @@ Detach event ### Parameters -* `event` **[string][5]** Event name -* `callback` **[Function][11]** Callback function +* `event` **[string][6]** Event name +* `callback` **[Function][12]** Callback function Returns **this** @@ -715,7 +714,7 @@ Trigger event ### Parameters -* `event` **[string][5]** Event to trigger +* `event` **[string][6]** Event to trigger Returns **this** @@ -727,7 +726,7 @@ Destroy the editor Render editor -Returns **[HTMLElement][10]** +Returns **[HTMLElement][11]** ## html @@ -735,8 +734,8 @@ Print safe HTML by using ES6 tagged template strings. ### Parameters -* `literals` **[Array][8]<[String][5]>** -* `substs` **[Array][8]<[String][5]>** +* `literals` **[Array][9]<[String][6]>** +* `substs` **[Array][9]<[String][6]>** ### Examples @@ -747,30 +746,32 @@ const safeStr = 'Hello'; const strHtml = editor.html`Escaped ${unsafeStr}, unescaped $${safeStr}`; ``` -Returns **[String][5]** +Returns **[String][6]** [1]: https://github.com/artf/grapesjs/blob/master/src/editor/config/config.js -[2]: /api/device_manager.html +[2]: /api/modal_dialog.html + +[3]: /api/device_manager.html -[3]: /api/parser.html +[4]: /api/parser.html -[4]: /api/pages.html +[5]: /api/pages.html -[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String +[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String -[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object +[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object -[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean +[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean -[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array +[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array -[9]: em#setComponents +[10]: em#setComponents -[10]: https://developer.mozilla.org/docs/Web/HTML/Element +[11]: https://developer.mozilla.org/docs/Web/HTML/Element -[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function +[12]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function -[12]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number +[13]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number -[13]: https://github.com/artf/grapesjs/issues/1936 +[14]: https://github.com/artf/grapesjs/issues/1936 diff --git a/docs/api/modal_dialog.md b/docs/api/modal_dialog.md index 516c5eeb9..954c01945 100644 --- a/docs/api/modal_dialog.md +++ b/docs/api/modal_dialog.md @@ -18,6 +18,14 @@ Once the editor is instantiated you can use its API. Before using these methods const modal = editor.Modal; ``` +## Available Events + +* `modal:open` - Modal is opened +* `modal:close` - Modal is closed +* `modal` - Event triggered on any change related to the modal. An object containing all the available data about the triggered event is passed as an argument to the callback. + +## Methods + * [open][2] * [close][3] * [isOpen][4] @@ -40,12 +48,28 @@ Open the modal window * `opts.content` **([String][12] | [HTMLElement][13])?** Content to set for the modal * `opts.attributes` **[Object][11]?** Updates the modal wrapper with custom attributes +### Examples + +```javascript +modal.open({ + title: 'My title', + content: 'My content', + attributes: { class: 'my-class' }, +}); +``` + Returns **this** ## close Close the modal window +### Examples + +```javascript +modal.close(); +``` + Returns **this** ## onceClose @@ -55,7 +79,15 @@ The callback will be called one only time ### Parameters -* `clb` **[Function][14]** +* `clb` **[Function][14]** Callback to call + +### Examples + +```javascript +modal.onceClose(() => { + console.log('The modal is closed'); +}); +``` Returns **this** @@ -66,7 +98,15 @@ The callback will be called one only time ### Parameters -* `clb` **[Function][14]** +* `clb` **[Function][14]** Callback to call + +### Examples + +```javascript +modal.onceOpen(() => { + console.log('The modal is opened'); +}); +``` Returns **this** @@ -74,6 +114,12 @@ Returns **this** Checks if the modal window is open +### Examples + +```javascript +modal.isOpen(); // true | false +``` + Returns **[Boolean][15]** ## setTitle @@ -82,12 +128,17 @@ Set the title to the modal window ### Parameters -* `title` **[string][12]** Title +* `title` **([string][12] | [HTMLElement][13])** Title ### Examples ```javascript -modal.setTitle('New title'); +// pass a string +modal.setTitle('Some title'); +// or an HTMLElement +const el = document.createElement('div'); +el.innerText = 'New title'; +modal.setTitle(el); ``` Returns **this** @@ -96,7 +147,13 @@ Returns **this** Returns the title of the modal window -Returns **[string][12]** +### Examples + +```javascript +modal.getTitle(); +``` + +Returns **([string][12] | [HTMLElement][13])** ## setContent @@ -109,7 +166,12 @@ Set the content of the modal window ### Examples ```javascript -modal.setContent('
Some HTML content
'); +// pass a string +modal.setContent('Some content'); +// or an HTMLElement +const el = document.createElement('div'); +el.innerText = 'New content'; +modal.setContent(el); ``` Returns **this** @@ -118,7 +180,13 @@ Returns **this** Get the content of the modal window -Returns **[string][12]** +### Examples + +```javascript +modal.getContent(); +``` + +Returns **([string][12] | [HTMLElement][13])** [1]: https://github.com/artf/grapesjs/blob/master/src/modal_dialog/config/config.js diff --git a/src/editor/index.js b/src/editor/index.js index e810234d5..f11ed9f46 100644 --- a/src/editor/index.js +++ b/src/editor/index.js @@ -85,9 +85,6 @@ * ### RTE * * `rte:enable` - RTE enabled. The view, on which RTE is enabled, is passed as an argument * * `rte:disable` - RTE disabled. The view, on which RTE is disabled, is passed as an argument - * ### Modal - * * `modal:open` - Modal is opened - * * `modal:close` - Modal is closed * ### Commands * * `run:{commandName}` - Triggered when some command is called to run (eg. editor.runCommand('preview')) * * `stop:{commandName}` - Triggered when some command is called to stop (eg. editor.stopCommand('preview')) @@ -96,6 +93,8 @@ * * `abort:{commandName}` - Triggered when the command execution is aborted (`editor.on(`run:preview:before`, opts => opts.abort = 1);`) * * `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 + * ### Modal + * Check the [Modal](/api/modal_dialog.html) module. * ### Devices * Check the [Devices](/api/device_manager.html) module. * ### Parser diff --git a/src/modal_dialog/index.js b/src/modal_dialog/index.js index 97033f7dd..c1649c1b3 100644 --- a/src/modal_dialog/index.js +++ b/src/modal_dialog/index.js @@ -15,7 +15,9 @@ * ``` * * ## Available Events - * * `modal` - Generic + * * `modal:open` - Modal is opened + * * `modal:close` - Modal is closed + * * `modal` - Event triggered on any change related to the modal. An object containing all the available data about the triggered event is passed as an argument to the callback. * * ## Methods * * [open](#open) @@ -192,6 +194,8 @@ export default () => { /** * Returns the title of the modal window * @returns {string | HTMLElement} + * @example + * modal.getTitle(); */ getTitle() { return model.get('title');