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/package.json b/package.json index d9f094370..9fba16b0d 100644 --- a/package.json +++ b/package.json @@ -19,6 +19,7 @@ "release:cli:latest": "ts-node scripts/releaseCli latest", "publish:core:rc": "cd packages/core && npm publish --tag rc --access public", "publish:core:latest": "cd packages/core && npm publish --access public", + "build:docs:api": "pnpm --filter @grapesjs/docs docs:api", "build:core": "pnpm --filter grapesjs build", "build:cli": "pnpm --filter grapesjs-cli build", "build:docs": "pnpm --filter @grapesjs/docs build" 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 });