From e0566c9f341ddd68e2c2002a5ebfd6fa33e04ffe Mon Sep 17 00:00:00 2001 From: Artur Arseniev Date: Thu, 2 Jun 2022 15:38:24 +0200 Subject: [PATCH] Update API docs --- docs/api.js | 16 +- docs/api/assets.md | 79 ++----- docs/api/block_manager.md | 6 +- docs/api/component.md | 388 ++++++++++++++++++---------------- docs/api/components.md | 104 +++------ docs/api/css_composer.md | 2 +- docs/api/css_rule.md | 83 ++++---- docs/api/editor.md | 86 +++++--- docs/api/pages.md | 44 ++-- docs/api/selector_manager.md | 28 +-- docs/api/storage_manager.md | 142 ++++++------- src/block_manager/index.js | 4 +- src/css_composer/index.js | 2 +- src/dom_components/index.ts | 2 +- src/selector_manager/index.ts | 2 +- src/storage_manager/index.js | 4 +- 16 files changed, 462 insertions(+), 530 deletions(-) diff --git a/docs/api.js b/docs/api.js index 2b9e636e8..81b53540f 100644 --- a/docs/api.js +++ b/docs/api.js @@ -17,7 +17,7 @@ async function generateDocs () { ['block_manager/index.js', 'block_manager.md'], ['block_manager/model/Block.js', 'block.md'], ['commands/index.js', 'commands.md'], - ['dom_components/index.js', 'components.md'], + ['dom_components/index.ts', 'components.md'], ['dom_components/model/Component.js', 'component.md'], ['panels/index.js', 'panels.md'], ['style_manager/index.js', 'style_manager.md'], @@ -46,8 +46,14 @@ async function generateDocs () { ['pages/index.ts', 'pages.md'], ['pages/model/Page.ts', 'page.md'], ['parser/index.js', 'parser.md'], - ].map(async (file) => - documentation.build([`${srcRoot}/${file[0]}`], { shallow: true }) + ].map(async (file) => { + const filePath = `${srcRoot}/${file[0]}`; + + if (!fs.existsSync(filePath)) { + throw `File not found '${filePath}'`; + } + + return documentation.build([filePath], { shallow: true }) .then(cm => documentation.formats.md(cm, /*{ markdownToc: true }*/)) .then(output => { const res = output @@ -60,8 +66,8 @@ async function generateDocs () { .replace('**Extends Model**', ''); fs.writeFileSync(`${docRoot}/api/${file[1]}`, res); log('Created', file[1]); - }) - )); + }); + })); log('API Reference generation done!'); }; diff --git a/docs/api/assets.md b/docs/api/assets.md index bbc3cffd1..175024446 100644 --- a/docs/api/assets.md +++ b/docs/api/assets.md @@ -42,9 +42,7 @@ const assetManager = editor.AssetManager; * [getAll][7] * [getAllVisible][8] * [remove][9] -* [store][10] -* [load][11] -* [getContainer][12] +* [getContainer][10] [Asset]: asset.html @@ -54,10 +52,10 @@ Open the asset manager. ### Parameters -* `options` **[Object][13]?** Options for the asset manager. (optional, default `{}`) +* `options` **[Object][11]?** Options for the asset manager. (optional, default `{}`) - * `options.types` **[Array][14]<[String][15]>** Types of assets to show. (optional, default `['image']`) - * `options.select` **[Function][16]?** Type of operation to perform on asset selection. If not specified, nothing will happen. + * `options.types` **[Array][12]<[String][13]>** Types of assets to show. (optional, default `['image']`) + * `options.select` **[Function][14]?** Type of operation to perform on asset selection. If not specified, nothing will happen. ### Examples @@ -97,7 +95,7 @@ Checks if the asset manager is open assetManager.isOpen(); // true | false ``` -Returns **[Boolean][17]** +Returns **[Boolean][15]** ## add @@ -105,8 +103,8 @@ Add new asset/s to the collection. URLs are supposed to be unique ### Parameters -* `asset` **([String][15] | [Object][13] | [Array][14]<[String][15]> | [Array][14]<[Object][13]>)** URL strings or an objects representing the resource. -* `opts` **[Object][13]?** Options (optional, default `{}`) +* `asset` **([String][13] | [Object][11] | [Array][12]<[String][13]> | [Array][12]<[Object][11]>)** URL strings or an objects representing the resource. +* `opts` **[Object][11]?** Options (optional, default `{}`) ### Examples @@ -133,7 +131,7 @@ Return asset by URL ### Parameters -* `src` **[String][15]** URL of the asset +* `src` **[String][13]** URL of the asset ### Examples @@ -161,7 +159,7 @@ Remove asset ### Parameters -* `asset` **([String][15] | [Asset])** Asset or asset URL +* `asset` **([String][13] | [Asset])** Asset or asset URL * `opts` ### Examples @@ -175,46 +173,11 @@ assetManager.remove(asset); Returns **[Asset]** Removed asset -## store - -Store assets data to the selected storage - -### Parameters - -* `noStore` **[Boolean][17]** If true, won't store - -### Examples - -```javascript -var assets = assetManager.store(); -``` - -Returns **[Object][13]** Data to store - -## load - -Load data from the passed object. -The fetched data will be added to the collection. - -### Parameters - -* `data` **[Object][13]** Object of data to load (optional, default `{}`) - -### Examples - -```javascript -var assets = assetManager.load({ - assets: [...] -}) -``` - -Returns **[Object][13]** Loaded assets - ## getContainer Return the Asset Manager Container -Returns **[HTMLElement][18]** +Returns **[HTMLElement][16]** ## render @@ -223,7 +186,7 @@ Render assets ### Parameters * `assts` -* `assets` **[array][14]** Assets to render, without the argument will render all global assets +* `assets` **[array][12]** Assets to render, without the argument will render all global assets ### Examples @@ -238,7 +201,7 @@ assetManager.render(assets.filter( )); ``` -Returns **[HTMLElement][18]** +Returns **[HTMLElement][16]** [1]: https://github.com/artf/grapesjs/blob/master/src/asset_manager/config/config.js @@ -258,20 +221,16 @@ Returns **[HTMLElement][18]** [9]: #remove -[10]: #store - -[11]: #load - -[12]: #getcontainer +[10]: #getcontainer -[13]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object +[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object -[14]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array +[12]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array -[15]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String +[13]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String -[16]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function +[14]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function -[17]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean +[15]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean -[18]: https://developer.mozilla.org/docs/Web/HTML/Element +[16]: https://developer.mozilla.org/docs/Web/HTML/Element diff --git a/docs/api/block_manager.md b/docs/api/block_manager.md index d703db3fe..48fbc81ea 100644 --- a/docs/api/block_manager.md +++ b/docs/api/block_manager.md @@ -1,6 +1,6 @@ -## BlockManager +## Blocks You can customize the initial state of the module from the editor initialization, by passing the following [Configuration Object][1] @@ -19,7 +19,7 @@ Once the editor is instantiated you can use its API and listen to its events. Be editor.on('block:add', (block) => { ... }); // Use the API -const blockManager = editor.BlockManager; +const blockManager = editor.Blocks; blockManager.add(...); ``` @@ -171,7 +171,7 @@ blockManager.render(); // Render new set of blocks const blocks = blockManager.getAll(); -const filtered = blocks.filter(block => block.get('category').id == 'Sections') +const filtered = blocks.filter(block => block.get('category') == 'sections') blockManager.render(filtered); // Or a new set from an array diff --git a/docs/api/component.md b/docs/api/component.md index c16ed54b1..1cb5ac2f6 100644 --- a/docs/api/component.md +++ b/docs/api/component.md @@ -19,50 +19,51 @@ component.get('tagName'); // -> 'span' ``` -[component]: component.html +[Component]: component.html ### Properties -- `type` **[String][1]?** Component type, eg. `text`, `image`, `video`, etc. -- `tagName` **[String][1]?** HTML tag of the component, eg. `span`. Default: `div` -- `attributes` **[Object][2]?** Key-value object of the component's attributes, eg. `{ title: 'Hello' }` Default: `{}` -- `name` **[String][1]?** Name of the component. Will be used, for example, in Layers and badges -- `removable` **[Boolean][3]?** When `true` the component is removable from the canvas, default: `true` -- `draggable` **([Boolean][3] | [String][1] | [Function][4])?** Indicates if it's possible to drag the component inside others. - You can also specify a query string to indentify elements, - eg. `'.some-class[title=Hello], [data-gjs-type=column]'` means you can drag the component only inside elements - containing `some-class` class and `Hello` title, and `column` components. In the case of a function, target and destination components are passed as arguments, return a Boolean to indicate if the drag is possible. Default: `true` -- `droppable` **([Boolean][3] | [String][1] | [Function][4])?** Indicates if it's possible to drop other components inside. You can use - a query string as with `draggable`. In the case of a function, target and destination components are passed as arguments, return a Boolean to indicate if the drop is possible. Default: `true` -- `badgable` **[Boolean][3]?** Set to false if you don't want to see the badge (with the name) over the component. Default: `true` -- `stylable` **([Boolean][3] | [Array][5]<[String][1]>)?** True if it's possible to style the component. - You can also indicate an array of CSS properties which is possible to style, eg. `['color', 'width']`, all other properties - will be hidden from the style manager. Default: `true` -- `stylable-require` **[Array][5]<[String][1]>?** Indicate an array of style properties to show up which has been marked as `toRequire`. Default: `[]` -- `unstylable` **[Array][5]<[String][1]>?** Indicate an array of style properties which should be hidden from the style manager. Default: `[]` -- `highlightable` **[Boolean][3]?** It can be highlighted with 'dotted' borders if true. Default: `true` -- `copyable` **[Boolean][3]?** True if it's possible to clone the component. Default: `true` -- `resizable` **[Boolean][3]?** Indicates if it's possible to resize the component. It's also possible to pass an object as [options for the Resizer][6]. Default: `false` -- `editable` **[Boolean][3]?** Allow to edit the content of the component (used on Text components). Default: `false` -- `layerable` **[Boolean][3]?** Set to `false` if you need to hide the component inside Layers. Default: `true` -- `selectable` **[Boolean][3]?** Allow component to be selected when clicked. Default: `true` -- `hoverable` **[Boolean][3]?** Shows a highlight outline when hovering on the element if `true`. Default: `true` -- `void` **[Boolean][3]?** This property is used by the HTML exporter as void elements don't have closing tags, eg. `
`, `
`, etc. Default: `false` -- `style` **[Object][2]?** Component default style, eg. `{ width: '100px', height: '100px', 'background-color': 'red' }` -- `styles` **[String][1]?** Component related styles, eg. `.my-component-class { color: red }` -- `content` **[String][1]?** Content of the component (not escaped) which will be appended before children rendering. Default: `''` -- `icon` **[String][1]?** Component's icon, this string will be inserted before the name (in Layers and badge), eg. it can be an HTML string ''. Default: `''` -- `script` **([String][1] | [Function][4])?** Component's javascript. More about it [here][7]. Default: `''` -- `script-export` **([String][1] | [Function][4])?** You can specify javascript available only in export functions (eg. when you get the HTML). - If this property is defined it will overwrite the `script` one (in export functions). Default: `''` -- `traits` **[Array][5]<([Object][2] | [String][1])>?** Component's traits. More about it [here][8]. Default: `['id', 'title']` -- `propagate` **[Array][5]<[String][1]>?** Indicates an array of properties which will be inhereted by all NEW appended children. - For example if you create a component likes this: `{ removable: false, draggable: false, propagate: ['removable', 'draggable'] }` - and append some new component inside, the new added component will get the exact same properties indicated in the `propagate` array (and the `propagate` property itself). Default: `[]` -- `toolbar` **[Array][5]<[Object][2]>?** Set an array of items to show up inside the toolbar when the component is selected (move, clone, delete). - Eg. `toolbar: [ { attributes: {class: 'fa fa-arrows'}, command: 'tlb-move' }, ... ]`. - By default, when `toolbar` property is falsy the editor will add automatically commands `core:component-exit` (select parent component, added if there is one), `tlb-move` (added if `draggable`) , `tlb-clone` (added if `copyable`), `tlb-delete` (added if `removable`). -- `components` **Collection<[Component][9]>?** Children components. Default: `null` +* `type` **[String][1]?** Component type, eg. `text`, `image`, `video`, etc. +* `tagName` **[String][1]?** HTML tag of the component, eg. `span`. Default: `div` +* `attributes` **[Object][2]?** Key-value object of the component's attributes, eg. `{ title: 'Hello' }` Default: `{}` +* `name` **[String][1]?** Name of the component. Will be used, for example, in Layers and badges +* `removable` **[Boolean][3]?** When `true` the component is removable from the canvas, default: `true` +* `draggable` **([Boolean][3] | [String][1] | [Function][4])?** Indicates if it's possible to drag the component inside others. + You can also specify a query string to indentify elements, + eg. `'.some-class[title=Hello], [data-gjs-type=column]'` means you can drag the component only inside elements + containing `some-class` class and `Hello` title, and `column` components. In the case of a function, target and destination components are passed as arguments, return a Boolean to indicate if the drag is possible. Default: `true` +* `droppable` **([Boolean][3] | [String][1] | [Function][4])?** Indicates if it's possible to drop other components inside. You can use + a query string as with `draggable`. In the case of a function, target and destination components are passed as arguments, return a Boolean to indicate if the drop is possible. Default: `true` +* `badgable` **[Boolean][3]?** Set to false if you don't want to see the badge (with the name) over the component. Default: `true` +* `stylable` **([Boolean][3] | [Array][5]<[String][1]>)?** True if it's possible to style the component. + You can also indicate an array of CSS properties which is possible to style, eg. `['color', 'width']`, all other properties + will be hidden from the style manager. Default: `true` +* `stylable-require` **[Array][5]<[String][1]>?** Indicate an array of style properties to show up which has been marked as `toRequire`. Default: `[]` +* `unstylable` **[Array][5]<[String][1]>?** Indicate an array of style properties which should be hidden from the style manager. Default: `[]` +* `highlightable` **[Boolean][3]?** It can be highlighted with 'dotted' borders if true. Default: `true` +* `copyable` **[Boolean][3]?** True if it's possible to clone the component. Default: `true` +* `resizable` **[Boolean][3]?** Indicates if it's possible to resize the component. It's also possible to pass an object as [options for the Resizer][6]. Default: `false` +* `editable` **[Boolean][3]?** Allow to edit the content of the component (used on Text components). Default: `false` +* `layerable` **[Boolean][3]?** Set to `false` if you need to hide the component inside Layers. Default: `true` +* `selectable` **[Boolean][3]?** Allow component to be selected when clicked. Default: `true` +* `hoverable` **[Boolean][3]?** Shows a highlight outline when hovering on the element if `true`. Default: `true` +* `locked` **[Boolean][3]?** Disable the selection of the component and its children in the canvas. Default: `false` +* `void` **[Boolean][3]?** This property is used by the HTML exporter as void elements don't have closing tags, eg. `
`, `
`, etc. Default: `false` +* `style` **[Object][2]?** Component default style, eg. `{ width: '100px', height: '100px', 'background-color': 'red' }` +* `styles` **[String][1]?** Component related styles, eg. `.my-component-class { color: red }` +* `content` **[String][1]?** Content of the component (not escaped) which will be appended before children rendering. Default: `''` +* `icon` **[String][1]?** Component's icon, this string will be inserted before the name (in Layers and badge), eg. it can be an HTML string ''. Default: `''` +* `script` **([String][1] | [Function][4])?** Component's javascript. More about it [here][7]. Default: `''` +* `script-export` **([String][1] | [Function][4])?** You can specify javascript available only in export functions (eg. when you get the HTML). + If this property is defined it will overwrite the `script` one (in export functions). Default: `''` +* `traits` **[Array][5]<([Object][2] | [String][1])>?** Component's traits. More about it [here][8]. Default: `['id', 'title']` +* `propagate` **[Array][5]<[String][1]>?** Indicates an array of properties which will be inhereted by all NEW appended children. + For example if you create a component likes this: `{ removable: false, draggable: false, propagate: ['removable', 'draggable'] }` + and append some new component inside, the new added component will get the exact same properties indicated in the `propagate` array (and the `propagate` property itself). Default: `[]` +* `toolbar` **[Array][5]<[Object][2]>?** Set an array of items to show up inside the toolbar when the component is selected (move, clone, delete). + Eg. `toolbar: [ { attributes: {class: 'fa fa-arrows'}, command: 'tlb-move' }, ... ]`. + By default, when `toolbar` property is falsy the editor will add automatically commands `core:component-exit` (select parent component, added if there is one), `tlb-move` (added if `draggable`) , `tlb-clone` (added if `copyable`), `tlb-delete` (added if `removable`). +* `components` **Collection<[Component][9]>?** Children components. Default: `null` ### init @@ -74,9 +75,9 @@ Hook method, called when the model has been updated (eg. updated some model's pr #### Parameters -- `property` **[String][1]** Property name, if triggered after some property update -- `value` **any** Property value, if triggered after some property update -- `previous` **any** Property previous value, if triggered after some property update +* `property` **[String][1]** Property name, if triggered after some property update +* `value` **any** Property value, if triggered after some property update +* `previous` **any** Property previous value, if triggered after some property update ### removed @@ -88,28 +89,28 @@ Check component's type #### Parameters -- `type` **[string][1]** Component type +* `type` **[string][1]** Component type #### Examples ```javascript -component.is("image"); +component.is('image') // -> false ``` -Returns **[Boolean][3]** +Returns **[Boolean][3]** ### props Return all the propeties -Returns **[Object][2]** +Returns **[Object][2]** ### index Get the index of the component in the parent collection. -Returns **[Number][10]** +Returns **[Number][10]** ### setDragMode @@ -118,9 +119,9 @@ To get more about this feature read: [https://github.com/artf/grapesjs/issues/19 #### Parameters -- `value` **[String][1]** Drag mode, options: 'absolute' | 'translate' +* `value` **[String][1]** Drag mode, options: 'absolute' | 'translate' -Returns **this** +Returns **this** ### find @@ -129,12 +130,12 @@ Find inner components by query string. #### Parameters -- `query` **[String][1]** Query string +* `query` **[String][1]** Query string #### Examples ```javascript -component.find("div > .class"); +component.find('div > .class'); // -> [Component, Component, ...] ``` @@ -148,16 +149,16 @@ also before rendering the component #### Parameters -- `type` **[String][1]** Component type +* `type` **[String][1]** Component type #### Examples ```javascript -const allImages = component.findType("image"); -console.log(allImages[0]); // prints the first found component +const allImages = component.findType('image'); +console.log(allImages[0]) // prints the first found component ``` -Returns **[Array][5]<[Component][9]>** +Returns **[Array][5]<[Component][9]>** ### closest @@ -166,16 +167,16 @@ Find the closest parent component by query string. #### Parameters -- `query` **[string][1]** Query string +* `query` **[string][1]** Query string #### Examples ```javascript -component.closest("div.some-class"); +component.closest('div.some-class'); // -> Component ``` -Returns **[Component][9]** +Returns **[Component][9]** ### closestType @@ -185,12 +186,12 @@ also before rendering the component #### Parameters -- `type` **[String][1]** Component type +* `type` **[String][1]** Component type #### Examples ```javascript -const Section = component.closestType("section"); +const Section = component.closestType('section'); console.log(Section); ``` @@ -203,9 +204,9 @@ component is a descendant of a given component #### Parameters -- `component` **[Component][9]** Component to check +* `component` **[Component][9]** Component to check -Returns **[Boolean][3]** +Returns **[Boolean][3]** ### replaceWith @@ -213,12 +214,12 @@ Replace a component with another one #### Parameters -- `el` **([String][1] | [Component][9])** Component or HTML string +* `el` **([String][1] | [Component][9])** Component or HTML string #### Examples ```javascript -component.replaceWith("
Some new content
"); +component.replaceWith('
Some new content
'); // -> Component ``` @@ -230,17 +231,17 @@ Update attributes of the component #### Parameters -- `attrs` **[Object][2]** Key value attributes -- `opts` (optional, default `{}`) -- `options` **[Object][2]** Options for the model update +* `attrs` **[Object][2]** Key value attributes +* `opts` (optional, default `{}`) +* `options` **[Object][2]** Options for the model update #### Examples ```javascript -component.setAttributes({ id: "test", "data-key": "value" }); +component.setAttributes({ id: 'test', 'data-key': 'value' }); ``` -Returns **this** +Returns **this** ### addAttributes @@ -248,17 +249,17 @@ Add attributes to the component #### Parameters -- `attrs` **[Object][2]** Key value attributes -- `opts` (optional, default `{}`) -- `options` **[Object][2]** Options for the model update +* `attrs` **[Object][2]** Key value attributes +* `opts` (optional, default `{}`) +* `options` **[Object][2]** Options for the model update #### Examples ```javascript -component.addAttributes({ "data-key": "value" }); +component.addAttributes({ 'data-key': 'value' }); ``` -Returns **this** +Returns **this** ### removeAttributes @@ -266,18 +267,18 @@ Remove attributes from the component #### Parameters -- `attrs` **([String][1] | [Array][5]<[String][1]>)** Array of attributes to remove (optional, default `[]`) -- `opts` (optional, default `{}`) -- `options` **[Object][2]** Options for the model update +* `attrs` **([String][1] | [Array][5]<[String][1]>)** Array of attributes to remove (optional, default `[]`) +* `opts` (optional, default `{}`) +* `options` **[Object][2]** Options for the model update #### Examples ```javascript -component.removeAttributes("some-attr"); -component.removeAttributes(["some-attr1", "some-attr2"]); +component.removeAttributes('some-attr'); +component.removeAttributes(['some-attr1', 'some-attr2']); ``` -Returns **this** +Returns **this** ### getStyle @@ -285,10 +286,10 @@ Get the style of the component #### Parameters -- `options` (optional, default `{}`) -- `optsAdd` (optional, default `{}`) +* `options` (optional, default `{}`) +* `optsAdd` (optional, default `{}`) -Returns **[Object][2]** +Returns **[Object][2]** ### setStyle @@ -296,16 +297,16 @@ Set the style on the component #### Parameters -- `prop` **[Object][2]** Key value style object (optional, default `{}`) -- `opts` (optional, default `{}`) +* `prop` **[Object][2]** Key value style object (optional, default `{}`) +* `opts` (optional, default `{}`) #### Examples ```javascript -component.setStyle({ color: "red" }); +component.setStyle({ color: 'red' }); ``` -Returns **[Object][2]** +Returns **[Object][2]** ### getAttributes @@ -313,9 +314,9 @@ Return all component's attributes #### Parameters -- `opts` (optional, default `{}`) +* `opts` (optional, default `{}`) -Returns **[Object][2]** +Returns **[Object][2]** ### addClass @@ -323,14 +324,14 @@ Add classes #### Parameters -- `classes` **([Array][5]<[String][1]> | [String][1])** Array or string of classes +* `classes` **([Array][5]<[String][1]> | [String][1])** Array or string of classes #### Examples ```javascript -model.addClass("class1"); -model.addClass("class1 class2"); -model.addClass(["class1", "class2"]); +model.addClass('class1'); +model.addClass('class1 class2'); +model.addClass(['class1', 'class2']); // -> [SelectorObject, ...] ``` @@ -342,14 +343,14 @@ Set classes (resets current collection) #### Parameters -- `classes` **([Array][5]<[String][1]> | [String][1])** Array or string of classes +* `classes` **([Array][5]<[String][1]> | [String][1])** Array or string of classes #### Examples ```javascript -model.setClass("class1"); -model.setClass("class1 class2"); -model.setClass(["class1", "class2"]); +model.setClass('class1'); +model.setClass('class1 class2'); +model.setClass(['class1', 'class2']); // -> [SelectorObject, ...] ``` @@ -361,14 +362,14 @@ Remove classes #### Parameters -- `classes` **([Array][5]<[String][1]> | [String][1])** Array or string of classes +* `classes` **([Array][5]<[String][1]> | [String][1])** Array or string of classes #### Examples ```javascript -model.removeClass("class1"); -model.removeClass("class1 class2"); -model.removeClass(["class1", "class2"]); +model.removeClass('class1'); +model.removeClass('class1 class2'); +model.removeClass(['class1', 'class2']); // -> [SelectorObject, ...] ``` @@ -378,7 +379,7 @@ Returns **[Array][5]** Array of removed selectors Returns component's classes as an array of strings -Returns **[Array][5]** +Returns **[Array][5]** ### append @@ -386,16 +387,16 @@ Add new component children #### Parameters -- `components` **([Component][9] | [String][1])** Component to add -- `opts` **[Object][2]** Options for the append action (optional, default `{}`) +* `components` **([Component][9] | [String][1])** Component to add +* `opts` **[Object][2]** Options for the append action (optional, default `{}`) #### Examples ```javascript -someComponent.get("components").length; // -> 0 -const videoComponent = someComponent.append("
")[0]; +someComponent.get('components').length // -> 0 +const videoComponent = someComponent.append('
')[0]; // This will add 2 components (`video` and `div`) to your `someComponent` -someComponent.get("components").length; // -> 2 +someComponent.get('components').length // -> 2 // You can pass components directly otherComponent.append(otherComponent2); otherComponent.append([otherComponent3, otherComponent4]); @@ -412,21 +413,21 @@ current collection is returned #### Parameters -- `components` **([Component][9] | [String][1])?** Component Definitions or HTML string -- `opts` **[Object][2]** Options, same as in `Component.append()` (optional, default `{}`) +* `components` **([Component][9] | [Array][5]<[Component][9]> | [String][1])?** Component Definitions or HTML string +* `opts` **[Object][2]** Options, same as in `Component.append()` (optional, default `{}`) #### Examples ```javascript // Set new collection -component.components("
"); +component.components('
'); // Get current collection const collection = component.components(); console.log(collection.length); // -> 2 ``` -Returns **(Collection | [Array][5]<[[Component][9]]>)** +Returns **(Collection | [Array][5]<[[Component][9]]>)** ### getChildAt @@ -434,7 +435,7 @@ If exists, returns the child component at specific index. #### Parameters -- `index` **[Number][10]** Index of the component to return +* `index` **[Number][10]** Index of the component to return #### Examples @@ -445,7 +446,7 @@ component.getChildAt(0); component.getChildAt(1); ``` -Returns **([[Component][9]] | null)** +Returns **([[Component][9]] | null)** ### getLastChild @@ -457,17 +458,17 @@ If exists, returns the last child component. const lastChild = component.getLastChild(); ``` -Returns **([[Component][9]] | null)** +Returns **([[Component][9]] | null)** ### empty Remove all inner components -- @return {this} +* @return {this} #### Parameters -- `opts` (optional, default `{}`) +* `opts` (optional, default `{}`) ### parent @@ -475,7 +476,7 @@ Get the parent component, if exists #### Parameters -- `opts` (optional, default `{}`) +* `opts` (optional, default `{}`) #### Examples @@ -484,7 +485,7 @@ component.parent(); // -> Component ``` -Returns **([Component][9] | null)** +Returns **([Component][9] | null)** ### getTraits @@ -498,7 +499,7 @@ console.log(traits); // [Trait, Trait, Trait, ...] ``` -Returns **[Array][5]\** +Returns **[Array][5]\** ### setTraits @@ -506,7 +507,7 @@ Replace current collection of traits with a new one. #### Parameters -- `traits` **[Array][5]<[Object][2]>** Array of trait definitions +* `traits` **[Array][5]<[Object][2]>** Array of trait definitions #### Examples @@ -516,7 +517,7 @@ console.log(traits); // [Trait, ...] ``` -Returns **[Array][5]\** +Returns **[Array][5]\** ### getTrait @@ -524,13 +525,13 @@ Get the trait by id/name. #### Parameters -- `id` **[String][1]** The `id` or `name` of the trait +* `id` **[String][1]** The `id` or `name` of the trait #### Examples ```javascript -const traitTitle = component.getTrait("title"); -traitTitle && traitTitle.set("label", "New label"); +const traitTitle = component.getTrait('title'); +traitTitle && traitTitle.set('label', 'New label'); ``` Returns **(Trait | null)** Trait getModelToStyle @@ -541,19 +542,19 @@ Update a trait. #### Parameters -- `id` **[String][1]** The `id` or `name` of the trait -- `props` **[Object][2]** Object with the props to update +* `id` **[String][1]** The `id` or `name` of the trait +* `props` **[Object][2]** Object with the props to update #### Examples ```javascript -component.updateTrait("title", { - type: "select", - options: ["Option 1", "Option 2"], +component.updateTrait('title', { + type: 'select', + options: [ 'Option 1', 'Option 2' ], }); ``` -Returns **this** +Returns **this** ### getTraitIndex @@ -562,12 +563,12 @@ replace some trait, at runtime, with something else. #### Parameters -- `id` **[String][1]** The `id` or `name` of the trait +* `id` **[String][1]** The `id` or `name` of the trait #### Examples ```javascript -const traitTitle = component.getTraitIndex("title"); +const traitTitle = component.getTraitIndex('title'); console.log(traitTitle); // 1 ``` @@ -579,13 +580,13 @@ Remove trait/s by id/s. #### Parameters -- `id` **([String][1] | [Array][5]<[String][1]>)** The `id`/`name` of the trait (or an array) +* `id` **([String][1] | [Array][5]<[String][1]>)** The `id`/`name` of the trait (or an array) #### Examples ```javascript -component.removeTrait("title"); -component.removeTrait(["title", "id"]); +component.removeTrait('title'); +component.removeTrait(['title', 'id']); ``` Returns **[Array][5]\** Array of removed traits @@ -596,8 +597,8 @@ Add new trait/s. #### Parameters -- `trait` **([String][1] | [Object][2] | [Array][5]<([String][1] | [Object][2])>)** Trait to add (or an array of traits) -- `opts` **Options** Options for the add (optional, default `{}`) +* `trait` **([String][1] | [Object][2] | [Array][5]<([String][1] | [Object][2])>)** Trait to add (or an array of traits) +* `opts` **Options** Options for the add (optional, default `{}`) #### Examples @@ -616,13 +617,13 @@ Returns **[Array][5]\** Array of added traits Get the name of the component -Returns **[String][1]** +Returns **[String][1]** ### getIcon Get the icon string -Returns **[String][1]** +Returns **[String][1]** ### toHTML @@ -630,34 +631,34 @@ Return HTML string of the component #### Parameters -- `opts` **[Object][2]** Options (optional, default `{}`) +* `opts` **[Object][2]** Options (optional, default `{}`) - - `opts.tag` **[String][1]?** Custom tagName - - `opts.attributes` **([Object][2] | [Function][4])** You can pass an object of custom attributes to replace with the current ones or you can even pass a function to generate attributes dynamically. (optional, default `null`) - - `opts.withProps` **[Boolean][3]?** Include component properties as `data-gjs-*` attributes. This allows you to have re-importable HTML. - - `opts.altQuoteAttr` **[Boolean][3]?** In case the attribute value contains a `"` char, instead of escaping it (`attr="value ""`), the attribute will be quoted using single quotes (`attr='value "'`). + * `opts.tag` **[String][1]?** Custom tagName + * `opts.attributes` **([Object][2] | [Function][4])** You can pass an object of custom attributes to replace with the current ones or you can even pass a function to generate attributes dynamically. (optional, default `null`) + * `opts.withProps` **[Boolean][3]?** Include component properties as `data-gjs-*` attributes. This allows you to have re-importable HTML. + * `opts.altQuoteAttr` **[Boolean][3]?** In case the attribute value contains a `"` char, instead of escaping it (`attr="value ""`), the attribute will be quoted using single quotes (`attr='value "'`). #### Examples ```javascript // Simple HTML return -component.set({ tagName: "span" }); -component.setAttributes({ title: "Hello" }); +component.set({ tagName: 'span' }); +component.setAttributes({ title: 'Hello' }); component.toHTML(); // -> // Custom attributes -component.toHTML({ attributes: { "data-test": "Hello" } }); +component.toHTML({ attributes: { 'data-test': 'Hello' } }); // -> // Custom dynamic attributes component.toHTML({ - attributes(component, attributes) { - if (component.get("tagName") == "span") { - attributes.title = "Custom attribute"; - } - return attributes; - }, + attributes(component, attributes) { + if (component.get('tagName') == 'span') { + attributes.title = 'Custom attribute'; + } + return attributes; + }, }); // -> ``` @@ -670,7 +671,7 @@ Get inner HTML of the component #### Parameters -- `opts` **[Object][2]** Same options of `toHTML` (optional, default `{}`) +* `opts` **[Object][2]** Same options of `toHTML` (optional, default `{}`) Returns **[String][1]** HTML string @@ -680,13 +681,13 @@ Return an object containing only changed props #### Parameters -- `res` +* `res` ### getId Return the component id -Returns **[String][1]** +Returns **[String][1]** ### setId @@ -694,10 +695,10 @@ Set new id on the component #### Parameters -- `id` **[String][1]** -- `opts` +* `id` **[String][1]** +* `opts` -Returns **this** +Returns **this** ### getEl @@ -706,9 +707,9 @@ This works only if the component is already rendered #### Parameters -- `frame` **Frame** Specific frame from which taking the element +* `frame` **Frame** Specific frame from which taking the element (optional, default `undefined`) -Returns **[HTMLElement][12]** +Returns **[HTMLElement][12]** ### getView @@ -717,9 +718,9 @@ This works only if the component is already rendered #### Parameters -- `frame` **Frame** Get View of a specific frame +* `frame` **Frame** Get View of a specific frame -Returns **ComponentView** +Returns **ComponentView** ### onAll @@ -727,17 +728,17 @@ Execute callback function on itself and all inner components #### Parameters -- `clb` **[Function][4]** Callback function, the model is passed as an argument +* `clb` **[Function][4]** Callback function, the model is passed as an argument #### Examples ```javascript -component.onAll((component) => { - // do something with component -}); +component.onAll(component => { + // do something with component +}) ``` -Returns **this** +Returns **this** ### remove @@ -745,9 +746,9 @@ Remove the component #### Parameters -- `opts` (optional, default `{}`) +* `opts` (optional, default `{}`) -Returns **this** +Returns **this** ### move @@ -755,8 +756,8 @@ Move the component to another destination component #### Parameters -- `component` **[Component][9]** Destination component (so the current one will be appended as a child) -- `opts` **[Object][2]** Options for the append action (optional, default `{}`) +* `component` **[Component][9]** Destination component (so the current one will be appended as a child) +* `opts` **[Object][2]** Options for the append action (optional, default `{}`) #### Examples @@ -766,7 +767,7 @@ const dest = editor.getWrapper(); editor.getSelected().move(dest, { at: 0 }); ``` -Returns **this** +Returns **this** ### isInstanceOf @@ -774,20 +775,20 @@ Check if the component is an instance of some component type. #### Parameters -- `type` **[String][1]** Component type +* `type` **[String][1]** Component type #### Examples ```javascript // Add a new component type by extending an existing one -editor.Components.addType("text-ext", { extend: "text" }); +editor.Components.addType('text-ext', { extend: 'text' }); // Append a new component somewhere -const newTextExt = editor.getSelected().append({ type: "text-ext" })[0]; -newTextExt.isInstanceOf("text-ext"); // true -newTextExt.isInstanceOf("text"); // true +const newTextExt = editor.getSelected().append({ type: 'text-ext' })[0]; +newTextExt.isInstanceOf('text-ext'); // true +newTextExt.isInstanceOf('text'); // true ``` -Returns **[Boolean][3]** +Returns **[Boolean][3]** ### isChildOf @@ -795,32 +796,43 @@ Check if the component is a child of some other component (or component type) #### Parameters -- `component` **([[Component][9]] | [String][1])** Component parent to check. In case a string is passed, - the check will be performed on the component type. +* `component` **([[Component][9]] | [String][1])** Component parent to check. In case a string is passed, + the check will be performed on the component type. #### Examples ```javascript const newTextComponent = editor.getSelected().append({ - type: "text", - components: "My text here", + type: 'text', + components: 'My text here', })[0]; -const innerComponent = newTextComponent.find("b")[0]; +const innerComponent = newTextComponent.find('b')[0]; innerComponent.isChildOf(newTextComponent); // true -innerComponent.isChildOf("text"); // true +innerComponent.isChildOf('text'); // true ``` -Returns **[Boolean][3]** +Returns **[Boolean][3]** [1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String + [2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object + [3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean + [4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function + [5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array + [6]: https://github.com/artf/grapesjs/blob/master/src/utils/Resizer.js + [7]: /modules/Components-js.html + [8]: /modules/Traits.html + [9]: #component + [10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number + [11]: https://github.com/artf/grapesjs/issues/1936 + [12]: https://developer.mozilla.org/docs/Web/HTML/Element diff --git a/docs/api/components.md b/docs/api/components.md index c8e348fe8..0a565d3ac 100644 --- a/docs/api/components.md +++ b/docs/api/components.md @@ -50,34 +50,9 @@ cmp.addType(...); * [getComponents][3] * [addComponent][4] * [clear][5] -* [load][6] -* [store][7] -* [addType][8] -* [getType][9] -* [getTypes][10] -* [render][11] - -## load - -Load components from the passed object, if the object is empty will try to fetch them -autonomously from the selected storage -The fetched data will be added to the collection - -### Parameters - -* `data` **[Object][12]** Object of data to load (optional, default `''`) - -Returns **[Object][12]** Loaded data - -## store - -Store components on the selected storage - -### Parameters - -* `noStore` **[Boolean][13]** If true, won't store - -Returns **[Object][12]** Data to store +* [addType][6] +* [getType][7] +* [getTypes][8] ## getWrapper @@ -126,7 +101,7 @@ comp1Children.add([ wrapperChildren.remove(comp2); ``` -Returns **[Components][14]** Collection of components +Returns **[Components][9]** Collection of components ## addComponent @@ -135,20 +110,20 @@ as 'cmp.getComponents().add(...)' ### Parameters -* `component` **([Object][12] | Component | [Array][15]<[Object][12]>)** Component/s to add +* `component` **([Object][10] | Component | [Array][11]<[Object][10]>)** Component/s to add - * `component.tagName` **[string][16]** Tag name (optional, default `'div'`) - * `component.type` **[string][16]** Type of the component. Available: ''(default), 'text', 'image' (optional, default `''`) + * `component.tagName` **[string][12]** Tag name (optional, default `'div'`) + * `component.type` **[string][12]** Type of the component. Available: ''(default), 'text', 'image' (optional, default `''`) * `component.removable` **[boolean][13]** If component is removable (optional, default `true`) * `component.draggable` **[boolean][13]** If is possible to move the component around the structure (optional, default `true`) * `component.droppable` **[boolean][13]** If is possible to drop inside other components (optional, default `true`) * `component.badgable` **[boolean][13]** If the badge is visible when the component is selected (optional, default `true`) * `component.stylable` **[boolean][13]** If is possible to style component (optional, default `true`) * `component.copyable` **[boolean][13]** If is possible to copy\&paste the component (optional, default `true`) - * `component.content` **[string][16]** String inside component (optional, default `''`) - * `component.style` **[Object][12]** Style object (optional, default `{}`) - * `component.attributes` **[Object][12]** Attribute object (optional, default `{}`) -* `opt` **[Object][12]** the options object to be used by the \[Components.add][getComponents][3] method (optional, default `{}`) + * `component.content` **[string][12]** String inside component (optional, default `''`) + * `component.style` **[Object][10]** Style object (optional, default `{}`) + * `component.attributes` **[Object][10]** Attribute object (optional, default `{}`) +* `opt` **[Object][10]** the options object to be used by the \[Components.add][getComponents][14] method (optional, default `{}`) ### Examples @@ -165,16 +140,7 @@ var comp1 = cmp.addComponent({ }); ``` -Returns **(Component | [Array][15]\)** Component/s added - -## render - -Render and returns wrapper element with all components inside. -Once the wrapper is rendered, and it's what happens when you init the editor, -the all new components will be added automatically and property changes are all -updated immediately - -Returns **[HTMLElement][17]** +Returns **(Component | [Array][11]\)** Component/s added ## clear @@ -189,25 +155,25 @@ Returns **this** ## addType Add new component type. -Read more about this in [Define New Component][18] +Read more about this in [Define New Component][15] ### Parameters -* `type` **[string][16]** Component ID -* `methods` **[Object][12]** Component methods +* `type` **[string][12]** Component ID +* `methods` **[Object][10]** Component methods Returns **this** ## getType Get component type. -Read more about this in [Define New Component][18] +Read more about this in [Define New Component][15] ### Parameters -* `type` **[string][16]** Component ID +* `type` **[string][12]** Component ID -Returns **[Object][12]** Component type definition, eg. `{ model: ..., view: ... }` +Returns **[Object][10]** Component type definition, eg. `{ model: ..., view: ... }` ## removeType @@ -215,16 +181,16 @@ Remove component type ### Parameters -* `id` -* `type` **[string][16]** Component ID +* `id` **[string][12]** +* `type` **[string][12]** Component ID -Returns **([Object][12] | [undefined][19])** Removed component type, undefined otherwise +Returns **([Object][10] | [undefined][16])** Removed component type, undefined otherwise ## getTypes Return the array of all types -Returns **[Array][15]** +Returns **[Array][11]** [1]: https://github.com/artf/grapesjs/blob/master/src/dom_components/config/config.js @@ -236,30 +202,24 @@ Returns **[Array][15]** [5]: #clear -[6]: #load +[6]: #addtype -[7]: #store +[7]: #gettype -[8]: #addtype +[8]: #gettypes -[9]: #gettype +[9]: #components -[10]: #gettypes +[10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object -[11]: #render +[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array -[12]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object +[12]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String [13]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean -[14]: #components - -[15]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array - -[16]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String - -[17]: https://developer.mozilla.org/docs/Web/HTML/Element +[14]: getComponents -[18]: https://grapesjs.com/docs/modules/Components.html#define-new-component +[15]: https://grapesjs.com/docs/modules/Components.html#define-new-component -[19]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined +[16]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined diff --git a/docs/api/css_composer.md b/docs/api/css_composer.md index be54998ea..2482af354 100644 --- a/docs/api/css_composer.md +++ b/docs/api/css_composer.md @@ -1,6 +1,6 @@ -## CssComposer +## Css This module manages CSS rules in the canvas. You can customize the initial state of the module from the editor initialization, by passing the following [Configuration Object][1] diff --git a/docs/api/css_rule.md b/docs/api/css_rule.md index 4d829a6db..2f293d5fd 100644 --- a/docs/api/css_rule.md +++ b/docs/api/css_rule.md @@ -6,15 +6,15 @@ ### Properties -- `selectors` **[Array][1]\** Array of selectors -- `style` **[Object][2]** Object containing style definitions -- `selectorsAdd` **[String][3]?** Additional string css selectors -- `atRuleType` **[String][3]?** Type of at-rule, eg. `media`, 'font-face' -- `mediaText` **[String][3]?** At-rule value, eg. `(max-width: 1000px)` -- `singleAtRule` **[Boolean][4]?** This property is used only on at-rules, like 'page' or 'font-face', where the block containes only style declarations -- `state` **[String][3]?** State of the rule, eg: `hover`, `focused` -- `important` **([Boolean][4] | [Array][1]<[String][3]>)?** If true, sets `!important` on all properties. You can also pass an array to specify properties on which use important -- `stylable` **[Boolean][4]?** Indicates if the rule is stylable from the editor[Device]: device.html[State]: state.html[Component]: component.html +* `selectors` **[Array][1]\** Array of selectors +* `style` **[Object][2]** Object containing style definitions +* `selectorsAdd` **[String][3]?** Additional string css selectors +* `atRuleType` **[String][3]?** Type of at-rule, eg. `media`, 'font-face' +* `mediaText` **[String][3]?** At-rule value, eg. `(max-width: 1000px)` +* `singleAtRule` **[Boolean][4]?** This property is used only on at-rules, like 'page' or 'font-face', where the block containes only style declarations +* `state` **[String][3]?** State of the rule, eg: `hover`, `focused` +* `important` **([Boolean][4] | [Array][1]<[String][3]>)?** If true, sets `!important` on all properties. You can also pass an array to specify properties on which use important +* `stylable` **[Boolean][4]?** Indicates if the rule is stylable from the editor[Device]: device.html[State]: state.html[Component]: component.html ### getAtRule @@ -23,18 +23,14 @@ Returns the at-rule statement when exists, eg. `@media (...)`, `@keyframes` #### Examples ```javascript -const cssRule = editor.Css.setRule( - ".class1", - { color: "red" }, - { - atRuleType: "media", - atRuleParams: "(min-width: 500px)", - } -); +const cssRule = editor.Css.setRule('.class1', { color: 'red' }, { + atRuleType: 'media', + atRuleParams: '(min-width: 500px)' +}); cssRule.getAtRule(); // "@media (min-width: 500px)" ``` -Returns **[String][3]** +Returns **[String][3]** ### selectorsToString @@ -42,19 +38,19 @@ Return selectors of the rule as a string #### Parameters -- `opts` **[Object][2]?** Options (optional, default `{}`) +* `opts` **[Object][2]?** Options (optional, default `{}`) - - `opts.skipState` **[Boolean][4]?** Skip state from the result + * `opts.skipState` **[Boolean][4]?** Skip state from the result #### Examples ```javascript -const cssRule = editor.Css.setRule(".class1:hover", { color: "red" }); +const cssRule = editor.Css.setRule('.class1:hover', { color: 'red' }); cssRule.selectorsToString(); // ".class1:hover" cssRule.selectorsToString({ skipState: true }); // ".class1" ``` -Returns **[String][3]** +Returns **[String][3]** ### getDeclaration @@ -62,23 +58,19 @@ Get declaration block (without the at-rule statement) #### Parameters -- `opts` **[Object][2]** Options (same as in `selectorsToString`) (optional, default `{}`) +* `opts` **[Object][2]** Options (same as in `selectorsToString`) (optional, default `{}`) #### Examples ```javascript -const cssRule = editor.Css.setRule( - ".class1", - { color: "red" }, - { - atRuleType: "media", - atRuleParams: "(min-width: 500px)", - } -); -cssRule.getDeclaration(); // ".class1{color:red;}" +const cssRule = editor.Css.setRule('.class1', { color: 'red' }, { + atRuleType: 'media', + atRuleParams: '(min-width: 500px)' +}); +cssRule.getDeclaration() // ".class1{color:red;}" ``` -Returns **[String][3]** +Returns **[String][3]** ### getDevice @@ -91,7 +83,7 @@ const device = rule.getDevice(); console.log(device?.getName()); ``` -Returns **([Device] | null)** +Returns **([Device] | null)** ### getState @@ -104,7 +96,7 @@ const state = rule.getState(); console.log(state?.getLabel()); ``` -Returns **([State] | null)** +Returns **([State] | null)** ### getComponent @@ -117,7 +109,7 @@ const cmp = rule.getComponent(); console.log(cmp?.toHTML()); ``` -Returns **([Component] | null)** +Returns **([Component] | null)** ### toCSS @@ -125,25 +117,24 @@ Return the CSS string of the rule #### Parameters -- `opts` **[Object][2]** Options (same as in `getDeclaration`) (optional, default `{}`) +* `opts` **[Object][2]** Options (same as in `getDeclaration`) (optional, default `{}`) #### Examples ```javascript -const cssRule = editor.Css.setRule( - ".class1", - { color: "red" }, - { - atRuleType: "media", - atRuleParams: "(min-width: 500px)", - } -); -cssRule.toCSS(); // "@media (min-width: 500px){.class1{color:red;}}" +const cssRule = editor.Css.setRule('.class1', { color: 'red' }, { + atRuleType: 'media', + atRuleParams: '(min-width: 500px)' +}); +cssRule.toCSS() // "@media (min-width: 500px){.class1{color:red;}}" ``` Returns **[String][3]** CSS string [1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array + [2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object + [3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String + [4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean diff --git a/docs/api/editor.md b/docs/api/editor.md index e047b2b78..2711c7bac 100644 --- a/docs/api/editor.md +++ b/docs/api/editor.md @@ -90,10 +90,9 @@ Returns configuration object ### Parameters -* `prop` **[string][16]?** Property name +* `prop` **[string][16]?** -Returns **any** Returns the configuration object or -the value of the specified property +Returns **any** Returns the configuration object or the value of the specified property ## getHtml @@ -417,53 +416,64 @@ Returns **any** The return is defined by the command ## store -Store data to the current storage +Store data to the current storage. +This will reset the counter of changes (`editor.getDirtyCount()`). ### Parameters -* `clb` **[Function][22]** Callback function +* `options` **[Object][17]?** Storage options. -Returns **[Object][17]** Stored data +### Examples + +```javascript +const storedData = await editor.store(); +``` + +Returns **[Object][17]** Stored data. -## storeData +## load -Get the JSON data object, which could be stored and loaded back with `editor.loadData(json)` +Load data from the current storage. + +### Parameters + +* `options` **[Object][17]?** Storage options. ### Examples ```javascript -console.log(editor.storeData()); -// { pages: [...], styles: [...], ... } +const data = await editor.load(); ``` -Returns **[Object][17]** +Returns **[Object][17]** Loaded data. -## load +## getProjectData -Load data from the current storage +Get the JSON project data, which could be stored and loaded back with `editor.loadProjectData(json)` -### Parameters +### Examples -* `clb` **[Function][22]** Callback function +```javascript +console.log(editor.getProjectData()); +// { pages: [...], styles: [...], ... } +``` -Returns **[Object][17]** Stored data +Returns **[Object][17]** -## loadData +## loadProjectData -Load data from the JSON data object +Load data from the JSON project ### Parameters -* `data` **[Object][17]** Data to load +* `data` **[Object][17]** Project to load ### Examples ```javascript -editor.loadData({ pages: [...], styles: [...], ... }) +editor.loadProjectData({ pages: [...], styles: [...], ... }) ``` -Returns **[Object][17]** Loaded object - ## getContainer Returns container element. The one which was indicated as 'container' @@ -476,7 +486,11 @@ Returns **[HTMLElement][21]** Return the count of changes made to the content and not yet stored. This count resets at any `store()` -Returns **[number][23]** +Returns **[number][22]** + +## clearDirtyCount + +Reset the counter of changes. ## refresh @@ -488,7 +502,7 @@ refresh you'll get misleading position of tools ### Parameters -* `opts` +* `opts` **any?** * `options` **[Object][17]?** Options * `options.tools` **[Boolean][18]** Update the position of tools (eg. rich text editor, component highlighter, etc.) (optional, default `false`) @@ -514,7 +528,7 @@ editor.setCustomRte({ rte = new MyCustomRte(el, {}); // this depends on the Custom RTE API ... return rte; // return the RTE instance - }, + } // Disable the editor, called for example when you unfocus the Text Component disable: function(el, rte) { @@ -539,7 +553,7 @@ custom parser, pass `null` as the argument ### Parameters -* `parser` **([Function][22] | null)** Parser function +* `parser` **([Function][23] | null)** Parser function ### Examples @@ -600,7 +614,7 @@ Translate label ### Parameters -* `args` **...any** +* `args` **...[Array][19]\** * `key` **[String][16]** Label to translate * `opts` **[Object][17]?** Options for the translation @@ -614,7 +628,7 @@ editor.t('msg'); // use params editor.t('msg2', { params: { test: 'hello' } }); // custom local -editor.t('msg2', { params: { test: 'hello' }, l: 'it' }); +editor.t('msg2', { params: { test: 'hello' } l: 'it' }); ``` Returns **[String][16]** @@ -626,7 +640,7 @@ Attach event ### Parameters * `event` **[string][16]** Event name -* `callback` **[Function][22]** Callback function +* `callback` **[Function][23]** Callback function Returns **this** @@ -637,7 +651,7 @@ Attach event and detach it after the first run ### Parameters * `event` **[string][16]** Event name -* `callback` **[Function][22]** Callback function +* `callback` **[Function][23]** Callback function Returns **this** @@ -648,7 +662,7 @@ Detach event ### Parameters * `event` **[string][16]** Event name -* `callback` **[Function][22]** Callback function +* `callback` **[Function][23]** Callback function Returns **this** @@ -658,6 +672,8 @@ Trigger event ### Parameters +* `eventName` **[string][16]** +* `args` **...[Array][19]\** * `event` **[string][16]** Event to trigger Returns **this** @@ -679,7 +695,7 @@ The callback will be executed immediately if the method is called on the already ### Parameters -* `clb` **[Function][22]** Callback to trigger +* `clb` **[Function][23]** Callback to trigger ### Examples @@ -704,7 +720,7 @@ Print safe HTML by using ES6 tagged template strings. const unsafeStr = ''; const safeStr = 'Hello'; // Use `$${var}` to avoid escaping -const strHtml = editor.html`Escaped ${unsafeStr}, unescaped $${safeStr}`; +const strHtml = editor.html`Escaped ${unsafeStr} unescaped $${safeStr}`; ``` Returns **[String][16]** @@ -751,8 +767,8 @@ Returns **[String][16]** [21]: https://developer.mozilla.org/docs/Web/HTML/Element -[22]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function +[22]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number -[23]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number +[23]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function [24]: https://github.com/artf/grapesjs/issues/1936 diff --git a/docs/api/pages.md b/docs/api/pages.md index 2044a18aa..bd1ce1826 100644 --- a/docs/api/pages.md +++ b/docs/api/pages.md @@ -48,14 +48,26 @@ const pageManager = editor.Pages; [Component]: component.html +## getAll + +Get all pages + +### Examples + +```javascript +const arrayOfPages = pageManager.getAll(); +``` + +Returns **[Array][9]<[Page]>** + ## add Add new page ### Parameters -* `props` **[Object][9]** Page properties -* `opts` **[Object][9]?** Options (optional, default `{}`) +* `props` **[Object][10]** Page properties +* `opts` **[Object][10]?** Options (optional, default `{}`) ### Examples @@ -75,8 +87,8 @@ Remove page ### Parameters -* `page` **([String][10] | [Page])** Page or page id -* `opts` (optional, default `{}`) +* `page` **([String][11] | [Page])** Page or page id +* `opts` **any** (optional, default `{}`) ### Examples @@ -95,7 +107,7 @@ Get page by id ### Parameters -* `id` **[String][10]** Page id +* `id` **[String][11]** Page id ### Examples @@ -117,18 +129,6 @@ const mainPage = pageManager.getMain(); Returns **[Page]** -## getAll - -Get all pages - -### Examples - -```javascript -const arrayOfPages = pageManager.getAll(); -``` - -Returns **[Array][11]<[Page]>** - ## getAllWrappers Get wrapper components (aka body) from all pages and frames. @@ -141,7 +141,7 @@ const wrappers = pageManager.getAllWrappers(); const allImages = wrappers.map(wrp => wrp.findType('image')).flat(); ``` -Returns **[Array][11]<[Component]>** +Returns **[Array][9]<[Component]>** ## select @@ -149,7 +149,7 @@ Change the selected page. This will switch the page rendered in canvas ### Parameters -* `page` **([String][10] | [Page])** Page or page id +* `page` **([String][11] | [Page])** Page or page id * `opts` (optional, default `{}`) ### Examples @@ -191,8 +191,8 @@ Returns **[Page]** [8]: #getselected -[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object +[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array -[10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String +[10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object -[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array +[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String diff --git a/docs/api/selector_manager.md b/docs/api/selector_manager.md index ddddca450..dc39edb2b 100644 --- a/docs/api/selector_manager.md +++ b/docs/api/selector_manager.md @@ -1,6 +1,6 @@ -## SelectorManager +## Selectors Selectors in GrapesJS are used in CSS Composer inside Rules and in Components as classes. To illustrate this concept let's take a look at this code: @@ -115,7 +115,7 @@ Get the selector by its name/type ### Parameters * `name` **[String][18]** Selector name or string identifier -* `type` +* `type` **[number][19]?** ### Examples @@ -134,7 +134,7 @@ Remove Selector. ### Parameters * `selector` **([String][18] | [Selector])** Selector instance or Selector string identifier -* `opts` +* `opts` **any?** ### Examples @@ -172,7 +172,7 @@ Returns **[String][18]** Get states -Returns **[Array][19]<[State]>** +Returns **[Array][20]<[State]>** ## setStates @@ -180,8 +180,8 @@ Set a new collection of states ### Parameters -* `states` **[Array][19]<[Object][17]>** Array of new states -* `opts` +* `states` **[Array][20]<[Object][17]>** Array of new states +* `opts` **any?** ### Examples @@ -192,7 +192,7 @@ const states = selectorManager.setStates([ ]); ``` -Returns **[Array][19]<[State]>** +Returns **[Array][20]<[State]>** ## getSelected @@ -205,7 +205,7 @@ const selected = selectorManager.getSelected(); console.log(selected.map(s => s.toString())) ``` -Returns **[Array][19]<[Selector]>** +Returns **[Array][20]<[Selector]>** ## addSelected @@ -246,7 +246,7 @@ const targetsToStyle = selectorManager.getSelectedTargets(); console.log(targetsToStyle.map(target => target.getSelectorsString())) ``` -Returns **[Array][19]<([Component] | [CssRule])>** +Returns **[Array][20]<([Component] | [CssRule])>** ## setComponentFirst @@ -256,13 +256,13 @@ of selectors (which would change styles on all components with those classes). ### Parameters -* `value` **[Boolean][20]** +* `value` **[Boolean][21]** ## getComponentFirst Get the value of component-first option. -Returns **[Boolean][20]** +Returns **[Boolean][21]** ## getAll @@ -306,6 +306,8 @@ Returns **Collection<[Selector]>** [18]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String -[19]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array +[19]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number -[20]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean +[20]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array + +[21]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean diff --git a/docs/api/storage_manager.md b/docs/api/storage_manager.md index 35345c839..ba3ec1aaa 100644 --- a/docs/api/storage_manager.md +++ b/docs/api/storage_manager.md @@ -1,6 +1,6 @@ -## StorageManager +## Storage You can customize the initial state of the module from the editor initialization, by passing the following [Configuration Object][1] @@ -19,7 +19,7 @@ Once the editor is instantiated you can use its API and listen to its events. Be editor.on('storage:start', () => { ... }); // Use the API -const storageManager = editor.StorageManager; +const storageManager = editor.Storage; storageManager.add(...); ``` @@ -48,133 +48,128 @@ storageManager.add(...); * [getCurrent][8] * [getCurrentStorage][9] * [setCurrent][10] -* [add][11] -* [get][12] -* [store][13] -* [load][14] +* [getStorageOptions][11] +* [add][12] +* [get][13] +* [store][14] +* [load][15] ## getConfig Get configuration object -Returns **[Object][15]** +Returns **[Object][16]** ## isAutosave -Checks if autosave is enabled +Check if autosave is enabled. -Returns **[Boolean][16]** +Returns **[Boolean][17]** ## setAutosave -Set autosave value +Set autosave value. ### Parameters -* `v` **[Boolean][16]** - -Returns **this** +* `value` **[Boolean][17]** ## getStepsBeforeSave -Returns number of steps required before trigger autosave +Returns number of steps required before trigger autosave. -Returns **[number][17]** +Returns **[Number][18]** ## setStepsBeforeSave -Set steps required before trigger autosave +Set steps required before trigger autosave. ### Parameters -* `v` **[number][17]** - -Returns **this** +* `value` **[Number][18]** ## add -Add new storage +Add new storage. ### Parameters -* `id` **[string][18]** Storage ID -* `storage` **[Object][15]** Storage wrapper +* `type` **[String][19]** Storage type +* `storage` **[Object][16]** Storage definition - * `storage.load` **[Function][19]** Load method - * `storage.store` **[Function][19]** Store method + * `storage.load` **[Function][20]** Load method + * `storage.store` **[Function][20]** Store method ### Examples ```javascript storageManager.add('local2', { - load: function(keys, clb, clbErr) { - var res = {}; - for (var i = 0, len = keys.length; i < len; i++){ - var v = localStorage.getItem(keys[i]); - if(v) res[keys[i]] = v; - } - clb(res); // might be called inside some async method - // In case of errors... - // clbErr('Went something wrong'); + async load(storageOptions) { + // ... + }, + async store(data, storageOptions) { + // ... }, - store: function(data, clb, clbErr) { - for(var key in data) - localStorage.setItem(key, data[key]); - clb(); // might be called inside some async method - } }); ``` -Returns **this** - ## get -Returns storage by id +Return storage by type. ### Parameters -* `id` **[string][18]** Storage ID +* `type` **[String][19]** Storage type -Returns **([Object][15] | null)** +Returns **([Object][16] | null)** ## getStorages -Returns all storages +Get all storages. -Returns **[Array][20]** +Returns **[Object][16]** ## getCurrent -Returns current storage type +Get current storage type. -Returns **[string][18]** +Returns **[String][19]** ## setCurrent -Set current storage type +Set current storage type. ### Parameters -* `id` **[string][18]** Storage ID +* `type` **[String][19]** Storage type -Returns **this** +## getStorageOptions + +Get storage options by type. + +### Parameters + +* `type` **[String][19]** Storage type + +Returns **[Object][16]** ## store -Store key-value resources in the current storage +Store data in the current storage. ### Parameters -* `data` **[Object][15]** Data in key-value format, eg. {item1: value1, item2: value2} -* `clb` **[Function][19]** Callback function +* `data` **[Object][16]** Project data. +* `options` **[Object][16]?** Storage options. (optional, default `{}`) ### Examples ```javascript -storageManager.store({item1: value1, item2: value2}); +const data = editor.getProjectData(); +await storageManager.store(data); ``` -Returns **([Object][15] | null)** +Returns **[Object][16]** Stored data. ## load @@ -182,25 +177,16 @@ Load resource from the current storage by keys ### Parameters -* `keys` **([string][18] | [Array][20]<[string][18]>)** Keys to load -* `clb` **[Function][19]** Callback function +* `options` **[Object][16]?** Storage options. (optional, default `{}`) ### Examples ```javascript -storageManager.load(['item1', 'item2'], res => { - // res -> {item1: value1, item2: value2} -}); -storageManager.load('item1', res => { -// res -> {item1: value1} -}); +const data = await storageManager.load(); +editor.loadProjectData(data); ``` -## getCurrentStorage - -Get current storage - -Returns **Storage** +Returns **[Object][16]** Loaded data. [1]: https://github.com/artf/grapesjs/blob/master/src/storage_manager/config/config.js @@ -222,22 +208,22 @@ Returns **Storage** [10]: #setcurrent -[11]: #add +[11]: #getstorageoptions -[12]: #get +[12]: #add -[13]: #store +[13]: #get -[14]: #load +[14]: #store -[15]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object +[15]: #load -[16]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean +[16]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object -[17]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number +[17]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean -[18]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String +[18]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number -[19]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function +[19]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String -[20]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array +[20]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function diff --git a/src/block_manager/index.js b/src/block_manager/index.js index 9d6dd8bf0..87fe2bd3e 100644 --- a/src/block_manager/index.js +++ b/src/block_manager/index.js @@ -15,7 +15,7 @@ * editor.on('block:add', (block) => { ... }); * * // Use the API - * const blockManager = editor.BlockManager; + * const blockManager = editor.Blocks; * blockManager.add(...); * ``` * @@ -42,7 +42,7 @@ * [Block]: block.html * [Component]: component.html * - * @module BlockManager + * @module Blocks */ import { isElement, isArray } from 'underscore'; import Module from '../abstract/moduleLegacy'; diff --git a/src/css_composer/index.js b/src/css_composer/index.js index 729b5d7a7..d9cce44cd 100644 --- a/src/css_composer/index.js +++ b/src/css_composer/index.js @@ -24,7 +24,7 @@ * * [CssRule]: css_rule.html * - * @module CssComposer + * @module Css */ import { isArray, isString, isUndefined } from 'underscore'; diff --git a/src/dom_components/index.ts b/src/dom_components/index.ts index d9d2d516a..3045df1ef 100644 --- a/src/dom_components/index.ts +++ b/src/dom_components/index.ts @@ -47,7 +47,6 @@ * * [addType](#addtype) * * [getType](#gettype) * * [getTypes](#gettypes) - * * [render](#render) * * @module Components */ @@ -392,6 +391,7 @@ export default class ComponentManager extends ItemManagerModule { * the all new components will be added automatically and property changes are all * updated immediately * @return {HTMLElement} + * @private */ render() { return this.componentView?.render().el; diff --git a/src/selector_manager/index.ts b/src/selector_manager/index.ts index 617350775..71f3db900 100644 --- a/src/selector_manager/index.ts +++ b/src/selector_manager/index.ts @@ -69,7 +69,7 @@ * [Component]: component.html * [CssRule]: css_rule.html * - * @module SelectorManager + * @module Selectors */ import { isString, debounce, isObject, isArray } from 'underscore'; diff --git a/src/storage_manager/index.js b/src/storage_manager/index.js index efc9b60b4..293ade241 100644 --- a/src/storage_manager/index.js +++ b/src/storage_manager/index.js @@ -15,7 +15,7 @@ * editor.on('storage:start', () => { ... }); * * // Use the API - * const storageManager = editor.StorageManager; + * const storageManager = editor.Storage; * storageManager.add(...); * ``` * @@ -48,7 +48,7 @@ * * [store](#store) * * [load](#load) * - * @module StorageManager + * @module Storage */ import Module from '../abstract/moduleLegacy';