Merge pull request #289 from magento-obsessive-owls/MC-19861

MC-19861: Update datastore docs

Author: davemacaulay

docs/reference/architecture.md

@@ -130,8 +130,7 @@ For example:
 
 Page Builder stores data for content types in a simple object called the DataStore: `Magento_PageBuilder/js/data-store`.
 
-The `name` parameter from the [content type configuration](configurations.md) is the name of a parameter in the `DataStore`.
-You can use the `subscribe` method to listen for changes in the DataStore and perform custom actions on the data.
+The name parameter from the [content type configuration](configurations.md) (or storage_key if specified) is the name of a parameter in the DataStore. You can use the subscribe method to listen for changes in the DataStore and perform custom actions like updating the UI.
 
 This is how the system binds the data from the DataStore to your elements attribute or style. When you include a new attribute or style, you must specify where it should retrieve its data from the content type. These `name` values normally bind to the field names within UI component forms. The field names are the keys we use to save the data.
 

docs/reference/data-store.md

@@ -1,36 +1,75 @@
 # Page Builder data store
 
 ## Summary
-The data store's purpose is to store all configured data associated with a content type's instance. You can modify this data in several ways, including through live edit on the Admin stage or from the content type's UI component form editor.
 
-Page Builder accesses the data store when generating the data sets in the preview and master templates before render.
+The data store is a utility class that stores the user's input data for a content type. When Page Builder creates a content type, either from the master storage format or from a user dragging and dropping a content type, Page Builder also creates a data store instance for that content type. Whenever the user modifies a content type, either by editing it on the stage or from the UI component form, Page Builder updates the data store with the new data. The master format and preview both fetch the data required for their render from the data store.
 
 ## Access
 
-The data store is available for access on the `ContentType` implementation via the key `dataStore`. If you're within a preview or master component, you must first access the content type through the `contentType` property.
+The data store is available for access on the `ContentType` implementation, using the key `dataStore`. If you are within a preview or master component, you must first access the content type through the `contentType` property, as follows:
+
+```js
+Preview.contentType.dataStore;
+```
+
+## Events
+
+The data store maintains its own event system. It does not use the global events system used by Page Builder. As a result, you need to create an instance of `dataStore` and subscribe to its data changes, as follows:
+
+```js
+var dataStore = self.contentType.dataStore;
+
+dataStore.subscribe(() => {
+    // handler to update content type
+});
+```
 
 ## API
+
 #### `get(key: string, defaultValue?: any): any`
+
 Retrieve a single value from the content type's data store based on its key. You can provide an optional default value if no data is present.
 
 #### `getState(): object`
+
 Get the entire state object for the current content type instance.
 
 #### `set(key: string, value: any): void`
+
 Set a single piece of data into the content type's data store.
 
 #### `setState(): void`
+
 Set the entire state for the current content type.
 
-## Events
-The data store maintains its own events system and does not use the global events system that's otherwise used by Page Builder.
+## Usage
 
-Because of this, you need to create an instance of `dataStore` to observe events.
+You can use the data store to modify your content type when its data changes. For example, the Page Builder native [Tabs content type](magento2-page-builder/app/code/Magento/PageBuilder/view/adminhtml/web/ts/js/content-type/tabs/preview.ts) subscribes to the data store and makes updates to it when a tab-item changes, as show here in TypeScript:
 
-Page Builder fires a single event called `state`, which returns the entire state of the data store. Page Builder fires this event whenever the state changes.
+```typescript
+...
+    args.contentType.dataStore.subscribe(() => {
+        this.updateTabNamesInDataStore();
+    });
+...
 
-```js
-dataStore.events.on("state", function (state) {
-    console.log(state);    
-});
-```
+/**
+* Update data store with active options
+*/
+private updateTabNamesInDataStore() {
+    const activeOptions: ActiveOptionsInterface[] = [];
+    this.contentType.children().forEach((tab: ContentTypeInterface, index: number) => {
+        const tabData = tab.dataStore.getState();
+        activeOptions.push({
+            label: tabData.tab_name.toString(),
+            labeltitle: tabData.tab_name.toString(),
+            value: index,
+        });
+    });
+
+    this.contentType.dataStore.set(
+        "_default_active_options",
+        activeOptions,
+    );
+}
+```