From 995b1ba385807f62ab3f41882bb4fe5cce0a52dc Mon Sep 17 00:00:00 2001 From: Artur Arseniev Date: Thu, 23 Apr 2020 01:46:38 +0200 Subject: [PATCH] Update API docs file --- docs/api/canvas.md | 32 +++++++++++++++++++ docs/api/component.md | 42 ++++++++++++++++++++++-- docs/api/editor.md | 8 ++++- docs/api/rich_text_editor.md | 26 +++++++++++++++ docs/api/selector_manager.md | 62 ++++++++++++++++++++++++++---------- docs/api/style_manager.md | 1 + docs/api/undo_manager.md | 22 +++++++++++++ 7 files changed, 173 insertions(+), 20 deletions(-) diff --git a/docs/api/canvas.md b/docs/api/canvas.md index 1b4886144..d43da98a8 100644 --- a/docs/api/canvas.md +++ b/docs/api/canvas.md @@ -140,6 +140,38 @@ Get zoom value Returns **[Number][21]** +## addFrame + +Add new frame to the canvas + +### Parameters + +- `props` **[Object][14]** Frame properties (optional, default `{}`) +- `opts` (optional, default `{}`) + +### Examples + +```javascript +editor.Canvas.addFrame({ +name: 'Mobile home page', +x: 100, // Position in canvas +y: 100, +width: 500, // Frame dimensions +height: 600, +// device: 'DEVICE-ID', +components: [ +'

Title frame

', +'

Paragraph frame

