Data source schema & providers (#6633)

* Setup initial schema types

* Setup initial schema methods

* Add DataSource tests

* Up test

* Add test getValue

* Cleanup

* Up test

* Add setValue method

* Up docs

* Check nested arrays

* Add a test for nested setValue

* Improve setValue for nested values

* Improve setValue for nested values

* Setup relation tests

* Add getResolvedRecords

* Resolve one to many relations in DataSource records

* Add DataSourceSchema

* Up type

* Start data source providers

* Start test provider

* Add tests for loadProvider

* Cleanup

* Skip records if DataSource provider is set

* Load providers on project load

* Type keymap events

* Move modal events

* Move layer events

* Move RTE events

* Move selector events

* Move StyleManager events

* Move editor events

* Start DataSource callbacks

* Add data source callbacks

* Update docs

* Up device_manager jsdoc

* Format

Author: artf

docs/api.mjs

@@ -97,33 +97,43 @@ async function generateDocs() {
         throw `File not found '${filePath}'`;
       }
 
-      return build([filePath], { shallow: true })
-        .then((cm) => formats.md(cm /*{ markdownToc: true }*/))
-        .then(async (output) => {
-          let addLogs = [];
-          let result = output
-            .replace(/\*\*\\\[/g, '**[')
-            .replace(/\*\*\(\\\[/g, '**([')
-            .replace(/<\\\[/g, '<[')
-            .replace(/<\(\\\[/g, '<([')
-            .replace(/\| \\\[/g, '| [')
-            .replace(/\\n```js/g, '```js')
-            .replace(/docsjs\./g, '')
-            .replace('**Extends ModuleModel**', '')
-            .replace('**Extends Model**', '');
+      try {
+        return build([filePath], { shallow: true })
+          .then((cm) => formats.md(cm /*{ markdownToc: true }*/))
+          .then(async (output) => {
+            let addLogs = [];
+            let result = output
+              .replace(/\*\*\\\[/g, '**[')
+              .replace(/\*\*\(\\\[/g, '**([')
+              .replace(/<\\\[/g, '<[')
+              .replace(/<\(\\\[/g, '<([')
+              .replace(/\| \\\[/g, '| [')
+              .replace(/\\n```js/g, '```js')
+              .replace(/docsjs\./g, '')
+              .replace('**Extends ModuleModel**', '')
+              .replace('**Extends Model**', '');
 
-          // Search for module event documentation
-          if (result.indexOf(REPLACE_EVENTS) >= 0) {
-            const eventsMd = await getEventsMdFromTypes(filePath);
-            if (eventsMd && result.indexOf(REPLACE_EVENTS) >= 0) {
-              addLogs.push('replaced events');
+            // Search for module event documentation
+            if (result.indexOf(REPLACE_EVENTS) >= 0) {
+              try {
+                const eventsMd = await getEventsMdFromTypes(filePath);
+                if (eventsMd && result.indexOf(REPLACE_EVENTS) >= 0) {
+                  addLogs.push('replaced events');
+                }
+                result = eventsMd ? result.replace(REPLACE_EVENTS, `## Available Events\n${eventsMd}`) : result;
+              } catch (err) {
+                console.error(`Failed getting events: ${file[0]}`);
+                throw err;
+              }
             }
-            result = eventsMd ? result.replace(REPLACE_EVENTS, `## Available Events\n${eventsMd}`) : result;
-          }
 
-          writeFileSync(`${docRoot}/api/${file[1]}`, result);
-          log('Created', file[1], addLogs.length ? `(${addLogs.join(', ')})` : '');
-        });
+            writeFileSync(`${docRoot}/api/${file[1]}`, result);
+            log('Created', file[1], addLogs.length ? `(${addLogs.join(', ')})` : '');
+          });
+      } catch (err) {
+        console.error(`Build failed: ${file[0]}`);
+        throw err;
+      }
     }),
   );
 

docs/api/block_manager.md

@@ -84,6 +84,8 @@ editor.on('block:custom', ({ container, blocks, ... }) => { ... });
 editor.on('block', ({ event, model, ... }) => { ... });
 ```
 
+* BlocksEventCallback
+
 [Block]: block.html
 
 [Component]: component.html

docs/api/canvas.md

@@ -122,6 +122,14 @@ editor.on('canvas:frame:load:body', ({ window }) => {
 });
 ```
 
+* `canvas:frame:unload` Frame is unloading from the canvas.
+
+```javascript
+editor.on('canvas:frame:unload', ({ frame }) => {
+ console.log('Unloading frame', frame);
+});
+```
+
 [Component]: component.html
 
 [Frame]: frame.html

docs/api/component.md

@@ -137,7 +137,7 @@ By setting override to specific properties, changes of those properties will be
 ### Parameters
 
 *   `value` **([Boolean][3] | [String][1] | [Array][5]<[String][1]>)**&#x20;
-*   `options` **DynamicWatchersOptions**  (optional, default `{}`)
+*   `options` **DataWatchersOptions**  (optional, default `{}`)
 
 ### Examples
 
@@ -335,8 +335,7 @@ Get the style of the component
 
 ### Parameters
 
-*   `options` **any**  (optional, default `{}`)
-*   `optsAdd` **any**  (optional, default `{}`)
+*   `opts` **GetComponentStyleOpts?**&#x20;
 
 Returns **[Object][2]**&#x20;
 
@@ -363,7 +362,7 @@ Return all component's attributes
 
 ### Parameters
 
-*   `opts` **{noClass: [boolean][3]?, noStyle: [boolean][3]?}**  (optional, default `{}`)
+*   `opts` **{noClass: [boolean][3]?, noStyle: [boolean][3]?, skipResolve: [boolean][3]?}**  (optional, default `{}`)
 
 Returns **[Object][2]**&#x20;
 

docs/api/datasource.md

@@ -31,6 +31,44 @@ dataSource.addRecord({ id: 'id3', name: 'value3' });
 *   `props` **DataSourceProps** Properties to initialize the data source.
 *   `opts` **DataSourceOptions** Options to initialize the data source.
 
+### hasProvider
+
+Indicates if the data source has a provider for records.
+
+### getResolvedRecords
+
+Retrieves all records from the data source with resolved relations based on the schema.
+
+### upSchema
+
+Update the schema.
+
+#### Parameters
+
+*   `schema` **Partial\<any>**&#x20;
+*   `opts` **SetOptions?**&#x20;
+
+#### Examples
+
+```javascript
+dataSource.upSchema({ name: { type: 'string' } });
+```
+
+### getSchemaField
+
+Get schema field definition.
+
+#### Parameters
+
+*   `fieldKey` **any**&#x20;
+
+#### Examples
+
+```javascript
+const fieldSchema = dataSource.getSchemaField('name');
+fieldSchema.type; // 'string'
+```
+
 ## defaults
 
 Returns the default properties for the data source.
@@ -55,6 +93,12 @@ Retrieves the collection of records associated with this data source.
 
 Returns **DataRecords\<DRProps>** The collection of data records.
 
+## records
+
+Retrieves the collection of records associated with this data source.
+
+Returns **DataRecords\<DRProps>** The collection of data records.
+
 ## em
 
 Retrieves the editor model associated with this data source.

docs/api/datasources.md

@@ -44,12 +44,26 @@ editor.on('data:path', ({ dataSource, dataRecord, path }) => {
 editor.on('data:pathSource:SOURCE_ID', ({ dataSource, dataRecord, path }) => { ... });
 ```
 
+* `data:provider:load` Data source provider load.
+
+```javascript
+editor.on('data:provider:load', ({ dataSource, result }) => { ... });
+```
+
+* `data:provider:loadAll` Load of all data source providers (eg. on project load).
+
+```javascript
+editor.on('data:provider:loadAll', () => { ... });
+```
+
 * `data` Catch-all event for all the events mentioned above.
 
 ```javascript
 editor.on('data', ({ event, model, ... }) => { ... });
 ```
 
+* DataSourcesEventCallback
+
 ## Methods
 
 *   [add][1] - Add a new data source.
@@ -101,15 +115,32 @@ Returns **[DataSource]** Data source.
 
 ## getValue
 
-Get value from data sources by key
+Get value from data sources by path.
 
 ### Parameters
 
-*   `key` **[String][7]** Path to value.
-*   `defValue` **any** 
+*   `path` **[String][7]** Path to value.
+*   `defValue` **any** Default value if the path is not found.
 
 Returns **any** const value = dsm.getValue('ds\_id.record\_id.propName', 'defaultValue');
 
+## setValue
+
+Set value in data sources by path.
+
+### Parameters
+
+*   `path` **[String][7]** Path to value in format 'dataSourceId.recordId.propName'
+*   `value` **any** Value to set
+
+### Examples
+
+```javascript
+dsm.setValue('ds_id.record_id.propName', 'new value');
+```
+
+Returns **[Boolean][8]** Returns true if the value was set successfully
+
 ## remove
 
 Remove data source.
@@ -152,7 +183,7 @@ data record, and optional property path.
 
 Store data sources to a JSON object.
 
-Returns **[Array][8]** Stored data sources.
+Returns **[Array][9]** Stored data sources.
 
 ## load
 
@@ -178,4 +209,6 @@ Returns **[Object][6]** Loaded data sources.
 
 [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]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
+
+[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array

docs/api/device_manager.md

@@ -19,12 +19,35 @@ const deviceManager = editor.Devices;
 ```
 
 ## Available Events
+* `device:add` New device added to the collection. The `Device` is passed as an argument.
 
-*   `device:add` - Added new device. The [Device] is passed as an argument to the callback
-*   `device:remove` - Device removed. The [Device] is passed as an argument to the callback
-*   `device:select` - New device selected. The newly selected [Device] and the previous one, are passed as arguments to the callback
-*   `device:update` - Device updated. The updated [Device] and the object containing changes are passed as arguments to the callback
-*   `device` - 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('device:add', (device) => { ... });
+```
+
+* `device:remove` Device removed from the collection. The `Device` is passed as an argument.
+
+```javascript
+editor.on('device:remove', (device) => { ... });
+```
+
+* `device:select` A new device is selected. The `Device` is passed as an argument.
+
+```javascript
+editor.on('device:select', (device) => { ... });
+```
+
+* `device:update` Device updated. The `Device` and the object containing changes are passed as arguments.
+
+```javascript
+editor.on('device:update', (device) => { ... });
+```
+
+* `device` Catch-all event for all the events mentioned above.
+
+```javascript
+editor.on('device', ({ event, model, ... }) => { ... });
+```
 
 ## Methods
 

docs/api/editor.md

@@ -42,6 +42,15 @@ editor.on('load', () => { ... });
 editor.on('project:load', ({ project, initial }) => { ... });
 ```
 
+* `project:loaded` Similar to `project:load`, but triggers only if the project is loaded successfully.
+
+```javascript
+editor.on('project:loaded', ({ project, initial }) => { ... });
+
+// Loading an empty project, won't trigger this event.
+editor.loadProjectData({});
+```
+
 * `project:get` Event triggered on request of the project data. This can be used to extend the project with custom data.
 
 ```javascript
@@ -516,6 +525,7 @@ Load data from the JSON project
 ### Parameters
 
 *   `data` **[Object][16]** Project to load
+*   `options` **[Object][16]?** Custom options that could be passed to the project load events. (optional, default `{}`)
 
 ### Examples
 
@@ -722,7 +732,7 @@ Trigger event
 ### Parameters
 
 *   `event` **[string][18]** Event to trigger
-*   `args` **...[Array][19]\<any>**&#x20;
+*   `args` **...any**&#x20;
 
 Returns **this**&#x20;
 

docs/api/keymaps.md

@@ -19,23 +19,30 @@ const editor = grapesjs.init({
 })
 ```
 
-Once the editor is instantiated you can use its API and listen to its events. Before using these methods, you should get the module from the instance.
+Once the editor is instantiated you can use its API. Before using these methods you should get the module from the instance.
 
 ```js
-// Listen to events
-editor.on('keymap:add', () => { ... });
-
-// Use the API
 const keymaps = editor.Keymaps;
-keymaps.add(...);
 ```
 
 ## Available Events
+* `keymap:add` New keymap added. The new keymap object is passed as an argument to the callback.
+
+```javascript
+editor.on('keymap:add', (keymap) => { ... });
+```
+
+* `keymap:remove` Keymap removed. The removed keymap object is passed as an argument to the callback.
 
-*   `keymap:add` - New keymap added. The new keyamp object is passed as an argument
-*   `keymap:remove` - Keymap removed. The removed keyamp object is passed as an argument
-*   `keymap:emit` - Some keymap emitted, in arguments you get keymapId, shortcutUsed, Event
-*   `keymap:emit:{keymapId}` - `keymapId` emitted, in arguments you get keymapId, shortcutUsed, Event
+```javascript
+editor.on('keymap:remove', (keymap) => { ... });
+```
+
+* `keymap:emit` Some keymap emitted. The keymapId, shortcutUsed, and Event are passed as arguments to the callback.
+
+```javascript
+editor.on('keymap:emit', (keymapId, shortcutUsed, event) => { ... });
+```
 
 ## Methods