From 20cce66d8cae2b30e90a95306547dfba60ae3c02 Mon Sep 17 00:00:00 2001 From: Artur Arseniev Date: Sun, 17 Sep 2023 15:37:43 +0400 Subject: [PATCH] Up docs --- docs/api.js | 3 +- docs/api/block_manager.md | 125 +++++++++++++++++++++---------------- docs/api/editor.md | 3 + src/block_manager/types.ts | 3 + 4 files changed, 78 insertions(+), 56 deletions(-) diff --git a/docs/api.js b/docs/api.js index 95f16f9377..f822750be1 100644 --- a/docs/api.js +++ b/docs/api.js @@ -14,7 +14,7 @@ const getEventsMdFromTypes = async (filePath) => { const dirname = filePath.replace(path.basename(filePath), ''); const typesFilePath = `${dirname}types.ts`; - if (fs.existsSync(typesFilePath) && typesFilePath.includes('canvas')) { + if (fs.existsSync(typesFilePath)) { const resTypes = await documentation.build([typesFilePath], { shallow: true }) .then(cm => documentation.formats.md(cm, /*{ markdownToc: true }*/)); const indexFrom = resTypes.indexOf(START_EVENTS) + START_EVENTS.length; @@ -26,6 +26,7 @@ const getEventsMdFromTypes = async (filePath) => { .replace(/## /gi, '* ') .replace(/\\`/gi, '`') .replace(/##/gi, '') + .replace(/\\\[/gi, '[') .trim(); return result diff --git a/docs/api/block_manager.md b/docs/api/block_manager.md index bb5055930b..e8f9383d34 100644 --- a/docs/api/block_manager.md +++ b/docs/api/block_manager.md @@ -24,26 +24,59 @@ blockManager.add(...); ``` ## Available Events +* `block:add` New block added to the collection. The [Block] is passed as an argument to the callback. -* `block:add` - Block added. The [Block] is passed as an argument to the callback. -* `block:remove` - Block removed. The [Block] is passed as an argument to the callback. -* `block:update` - Block updated. The [Block] and the object containing changes are passed as arguments to the callback. -* `block:drag:start` - Started dragging block, the [Block] is passed as an argument. -* `block:drag` - Dragging block, the [Block] is passed as an argument. -* `block:drag:stop` - Dragging of the block is stopped. The dropped [Component] (if dropped successfully) and the [Block] are passed as arguments. -* `block` - Catch-all event for all the events mentioned above. An object containing all the available data about the triggered event is passed as an argument to the callback. - -## Methods - -* [add][2] -* [get][3] -* [getAll][4] -* [getAllVisible][5] -* [remove][6] -* [getConfig][7] -* [getCategories][8] -* [getContainer][9] -* [render][10] +```javascript +editor.on('block:add', (block) => { ... }); +``` + +* `block:remove` Block removed from the collection. The [Block] is passed as an argument to the callback. + +```javascript +editor.on('block:remove', (block) => { ... }); +``` + +* `block:remove:before` Event triggered before Block remove. + +```javascript +editor.on('block:remove:before', (block, remove, opts) => { ... }); +``` + +* `block:update` Block updated. The [Block] and the object containing changes are passed as arguments to the callback. + +```javascript +editor.on('block:update', (block, updatedProps) => { ... }); +``` + +* `block:drag:start` Started dragging block. The [Block] is passed as an argument. + +```javascript +editor.on('block:drag:start', (block) => { ... }); +``` + +* `block:drag` The block is dragging. The [Block] is passed as an argument. + +```javascript +editor.on('block:drag', (block) => { ... }); +``` + +* `block:drag:stop` Dragging of the block is stopped. The dropped [Component] (if dropped successfully) and the [Block] are passed as arguments. + +```javascript +editor.on('block:drag:stop', (component, block) => { ... }); +``` + +* `block:custom` Event to use in case of [custom Block Manager UI]\(https://grapesjs.com/docs/modules/Blocks.html#customization). + +```javascript +editor.on('block:custom', ({ container, blocks, ... }) => { ... }); +``` + +* `block` Catch-all event for all the events mentioned above. An object containing all the available data about the triggered event is passed as an argument to the callback. + +```javascript +editor.on('block', ({ event, model, ... }) => { ... }); +``` [Block]: block.html @@ -53,7 +86,7 @@ blockManager.add(...); Get configuration object -Returns **[Object][11]** +Returns **[Object][2]** ## add @@ -61,7 +94,7 @@ Add new block. ### Parameters -* `id` **[String][12]** Block ID +* `id` **[String][3]** Block ID * `props` **[Block]** Block properties * `opts` (optional, default `{}`) @@ -86,7 +119,7 @@ Get the block by id. ### Parameters -* `id` **[String][12]** Block id +* `id` **[String][3]** Block id ### Examples @@ -124,7 +157,7 @@ Remove block. ### Parameters -* `block` **([String][12] | [Block])** Block or block ID +* `block` **([String][3] | [Block])** Block or block ID * `opts` (optional, default `{}`) ### Examples @@ -143,20 +176,20 @@ Returns **[Block]** Removed block Get all available categories. It's possible to add categories only within blocks via 'add()' method -Returns **([Array][13] | Collection)** +Returns **([Array][4] | Collection)** ## getContainer Return the Blocks container element -Returns **[HTMLElement][14]** +Returns **[HTMLElement][5]** ## getDragBlock Returns currently dragging block. Updated when the drag starts and cleared once it's done. -Returns **([Block] | [undefined][15])** +Returns **([Block] | [undefined][6])** ## render @@ -164,11 +197,11 @@ Render blocks ### Parameters -* `blocks` **[Array][13]** Blocks to render, without the argument will render all global blocks -* `opts` **[Object][11]** Options (optional, default `{}`) +* `blocks` **[Array][4]** Blocks to render, without the argument will render all global blocks +* `opts` **[Object][2]** Options (optional, default `{}`) - * `opts.external` **[Boolean][16]?** Render blocks in a new container (HTMLElement will be returned) - * `opts.ignoreCategories` **[Boolean][16]?** Render blocks without categories + * `opts.external` **[Boolean][7]?** Render blocks in a new container (HTMLElement will be returned) + * `opts.ignoreCategories` **[Boolean][7]?** Render blocks without categories ### Examples @@ -194,36 +227,18 @@ const newBlocksEl = blockManager.render(filtered, { external: true }); document.getElementById('some-id').appendChild(newBlocksEl); ``` -Returns **[HTMLElement][14]** Rendered element +Returns **[HTMLElement][5]** Rendered element [1]: https://github.com/GrapesJS/grapesjs/blob/master/src/block_manager/config/config.ts -[2]: #add - -[3]: #get - -[4]: #getall - -[5]: #getallvisible - -[6]: #remove - -[7]: #getconfig - -[8]: #getcategories - -[9]: #getcontainer - -[10]: #render - -[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object +[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object -[12]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String +[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String -[13]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array +[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array -[14]: https://developer.mozilla.org/docs/Web/HTML/Element +[5]: https://developer.mozilla.org/docs/Web/HTML/Element -[15]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined +[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined -[16]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean +[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean diff --git a/docs/api/editor.md b/docs/api/editor.md index 6382a81975..a3fc209fad 100644 --- a/docs/api/editor.md +++ b/docs/api/editor.md @@ -438,6 +438,9 @@ Load data from the current storage. ### Parameters * `options` **[Object][16]?** Storage options. +* `loadOptions` **[Object][16]** Load options. (optional, default `{}`) + + * `loadOptions.clear` **[Boolean][17]** Clear the editor state (eg. dirty counter, undo manager, etc.). (optional, default `false`) ### Examples diff --git a/src/block_manager/types.ts b/src/block_manager/types.ts index 9eabb70b28..260d28c347 100644 --- a/src/block_manager/types.ts +++ b/src/block_manager/types.ts @@ -64,3 +64,6 @@ export enum BlocksEvents { all = 'block', } /**{END_EVENTS}*/ + +// need this to avoid the TS documentation generator to break +export default BlocksEvents;