', +], +styles: ` +.testh { color: red; } +.testp { color: blue; } +`, +}); +``` + +Returns **Frame** + [1]: https://github.com/artf/grapesjs/blob/master/src/canvas/config/config.js [2]: #getconfig diff --git a/docs/api/component.md b/docs/api/component.md index 1f396fb08..e28098763 100644 --- a/docs/api/component.md +++ b/docs/api/component.md @@ -137,13 +137,13 @@ Returns **[Array][4]** Array of components ## findType -Find all inner components by component id. +Find all inner components by component type. The advantage of this method over `find` is that you can use it also before rendering the component ### Parameters -- `id` **[String][1]** Component id +- `type` **[String][1]** Component type ### Examples @@ -172,6 +172,25 @@ component.closest('div.some-class'); Returns **[Component][9]** +## closestType + +Find the closest parent component by its type. +The advantage of this method over `closest` is that you can use it +also before rendering the component + +### Parameters + +- `type` **[String][1]** Component type + +### Examples + +```javascript +const Section = component.closestType('section'); +console.log(Section); +``` + +Returns **[Component][9]** Found component, otherwise `undefined` + ## replaceWith Replace a component with another one @@ -359,6 +378,16 @@ console.log(collection.length); Returns **(Collection | [Array][4]<[Component][9]>)** +## empty + +Remove all inner components + +- @return {this} + +### Parameters + +- `opts` (optional, default `{}`) + ## parent Get the parent component, if exists @@ -485,6 +514,7 @@ Return HTML string of the component ### Parameters - `opts` **[Object][2]** Options (optional, default `{}`) + - `opts.tag` **[String][1]?** Custom tagName - `opts.attributes` **([Object][2] \| [Function][6])** You can pass an object of custom attributes to replace with the current one or you can even pass a function to generate attributes dynamically (optional, default `null`) @@ -537,6 +567,10 @@ Returns **this** Get the DOM element of the component. This works only if the component is already rendered +### Parameters + +- `frame` **Frame** Specific frame from which taking the element + Returns **[HTMLElement][12]** ## getView @@ -544,6 +578,10 @@ Returns **[HTMLElement][12]** Get the View of the component. This works only if the component is already rendered +### Parameters + +- `frame` **Frame** Get View of a specific frame + Returns **ComponentView** ## onAll diff --git a/docs/api/editor.md b/docs/api/editor.md index 9ef9a7bd6..af051b0ed 100644 --- a/docs/api/editor.md +++ b/docs/api/editor.md @@ -37,6 +37,9 @@ editor.on('EVENT-NAME', (some, argument) => { - `component:toggled` - Component selection changed, toggled model is passed as an argument to the callback - `component:type:add` - New component type added, the new type is passed as an argument to the callback - `component:type:update` - Component type updated, the updated type is passed as an argument to the callback +- `component:drag:start` - Component drag started. Passed an object, to the callback, containing the `target` (component to drag), `parent` (parent of the component) and `index` (component index in the parent) +- `component:drag` - During component drag. Passed the same object as in `component:drag:start` event, but in this case, `parent` and `index` are updated by the current pointer +- `component:drag:end` - Component drag ended. Passed the same object as in `component:drag:start` event, but in this case, `parent` and `index` are updated by the final pointer ### Blocks @@ -93,7 +96,10 @@ editor.on('EVENT-NAME', (some, argument) => { ### Selectors -- `selector:add` - Triggers when a new selector/class is created +- `selector:add` - New selector is add. Passes the new selector as an argument +- `selector:remove` - Selector removed. Passes the removed selector as an argument +- `selector:update` - Selector updated. Passes the updated selector as an argument +- `selector:state` - State changed. Passes the new state value as an argument ### RTE diff --git a/docs/api/rich_text_editor.md b/docs/api/rich_text_editor.md index 5c661cd41..06f1aa8e5 100644 --- a/docs/api/rich_text_editor.md +++ b/docs/api/rich_text_editor.md @@ -68,6 +68,32 @@ rte.add('fontSize', { } } }) +// An example with state +const isValidAnchor = (rte) => { + // a utility function to help determine if the selected is a valid anchor node + const anchor = rte.selection().anchorNode; + const parentNode = anchor && anchor.parentNode; + const nextSibling = anchor && anchor.nextSibling; + return (parentNode && parentNode.nodeName == 'A') || (nextSibling && nextSibling.nodeName == 'A') +} +rte.add('toggleAnchor', { + icon: `⫘`, + state: (rte, doc) => { + if (rte && rte.selection()) { + // `btnState` is a integer, -1 for disabled, 0 for inactive, 1 for active + return isValidAnchor(rte) ? btnState.ACTIVE : btnState.INACTIVE; + } else { + return btnState.INACTIVE; + } + }, + result: (rte, action) => { + if (isValidAnchor(rte)) { + rte.exec('unlink'); + } else { + rte.insertHTML(`${rte.selection()}`); + } + } +}) ``` ## get diff --git a/docs/api/selector_manager.md b/docs/api/selector_manager.md index 3f5f383de..417366aaa 100644 --- a/docs/api/selector_manager.md +++ b/docs/api/selector_manager.md @@ -46,12 +46,36 @@ const selectorManager = editor.SelectorManager; - [addClass][4] - [get][5] - [getAll][6] +- [setState][7] +- [getState][8] ## getConfig Get configuration object -Returns **[Object][7]** +Returns **[Object][9]** + +## setState + +Change the selector state + +### Parameters + +- `value` **[String][10]** State value + +### Examples + +```javascript +selectorManager.setState('hover'); +``` + +Returns **this** + +## getState + +Get the current selector state + +Returns **[String][10]** ## add @@ -59,10 +83,10 @@ Add a new selector to collection if it's not already exists. Class type is a def ### Parameters -- `name` **([String][8] \| [Array][9])** Selector/s name -- `opts` **[Object][7]** Selector options (optional, default `{}`) - - `opts.label` **[String][8]** Label for the selector, if it's not provided the label will be the same as the name (optional, default `''`) - - `opts.type` **[String][8]** Type of the selector. At the moment, only 'class' (1) is available (optional, default `1`) +- `name` **([String][10] \| [Array][11])** Selector/s name +- `opts` **[Object][9]** Selector options (optional, default `{}`) + - `opts.label` **[String][10]** Label for the selector, if it's not provided the label will be the same as the name (optional, default `''`) + - `opts.type` **[String][10]** Type of the selector. At the moment, only 'class' (1) is available (optional, default `1`) ### Examples @@ -77,7 +101,7 @@ const selector = selectorManager.add('selectorName', { const selectors = selectorManager.add(['.class1', '.class2', '#id1']); ``` -Returns **(Model | [Array][9])** +Returns **(Model | [Array][11])** ## addClass @@ -85,7 +109,7 @@ Add class selectors ### Parameters -- `classes` **([Array][9] \| [string][8])** Array or string of classes +- `classes` **([Array][11] \| [string][10])** Array or string of classes ### Examples @@ -96,7 +120,7 @@ sm.addClass(['class1', 'class2']); // -> [SelectorObject, ...] ``` -Returns **[Array][9]** Array of added selectors +Returns **[Array][11]** Array of added selectors ## get @@ -104,8 +128,8 @@ Get the selector by its name ### Parameters -- `name` **([String][8] \| [Array][9])** Selector name -- `type` **[String][8]** Selector type +- `name` **([String][10] \| [Array][11])** Selector name +- `type` **[String][10]** Selector type ### Examples @@ -115,7 +139,7 @@ const selector = selectorManager.get('selectorName'); const selectors = selectorManager.get(['class1', 'class2']); ``` -Returns **(Model | [Array][9])** +Returns **(Model | [Array][11])** ## getAll @@ -129,9 +153,9 @@ Return escaped selector name ### Parameters -- `name` **[String][8]** Selector name to escape +- `name` **[String][10]** Selector name to escape -Returns **[String][8]** Escaped name +Returns **[String][10]** Escaped name [1]: https://github.com/artf/grapesjs/blob/master/src/selector_manager/config/config.js @@ -143,10 +167,14 @@ Returns **[String][8]** Escaped name [5]: #get -[6]: #getAll +[6]: #getall + +[7]: #setstate + +[8]: #getstate -[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object +[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object -[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String +[10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String -[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array +[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array diff --git a/docs/api/style_manager.md b/docs/api/style_manager.md index 2d735f0ae..08f4aa30f 100644 --- a/docs/api/style_manager.md +++ b/docs/api/style_manager.md @@ -214,6 +214,7 @@ one or more classes, the function will return the corresponding CSS Rule ### Parameters - `model` **Model** +- `options` (optional, default `{}`) Returns **Model** diff --git a/docs/api/undo_manager.md b/docs/api/undo_manager.md index 3304715c3..9ee446b25 100644 --- a/docs/api/undo_manager.md +++ b/docs/api/undo_manager.md @@ -110,6 +110,10 @@ Returns **this** Undo last change +### Parameters + +- `all` (optional, default `true`) + ### Examples ```javascript @@ -134,6 +138,10 @@ Returns **this** Redo last change +### Parameters + +- `all` (optional, default `true`) + ### Examples ```javascript @@ -191,6 +199,18 @@ stack.each(item => ...); Returns **Collection** +## getStackGroup + +Get grouped undo manager stack. +The difference between `getStack` is when you do multiple operations at a time, +like appending multiple components: +`editor.getWrapper().append(`
C1
C2
`);` +`getStack` will return a collection length of 2. + `getStackGroup` instead will group them as a single operation (the first +inserted component will be returned in the list) by returning an array length of 1. + +Returns **[Array][17]** + ## clear Clear the stack @@ -234,3 +254,5 @@ Returns **this** [15]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object [16]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean + +[17]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array