Skip to content

Commit

Permalink
Up docs (#6236)
Browse files Browse the repository at this point in the history
  • Loading branch information
artf authored Oct 21, 2024
1 parent 5555bfa commit de59e06
Show file tree
Hide file tree
Showing 9 changed files with 225 additions and 11 deletions.
4 changes: 2 additions & 2 deletions docs/.vuepress/config.js
Original file line number Diff line number Diff line change
Expand Up @@ -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`],
],
Expand All @@ -129,7 +129,7 @@ module.exports = {
['/modules/Storage', 'Storage Manager'],
['/modules/Modal', 'Modal'],
['/modules/Plugins', 'Plugins'],
['/modules/DataSources', 'Data Sources'],
// ['/modules/DataSources', 'Data Sources'],
],
},
{
Expand Down
2 changes: 1 addition & 1 deletion docs/api.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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) => {
Expand Down
6 changes: 6 additions & 0 deletions docs/api/block.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,12 @@ Get block content

Returns **([Object][2] | [String][1] | [Array][6]<([Object][2] | [String][1])>)**&#x20;

## getDragDef

Get block component dragDef

Returns **ComponentDefinition**&#x20;

## getCategoryLabel

Get block category label
Expand Down
34 changes: 34 additions & 0 deletions docs/api/canvas.md
Original file line number Diff line number Diff line change
Expand Up @@ -196,6 +196,40 @@ Get canvas rectangular data

Returns **[Object][2]**&#x20;

## startDrag

Start custom drag-and-drop process.

### Parameters

* `dragSource` **DragSource\<Component>** 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: '<div>...</div>'
});
```

## 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
Expand Down
159 changes: 159 additions & 0 deletions docs/api/datasources.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,159 @@
<!-- Generated by documentation.js. Update this documentation by updating the source code. -->

## 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**&#x20;

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?**&#x20;

### 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
8 changes: 4 additions & 4 deletions docs/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
<Demo>
<DemoCanvasOnly/>
</Demo>
Expand Down Expand Up @@ -277,7 +277,7 @@ Another utility tool you might find useful when working with web elements is the
<div id="blocks"></div>
```

<<< @/docs/.vuepress/components/demos/DemoLayers.css
<<< @/.vuepress/components/demos/DemoLayers.css

```js
const editor = grapesjs.init({
Expand Down
2 changes: 1 addition & 1 deletion docs/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"
}
}
5 changes: 4 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
"packageManager": "[email protected]",
"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",
Expand All @@ -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",
Expand Down
16 changes: 14 additions & 2 deletions packages/core/src/canvas/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -510,10 +510,18 @@ export default class CanvasModule extends Module<CanvasConfig> {
}

/**
* 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<Component>} 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: '<div>...</div>'
* });
*/
startDrag(dragSource: DragSource<Component>) {
this.em.set('dragSource', dragSource);
Expand All @@ -522,6 +530,10 @@ export default class CanvasModule extends Module<CanvasConfig> {
/**
* 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 });
Expand Down

0 comments on commit de59e06

Please sign in to comment.