Browse Source

Update Parser docs

pull/3691/head
Artur Arseniev 5 years ago
parent
commit
aea6abe1bb
  1. 1
      docs/.vuepress/config.js
  2. 1
      docs/api.js
  3. 4
      docs/api/assets.md
  4. 2
      docs/api/component.md
  5. 193
      docs/api/editor.md
  6. 96
      docs/api/parser.md
  7. 15
      src/parser/index.js

1
docs/.vuepress/config.js

@ -77,6 +77,7 @@ module.exports = {
['/api/rich_text_editor', 'Rich Text Editor'], ['/api/rich_text_editor', 'Rich Text Editor'],
['/api/keymaps', 'Keymaps'], ['/api/keymaps', 'Keymaps'],
['/api/undo_manager', 'Undo Manager'], ['/api/undo_manager', 'Undo Manager'],
['/api/parser', 'Parser'],
], ],
'/': [ '/': [
'', '',

1
docs/api.js

@ -25,6 +25,7 @@ const cmds = [
['i18n/index.js', 'i18n.md'], ['i18n/index.js', 'i18n.md'],
['pages/index.js', 'pages.md'], ['pages/index.js', 'pages.md'],
['pages/model/Page.js', 'page.md'], ['pages/model/Page.js', 'page.md'],
['parser/index.js', 'parser.md'],
].map(entry => ].map(entry =>
`${binRoot}documentation build ${srcRoot}/${entry[0]} -o ${docRoot}/api/${entry[1]} -f md --shallow --markdown-toc false`) `${binRoot}documentation build ${srcRoot}/${entry[0]} -o ${docRoot}/api/${entry[1]} -f md --shallow --markdown-toc false`)
.join(' && '); .join(' && ');

4
docs/api/assets.md

@ -160,8 +160,8 @@ Render assets
### Parameters ### Parameters
* `assets` **[array][16]** Assets to render, without the argument will render * `assts`
all global assets * `assets` **[array][16]** Assets to render, without the argument will render all global assets
### Examples ### Examples

2
docs/api/component.md

@ -2,6 +2,8 @@
## Component ## Component
**Extends Model.extend(Styleable)**
The Component object represents a single node of our template structure, so when you update its properties the changes are The Component object represents a single node of our template structure, so when you update its properties the changes are
immediately reflected on the canvas and in the code to export (indeed, when you ask to export the code we just go through all immediately reflected on the canvas and in the code to export (indeed, when you ask to export the code we just go through all
the tree of nodes). the tree of nodes).

193
docs/api/editor.md

@ -113,11 +113,6 @@ By changing `result.content` you're able to customize what is dropped
* `modal:open` - Modal is opened * `modal:open` - Modal is opened
* `modal:close` - Modal is closed * `modal:close` - Modal is closed
### Parser
* `parse:html` - On HTML parse, an object containing the input and the output of the parser is passed as an argument
* `parse:css` - On CSS parse, an object containing the input and the output of the parser is passed as an argument
### Commands ### Commands
* `run:{commandName}` - Triggered when some command is called to run (eg. editor.runCommand('preview')) * `run:{commandName}` - Triggered when some command is called to run (eg. editor.runCommand('preview'))
@ -128,9 +123,13 @@ 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 * `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 * `stop` - Triggered on stop of any command. The id and the result are passed as arguments to the callback
### Parser
Check the [Parser][2] module.
### Pages ### Pages
Check the [Pages][2] module. Check the [Pages][3] module.
### General ### General
@ -146,7 +145,7 @@ Returns configuration object
### Parameters ### Parameters
* `prop` **[string][3]?** Property name * `prop` **[string][4]?** Property name
Returns **any** Returns the configuration object or Returns **any** Returns the configuration object or
the value of the specified property the value of the specified property
@ -157,11 +156,12 @@ Returns HTML built inside canvas
### Parameters ### Parameters
* `opts` **[Object][4]** Options (optional, default `{}`) * `opts` **[Object][5]** Options (optional, default `{}`)
* `opts.cleanId` **[Boolean][5]** Remove unnecessary IDs (eg. those created automatically) (optional, default `false`) * `opts.component` **Component?** Return the HTML of a specific Component
* `opts.cleanId` **[Boolean][6]** Remove unnecessary IDs (eg. those created automatically) (optional, default `false`)
Returns **[string][3]** HTML string Returns **[string][4]** HTML string
## getCss ## getCss
@ -169,11 +169,13 @@ Returns CSS built inside canvas
### Parameters ### Parameters
* `opts` **[Object][4]** Options (optional, default `{}`) * `opts` **[Object][5]** Options (optional, default `{}`)
* `opts.avoidProtected` **[Boolean][5]** Don't include protected CSS (optional, default `false`) * `opts.component` **Component?** Return the CSS of a specific Component
* `opts.json` **[Boolean][6]** Return an array of CssRules instead of the CSS string (optional, default `false`)
* `opts.avoidProtected` **[Boolean][6]** Don't include protected CSS (optional, default `false`)
Returns **[string][3]** CSS string Returns **([String][4] | [Array][7]\<CssRule>)** CSS string or array of CssRules
## getJs ## getJs
@ -181,11 +183,11 @@ Returns JS of all components
### Parameters ### Parameters
* `opts` **[Object][4]** Options (optional, default `{}`) * `opts` **[Object][5]** Options (optional, default `{}`)
* `opts.component` **Component?** Get the JS of a particular component * `opts.component` **Component?** Get the JS of a specific component
Returns **[string][3]** JS string Returns **[String][4]** JS string
## getComponents ## getComponents
@ -205,8 +207,8 @@ Set components inside editor's canvas. This method overrides actual components
### Parameters ### Parameters
* `components` **([Array][6]<[Object][4]> | [Object][4] | [string][3])** HTML string or components model * `components` **([Array][7]<[Object][5]> | [Object][5] | [string][4])** HTML string or components model
* `opt` **[Object][4]** the options object to be used by the \[setComponents][em#setComponents][7] method (optional, default `{}`) * `opt` **[Object][5]** the options object to be used by the \[setComponents][em#setComponents][8] method (optional, default `{}`)
### Examples ### Examples
@ -228,10 +230,10 @@ Add components
### Parameters ### Parameters
* `components` **([Array][6]<[Object][4]> | [Object][4] | [string][3])** HTML string or components model * `components` **([Array][7]<[Object][5]> | [Object][5] | [string][4])** HTML string or components model
* `opts` **[Object][4]** Options * `opts` **[Object][5]** Options
* `opts.avoidUpdateStyle` **[Boolean][5]** If the HTML string contains styles, * `opts.avoidUpdateStyle` **[Boolean][6]** If the HTML string contains styles,
by default, they will be created and, if already exist, updated. When this option 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`) is true, styles already created will not be updated. (optional, default `false`)
@ -247,13 +249,13 @@ editor.addComponents({
}); });
``` ```
Returns **[Array][6]\<Component>** Returns **[Array][7]\<Component>**
## getStyle ## getStyle
Returns style in JSON format object Returns style in JSON format object
Returns **[Object][4]** Returns **[Object][5]**
## setStyle ## setStyle
@ -261,7 +263,7 @@ Set style inside editor's canvas. This method overrides actual style
### Parameters ### Parameters
* `style` **([Array][6]<[Object][4]> | [Object][4] | [string][3])** CSS string or style model * `style` **([Array][7]<[Object][5]> | [Object][5] | [string][4])** CSS string or style model
* `opt` (optional, default `{}`) * `opt` (optional, default `{}`)
### Examples ### Examples
@ -283,7 +285,7 @@ Add styles to the editor
### Parameters ### Parameters
* `style` **([Array][6]<[Object][4]> | [Object][4] | [string][3])** CSS string or style model * `style` **([Array][7]<[Object][5]> | [Object][5] | [string][4])** CSS string or style model
* `opts` (optional, default `{}`) * `opts` (optional, default `{}`)
### Examples ### Examples
@ -292,7 +294,7 @@ Add styles to the editor
editor.addStyle('.cls{color: red}'); editor.addStyle('.cls{color: red}');
``` ```
Returns **[Array][6]\<CssRule>** Array of created CssRule instances Returns **[Array][7]\<CssRule>** Array of created CssRule instances
## getSelected ## getSelected
@ -304,7 +306,7 @@ Returns **Model**
Returns an array of all selected components Returns an array of all selected components
Returns **[Array][6]** Returns **[Array][7]**
## getSelectedToStyle ## getSelectedToStyle
@ -322,10 +324,10 @@ Select a component
### Parameters ### Parameters
* `el` **(Component | [HTMLElement][8])** Component to select * `el` **(Component | [HTMLElement][9])** Component to select
* `opts` **[Object][4]?** Options * `opts` **[Object][5]?** Options
* `opts.scroll` **[Boolean][5]?** Scroll canvas to the selected element * `opts.scroll` **[Boolean][6]?** Scroll canvas to the selected element
### Examples ### Examples
@ -344,7 +346,7 @@ Add component to selection
### Parameters ### Parameters
* `el` **(Component | [HTMLElement][8] | [Array][6])** Component to select * `el` **(Component | [HTMLElement][9] | [Array][7])** Component to select
### Examples ### Examples
@ -360,7 +362,7 @@ Remove component from selection
### Parameters ### Parameters
* `el` **(Component | [HTMLElement][8] | [Array][6])** Component to select * `el` **(Component | [HTMLElement][9] | [Array][7])** Component to select
### Examples ### Examples
@ -376,7 +378,7 @@ Toggle component selection
### Parameters ### Parameters
* `el` **(Component | [HTMLElement][8] | [Array][6])** Component to select * `el` **(Component | [HTMLElement][9] | [Array][7])** Component to select
### Examples ### Examples
@ -408,7 +410,7 @@ change the canvas to the proper width
### Parameters ### Parameters
* `name` **[string][3]** Name of the device * `name` **[string][4]** Name of the device
### Examples ### Examples
@ -430,7 +432,7 @@ console.log(device);
// 'Tablet' // 'Tablet'
``` ```
Returns **[string][3]** Device name Returns **[string][4]** Device name
## runCommand ## runCommand
@ -438,8 +440,8 @@ Execute command
### Parameters ### Parameters
* `id` **[string][3]** Command ID * `id` **[string][4]** Command ID
* `options` **[Object][4]** Custom options (optional, default `{}`) * `options` **[Object][5]** Custom options (optional, default `{}`)
### Examples ### Examples
@ -455,8 +457,8 @@ Stop the command if stop method was provided
### Parameters ### Parameters
* `id` **[string][3]** Command ID * `id` **[string][4]** Command ID
* `options` **[Object][4]** Custom options (optional, default `{}`) * `options` **[Object][5]** Custom options (optional, default `{}`)
### Examples ### Examples
@ -472,9 +474,22 @@ Store data to the current storage
### Parameters ### Parameters
* `clb` **[Function][9]** Callback function * `clb` **[Function][10]** Callback function
Returns **[Object][5]** Stored data
## storeData
Get the JSON data object, which could be stored and loaded back with `editor.loadData(json)`
### Examples
```javascript
console.log(editor.storeData());
// { pages: [...], styles: [...], ... }
```
Returns **[Object][4]** Stored data Returns **[Object][5]**
## load ## load
@ -482,23 +497,39 @@ Load data from the current storage
### Parameters ### Parameters
* `clb` **[Function][9]** Callback function * `clb` **[Function][10]** Callback function
Returns **[Object][5]** Stored data
Returns **[Object][4]** Stored data ## loadData
Load data from the JSON data object
### Parameters
* `data` **[Object][5]** Data to load
### Examples
```javascript
editor.loadData({ pages: [...], styles: [...], ... })
```
Returns **[Object][5]** Loaded object
## getContainer ## getContainer
Returns container element. The one which was indicated as 'container' Returns container element. The one which was indicated as 'container'
on init method on init method
Returns **[HTMLElement][8]** Returns **[HTMLElement][9]**
## getDirtyCount ## getDirtyCount
Return the count of changes made to the content and not yet stored. Return the count of changes made to the content and not yet stored.
This count resets at any `store()` This count resets at any `store()`
Returns **[number][10]** Returns **[number][11]**
## refresh ## refresh
@ -511,9 +542,9 @@ refresh you'll get misleading position of tools
### Parameters ### Parameters
* `opts` * `opts`
* `options` **[Object][4]?** Options * `options` **[Object][5]?** Options
* `options.tools` **[Boolean][5]** Update the position of tools (eg. rich text editor, component highlighter, etc.) (optional, default `false`) * `options.tools` **[Boolean][6]** Update the position of tools (eg. rich text editor, component highlighter, etc.) (optional, default `false`)
## setCustomRte ## setCustomRte
@ -521,7 +552,7 @@ Replace the built-in Rich Text Editor with a custom one.
### Parameters ### Parameters
* `obj` **[Object][4]** Custom RTE Interface * `obj` **[Object][5]** Custom RTE Interface
### Examples ### Examples
@ -561,7 +592,7 @@ custom parser, pass `null` as the argument
### Parameters ### Parameters
* `parser` **([Function][9] | null)** Parser function * `parser` **([Function][10] | null)** Parser function
### Examples ### Examples
@ -583,11 +614,11 @@ Returns **this**
## setDragMode ## setDragMode
Change the global drag mode of components. Change the global drag mode of components.
To get more about this feature read: [https://github.com/artf/grapesjs/issues/1936][11] To get more about this feature read: [https://github.com/artf/grapesjs/issues/1936][12]
### Parameters ### Parameters
* `value` **[String][3]** Drag mode, options: 'absolute' | 'translate' * `value` **[String][4]** Drag mode, options: 'absolute' | 'translate'
Returns **this** Returns **this**
@ -598,10 +629,10 @@ Trigger event log message
### Parameters ### Parameters
* `msg` **any** Message to log * `msg` **any** Message to log
* `opts` **[Object][4]** Custom options (optional, default `{}`) * `opts` **[Object][5]** Custom options (optional, default `{}`)
* `opts.ns` **[String][3]** Namespace of the log (eg. to use in plugins) (optional, default `''`) * `opts.ns` **[String][4]** Namespace of the log (eg. to use in plugins) (optional, default `''`)
* `opts.level` **[String][3]** Level of the log, `debug`, `info`, `warning`, `error` (optional, default `'debug'`) * `opts.level` **[String][4]** Level of the log, `debug`, `info`, `warning`, `error` (optional, default `'debug'`)
### Examples ### Examples
@ -623,11 +654,11 @@ Translate label
### Parameters ### Parameters
* `args` **...any** * `args` **...any**
* `key` **[String][3]** Label to translate * `key` **[String][4]** Label to translate
* `opts` **[Object][4]?** Options for the translation * `opts` **[Object][5]?** Options for the translation
* `opts.params` **[Object][4]?** Params for the translation * `opts.params` **[Object][5]?** Params for the translation
* `opts.noWarn` **[Boolean][5]?** Avoid warnings in case of missing resources * `opts.noWarn` **[Boolean][6]?** Avoid warnings in case of missing resources
### Examples ### Examples
@ -639,7 +670,7 @@ editor.t('msg2', { params: { test: 'hello' } });
editor.t('msg2', { params: { test: 'hello' }, l: 'it' }); editor.t('msg2', { params: { test: 'hello' }, l: 'it' });
``` ```
Returns **[String][3]** Returns **[String][4]**
## on ## on
@ -647,8 +678,8 @@ Attach event
### Parameters ### Parameters
* `event` **[string][3]** Event name * `event` **[string][4]** Event name
* `callback` **[Function][9]** Callback function * `callback` **[Function][10]** Callback function
Returns **this** Returns **this**
@ -658,8 +689,8 @@ Attach event and detach it after the first run
### Parameters ### Parameters
* `event` **[string][3]** Event name * `event` **[string][4]** Event name
* `callback` **[Function][9]** Callback function * `callback` **[Function][10]** Callback function
Returns **this** Returns **this**
@ -669,8 +700,8 @@ Detach event
### Parameters ### Parameters
* `event` **[string][3]** Event name * `event` **[string][4]** Event name
* `callback` **[Function][9]** Callback function * `callback` **[Function][10]** Callback function
Returns **this** Returns **this**
@ -680,7 +711,7 @@ Trigger event
### Parameters ### Parameters
* `event` **[string][3]** Event to trigger * `event` **[string][4]** Event to trigger
Returns **this** Returns **this**
@ -692,7 +723,7 @@ Destroy the editor
Render editor Render editor
Returns **[HTMLElement][8]** Returns **[HTMLElement][9]**
## html ## html
@ -700,8 +731,8 @@ Print safe HTML by using ES6 tagged template strings.
### Parameters ### Parameters
* `literals` **[Array][6]<[String][3]>** * `literals` **[Array][7]<[String][4]>**
* `substs` **[Array][6]<[String][3]>** * `substs` **[Array][7]<[String][4]>**
### Examples ### Examples
@ -712,26 +743,28 @@ const safeStr = '<b>Hello</b>';
const strHtml = editor.html`Escaped ${unsafeStr}, unescaped $${safeStr}`; const strHtml = editor.html`Escaped ${unsafeStr}, unescaped $${safeStr}`;
``` ```
Returns **[String][3]** Returns **[String][4]**
[1]: https://github.com/artf/grapesjs/blob/master/src/editor/config/config.js [1]: https://github.com/artf/grapesjs/blob/master/src/editor/config/config.js
[2]: /api/pages.html [2]: /api/parser.html
[3]: /api/pages.html
[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String [4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object [5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean [6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array [7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
[7]: em#setComponents [8]: em#setComponents
[8]: https://developer.mozilla.org/docs/Web/HTML/Element [9]: https://developer.mozilla.org/docs/Web/HTML/Element
[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function [10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
[10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number [11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
[11]: https://github.com/artf/grapesjs/issues/1936 [12]: https://github.com/artf/grapesjs/issues/1936

96
docs/api/parser.md

@ -0,0 +1,96 @@
<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
## Parser
You can customize the initial state of the module from the editor initialization, by passing the following [Configuration Object][1]
```js
const editor = grapesjs.init({
parser: {
// options
}
})
```
Once the editor is instantiated you can use its API. Before using these methods you should get the module from the instance
```js
const { Parser } = editor;
```
## Available Events
* `parse:html` - On HTML parse, an object containing the input and the output of the parser is passed as an argument
* `parse:css` - On CSS parse, an object containing the input and the output of the parser is passed as an argument
## Methods
* [getConfig][2]
* [parseHtml][3]
* [parseCss][4]
## getConfig
Get the configuration object
### Examples
```javascript
console.log(parser.getConfig())
```
Returns **[Object][5]** Configuration object
## parseHtml
Parse HTML string and return the object containing the Component Definition
### Parameters
* `input` **[String][6]** HTML string to parse
* `opts` (optional, default `{}`)
* `options` **[Object][5]?** Options
* `options.htmlType` **[String][6]?** [HTML mime type][7] to parse
### Examples
```javascript
const resHtml = Parser.parseHtml(`<table><div>Hi</div></table>`, {
htmlType: 'text/html', // default
});
// By using the `text/html`, this will fix automatically all the HTML syntax issues
// Indeed the final rappresetnation, in this case, will be `<div>Hi</div><table></table>`
const resXml = Parser.parseHtml(`<table><div>Hi</div></table>`, {
htmlType: 'application/xml',
});
// This will preserve the original format as, from the XML point of view, is a valid format
```
Returns **[Object][5]** Object containing the result `{ html: ..., css: ... }`
## parseCss
Parse CSS string and return an array of valid definition objects for CSSRules
### Parameters
* `input` **[String][6]** CSS string to parse
Returns **[Array][8]<[Object][5]>** Array containing the result
[1]: https://github.com/artf/grapesjs/blob/master/src/parser/config/config.js
[2]: #getconfig
[3]: #parsehtml
[4]: #parsecss
[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
[7]: https://developer.mozilla.org/en-US/docs/Web/API/DOMParser/parseFromString
[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array

15
src/parser/index.js

@ -56,7 +56,7 @@ export default () => {
* Get the configuration object * Get the configuration object
* @returns {Object} Configuration object * @returns {Object} Configuration object
* @example * @example
* console.log(parser.getConfig()) * console.log(Parser.getConfig())
*/ */
getConfig() { getConfig() {
return conf; return conf;
@ -66,29 +66,32 @@ export default () => {
* Parse HTML string and return the object containing the Component Definition * Parse HTML string and return the object containing the Component Definition
* @param {String} input HTML string to parse * @param {String} input HTML string to parse
* @param {Object} [options] Options * @param {Object} [options] Options
* @param {String} [options.htmlType] [HTML mime type](https://developer.mozilla.org/en-US/docs/Web/API/DOMParser/parseFromString) to parse * @param {String} [options.htmlType] [HTML mime type](https://developer.mozilla.org/en-US/docs/Web/API/DOMParser/parseFromString#Argument02) to parse
* @returns {Object} Object containing the result `{ html: ..., css: ... }` * @returns {Object} Object containing the result `{ html: ..., css: ... }`
* @example * @example
* const resHtml = Parser.parseHtml(`<table><div>Hi</div></table>`, { * const resHtml = Parser.parseHtml(`<table><div>Hi</div></table>`, {
* htmlType: 'text/html', // default * htmlType: 'text/html', // default
* }); * });
* // By using the `text/html`, this will fix automatically all the HTML syntax issues * // By using the `text/html`, this will fix automatically all the HTML syntax issues
* // Indeed the final rappresetnation, in this case, will be `<div>Hi</div><table></table>` * // Indeed the final representation, in this case, will be `<div>Hi</div><table></table>`
* const resXml = Parser.parseHtml(`<table><div>Hi</div></table>`, { * const resXml = Parser.parseHtml(`<table><div>Hi</div></table>`, {
* htmlType: 'application/xml', * htmlType: 'application/xml',
* }); * });
* // This will preserve the original format as, from the XML point of view, is a valid format * // This will preserve the original format as, from the XML point of view, is a valid format
*/ */
parseHtml(input, opts = {}) { parseHtml(input, options = {}) {
const { em, compTypes } = this; const { em, compTypes } = this;
pHtml.compTypes = em ? em.get('DomComponents').getTypes() : compTypes; pHtml.compTypes = em ? em.get('DomComponents').getTypes() : compTypes;
return pHtml.parse(input, pCss, opts); return pHtml.parse(input, pCss, options);
}, },
/** /**
* Parse CSS string and return an array of valid definition objects for CSSRules * Parse CSS string and return an array of valid definition objects for CSSRules
* @param {String} input CSS string to parse * @param {String} input CSS string to parse
* @return {Array<Object>} Array containing the result * @returns {Array<Object>} Array containing the result
* @example
* const res = Parser.parseCss('.cls { color: red }');
* // [{ ... }]
*/ */
parseCss(input) { parseCss(input) {
return pCss.parse(input); return pCss.parse(input);

Loading…
Cancel
Save