From de59e0693025194e028db83ff8eb87f4ef89a7e0 Mon Sep 17 00:00:00 2001 From: Artur Arseniev Date: Mon, 21 Oct 2024 16:24:47 +0400 Subject: [PATCH] Up docs (#6236) --- docs/.vuepress/config.js | 4 +- docs/api.mjs | 2 +- docs/api/block.md | 6 ++ docs/api/canvas.md | 34 +++++++ docs/api/datasources.md | 159 ++++++++++++++++++++++++++++++ docs/getting-started.md | 8 +- docs/package.json | 2 +- package.json | 5 +- packages/core/src/canvas/index.ts | 16 ++- 9 files changed, 225 insertions(+), 11 deletions(-) create mode 100644 docs/api/datasources.md diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 7aaef1e64..f83ff0fec 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -103,7 +103,7 @@ module.exports = { ['/api/keymaps', 'Keymaps'], ['/api/undo_manager', 'Undo Manager'], ['/api/parser', 'Parser'], - ['/api/data_source_manager', 'Data Source Manager'], + ['/api/datasources', 'Data Sources'], ['/api/datasource', `${subDivider}DataSource`], ['/api/datarecord', `${subDivider}DataRecord`], ], @@ -129,7 +129,7 @@ module.exports = { ['/modules/Storage', 'Storage Manager'], ['/modules/Modal', 'Modal'], ['/modules/Plugins', 'Plugins'], - ['/modules/DataSources', 'Data Sources'], + // ['/modules/DataSources', 'Data Sources'], ], }, { diff --git a/docs/api.mjs b/docs/api.mjs index 0df97b8df..a16dde8d6 100644 --- a/docs/api.mjs +++ b/docs/api.mjs @@ -87,7 +87,7 @@ async function generateDocs() { ['pages/index.ts', 'pages.md'], ['pages/model/Page.ts', 'page.md'], ['parser/index.ts', 'parser.md'], - ['data_sources/index.ts', 'data_source_manager.md'], + ['data_sources/index.ts', 'datasources.md'], ['data_sources/model/DataSource.ts', 'datasource.md'], ['data_sources/model/DataRecord.ts', 'datarecord.md'], ].map(async (file) => { diff --git a/docs/api/block.md b/docs/api/block.md index 3e03073fd..01b72e490 100644 --- a/docs/api/block.md +++ b/docs/api/block.md @@ -39,6 +39,12 @@ Get block content Returns **([Object][2] | [String][1] | [Array][6]<([Object][2] | [String][1])>)** +## getDragDef + +Get block component dragDef + +Returns **ComponentDefinition** + ## getCategoryLabel Get block category label diff --git a/docs/api/canvas.md b/docs/api/canvas.md index 5df3b7de5..c707d472f 100644 --- a/docs/api/canvas.md +++ b/docs/api/canvas.md @@ -196,6 +196,40 @@ Get canvas rectangular data Returns **[Object][2]** +## startDrag + +Start custom drag-and-drop process. + +### Parameters + +* `dragSource` **DragSource\** The source object for the drag operation, containing the component being dragged. + +### Examples + +```javascript +// as component definition +canvas.startDrag({ + content: { type: 'my-component' } +}); +// as HTML +canvas.startDrag({ + content: '
...
' +}); +``` + +## endDrag + +Ends the drag-and-drop process, resetting the drag source and clearing any drag results. +This method can be used to finalize custom drag-and-drop content operations. + +### Examples + +```javascript +canvas.startDrag({...}); +// ... drag finished ... +canvas.endDrag(); +``` + ## hasFocus Check if the canvas is focused diff --git a/docs/api/datasources.md b/docs/api/datasources.md new file mode 100644 index 000000000..b044ad288 --- /dev/null +++ b/docs/api/datasources.md @@ -0,0 +1,159 @@ + + +## DataSources + +This module manages data sources within the editor. +You can initialize the module with the editor by passing an instance of `EditorModel`. + +```js +const editor = new EditorModel(); +const dsm = new DataSourceManager(editor); +``` + +Once the editor is instantiated, you can use the following API to manage data sources: + +```js +const dsm = editor.DataSources; +``` + +* [add][1] - Add a new data source. +* [get][2] - Retrieve a data source by its ID. +* [getAll][3] - Retrieve all data sources. +* [remove][4] - Remove a data source by its ID. +* [clear][5] - Remove all data sources. + +Example of adding a data source: + +```js +const ds = dsm.add({ + id: 'my_data_source_id', + records: [ + { id: 'id1', name: 'value1' }, + { id: 'id2', name: 'value2' } + ] +}); +``` + +### Parameters + +* `em` **EditorModel** Editor model. + +## add + +Add new data source. + +### Parameters + +* `props` **[Object][6]** Data source properties. +* `opts` **AddOptions** (optional, default `{}`) + +### Examples + +```javascript +const ds = dsm.add({ + id: 'my_data_source_id', + records: [ + { id: 'id1', name: 'value1' }, + { id: 'id2', name: 'value2' } + ] +}); +``` + +Returns **[DataSource]** Added data source. + +## get + +Get data source. + +### Parameters + +* `id` **[String][7]** Data source id. + +### Examples + +```javascript +const ds = dsm.get('my_data_source_id'); +``` + +Returns **[DataSource]** Data source. + +## getValue + +Get value from data sources by key + +### Parameters + +* `key` **[String][7]** Path to value. +* `defValue` **any** + +Returns **any** const value = dsm.getValue('ds\_id.record\_id.propName', 'defaultValue'); + +## remove + +Remove data source. + +### Parameters + +* `id` **([String][7] | [DataSource])** Id of the data source. +* `opts` **RemoveOptions?** + +### Examples + +```javascript +const removed = dsm.remove('DS_ID'); +``` + +Returns **[DataSource]** Removed data source. + +## fromPath + +Retrieve a data source, data record, and optional property path based on a string path. +This method parses a string path to identify and retrieve the corresponding data source +and data record. If a property path is included in the input, it will also be returned. +The method is useful for accessing nested data within data sources. + +### Parameters + +* `path` **[String][7]** The string path in the format 'dataSourceId.recordId.property'. + +### Examples + +```javascript +const [dataSource, dataRecord, propPath] = dsm.fromPath('my_data_source_id.record_id.myProp'); +// e.g., [DataSource, DataRecord, 'myProp'] +``` + +Returns **[DataSource?, DataRecord?, [String][7]?]** An array containing the data source, +data record, and optional property path. + +## store + +Store data sources to a JSON object. + +Returns **[Array][8]** Stored data sources. + +## load + +Load data sources from a JSON object. + +### Parameters + +* `data` **[Object][6]** The data object containing data sources. + +Returns **[Object][6]** Loaded data sources. + +[1]: #add + +[2]: #get + +[3]: #getall + +[4]: #remove + +[5]: #clear + +[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object + +[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String + +[8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array diff --git a/docs/getting-started.md b/docs/getting-started.md index 421d8de14..780d2873a 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -37,9 +37,9 @@ import grapesjs from 'grapesjs'; The first step is to define the interface of our editor. For this purpose we gonna start with basic HTML layouts. Finding a common structure for the UI of any project is not an easy task. That's why GrapesJS prefers to keep this process as simple as possible. We provide a few helpers, but let the user define the interface. This guarantees maximum flexibility. The main part of the GrapesJS editor is the canvas, this is where you create the structure of your templates and you can't miss it. Let's try to initiate the editor with the canvas and no panels. -<<< @/docs/.vuepress/components/demos/DemoCanvasOnly.html -<<< @/docs/.vuepress/components/demos/DemoCanvasOnly.js -<<< @/docs/.vuepress/components/demos/DemoCanvasOnly.css +<<< @/.vuepress/components/demos/DemoCanvasOnly.html +<<< @/.vuepress/components/demos/DemoCanvasOnly.js +<<< @/.vuepress/components/demos/DemoCanvasOnly.css @@ -277,7 +277,7 @@ Another utility tool you might find useful when working with web elements is the
``` -<<< @/docs/.vuepress/components/demos/DemoLayers.css +<<< @/.vuepress/components/demos/DemoLayers.css ```js const editor = grapesjs.init({ diff --git a/docs/package.json b/docs/package.json index 6f1892919..072f81cda 100644 --- a/docs/package.json +++ b/docs/package.json @@ -33,7 +33,7 @@ "scripts": { "docs": "vuepress dev .", "docs:api": "node ./api.mjs", - "build": "vuepress build .", + "build": "npm run docs:api && vuepress build .", "docs:deploy": "./deploy.sh" } } diff --git a/package.json b/package.json index 10420183e..4c293d0bd 100644 --- a/package.json +++ b/package.json @@ -4,6 +4,7 @@ "packageManager": "pnpm@9.10.0", "scripts": { "start": "pnpm --filter grapesjs start", + "start:docs": "pnpm --filter @grapesjs/docs docs", "test": "pnpm -r run test", "docs": "pnpm --filter @grapesjs/docs docs", "docs:api": "pnpm --filter @grapesjs/docs docs:api", @@ -20,7 +21,9 @@ "publish:core:rc": "cd packages/core && npm publish --tag rc --access public", "publish:core:latest": "cd packages/core && npm publish --access public", "build:core": "pnpm --filter grapesjs build", - "build:cli": "pnpm --filter grapesjs-cli build" + "build:cli": "pnpm --filter grapesjs-cli build", + "build:docs:api": "pnpm --filter @grapesjs/docs docs:api", + "build:docs": "pnpm --filter @grapesjs/docs build" }, "devDependencies": { "@babel/cli": "7.24.8", diff --git a/packages/core/src/canvas/index.ts b/packages/core/src/canvas/index.ts index d4f3d841c..a07ef0cdf 100644 --- a/packages/core/src/canvas/index.ts +++ b/packages/core/src/canvas/index.ts @@ -510,10 +510,18 @@ export default class CanvasModule extends Module { } /** - * Sets the drag source in the editor so it's used in Droppable.ts. - * This method can be used for custom drag-and-drop content by passing in a `DragSource` object. + * Start custom drag-and-drop process. * * @param {DragSource} dragSource - The source object for the drag operation, containing the component being dragged. + * @example + * // as component definition + * canvas.startDrag({ + * content: { type: 'my-component' } + * }); + * // as HTML + * canvas.startDrag({ + * content: '
...
' + * }); */ startDrag(dragSource: DragSource) { this.em.set('dragSource', dragSource); @@ -522,6 +530,10 @@ export default class CanvasModule extends Module { /** * Ends the drag-and-drop process, resetting the drag source and clearing any drag results. * This method can be used to finalize custom drag-and-drop content operations. + * @example + * canvas.startDrag({...}); + * // ... drag finished ... + * canvas.endDrag(); */ endDrag() { this.em.set({ dragResult: null, dragSource: undefined });