MC-4272: Update content type docs

More progress on the basic content type tutorial

Author: bdenham

README.md

@@ -49,6 +49,7 @@ We offer one method for installing PageBuilder:
 * [Main configurations](docs/configurations/content-type-configuration.md)
 * [Additional configurations](docs/configurations/additional-configurations.md)
 * [Panel configurations](docs/configurations/panel-configurations.md)
+* [Option menu configurations](docs/configurations/option-menu-configurations.md)
 * [Iconography](docs/configurations/iconography.md)
 * [Block chooser configuration](docs/configurations/block-chooser-configuration.md)
 * [Full-width page layout configuration](docs/configurations/full-width-page-layout-configuration.md)
@@ -60,6 +61,9 @@ We offer one method for installing PageBuilder:
 
 ### How Tos
 
+* [How to develop a new content type](docs/how-to/how-to-develop-new-content-type.md)
+* [How to develop a container content type](docs/how-to/how-to-develop-container-content-type.md)
+* [How to use the Image Uploader](docs/how-to/how-to-use-image-uploader.md)
 * [How to use the Image Uploader](docs/how-to/how-to-use-image-uploader.md)
 * [How to add inline text editing](docs/how-to/how-to-add-inline-text-editing.md)
 * [How to add a custom toolbar](docs/how-to/how-to-add-custom-toolbar.md)

docs/configurations/content-type-configuration.md

@@ -15,7 +15,7 @@ Use the content type and group configuration to add new content types, extend ex
 | `children`          | List of children content types that can accept this type as a parent.                                                                       |
 | `appearances`       | Appearance configuration.                                                                                                                   |
 | `is_visible`        | Determines menu visibility for the component. System components should not be visible in the menu. Default value is true.                   |
-| `additional_data`   | Allows to specify additional data for component, see [custom configuration for content type](data-configuration.md) for more information. |
+| `additional_data`   | Allows to specify additional data for component, see [additional configurations](additional-configurations.md) for more information. |
 
 | Attribute           | Description                                                                                                                                 |
 | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |

docs/configurations/option-menu-configurations.md

@@ -0,0 +1 @@
+# Option menu configurations

docs/create-basic-content-type/overview.md

@@ -1,5 +1,7 @@
 # Overview
 
+> NOTE: The development of this tutorial is currently IN PROGRESS. A more complete rough draft is available in the How Tos section here: [How to develop a new content type](docs/how-to/how-to-develop-new-content-type.md). When this tutorial is complete, it will replace the equivalent How To.
+
 Out of the box, Page Builder comes with several content types (controls) that you can drag onto the stage to build your storefront pages, as shown below. In this topic, you will learn how to create your own content type for use within Page Builder.
 
 ![Page Builder Content Types](../images/panel-horizontal.png)
@@ -18,8 +20,8 @@ An overview of the steps for creating a Page Builder content type are briefly il
 ![Creating Custom Content Types](../images/content-type-overview.png)
 
 1. **Add configuration**: an XML file to setup all the other files that control the appearances and behaviors of your content type.  
-2. **Add templates**: HTML files to control the appearance of your content types on the Admin stage (preview.html) and the storefront (master.html).
-3. **Add component**: a JavaScript file to control the behavior of your content type on the Admin stage (preview.js) and the storefront (master.js).
+2. **Add templates**: HTML files that define the appearance of your content types on the Admin stage (preview.html) and the storefront (master.html).
+3. **Add component**: a JavaScript file that define the behavior of your content type on the Admin stage (preview.js) and the storefront (master.js).
 4. **Add form (editor)**: a UI component (XML file) to give users the ability to add or edit content using your content type.
 5. **Add layout**: an XML file to add your form editor to the stage. 
 6. **Add styles and icons**: LESS and image files (png, svg) to add specific styling and images to your content types as they appear on the Admin stage and the storefront. 
@@ -31,4 +33,4 @@ The files you will need to create in order to build a basic content type are sho
 
 ![Before and after content type](../images/content-type-files.png)
 
-This tutorial walks you through creating these files, step by step.
+This tutorial walks you through creating these files, starting with [Step 1: Add configuration](step-1-add-configuration.md).

docs/create-basic-content-type/step-1-add-configuration.md

@@ -6,6 +6,8 @@ Creating a configuration file is the first step to creating a new content type.
 
 1. Create a new XML file in the following directory structure of your module: `view/adminhtml/pagebuilder/content_type/my-content-type.xml`. 
 
+    ![Create config file](../images/create-config-file.png)
+
 2. Copy the contents of this example into your `my-content-type.xml` file:
     ``` xml
     <?xml version="1.0"?>
@@ -39,35 +41,4 @@ Creating a configuration file is the first step to creating a new content type.
     </config>
     ```
 
-3. Create the required `preview_template` and `render_template` as specified in the configuration file.
-
-    Before seeing the results of our configuration in the Page Builder panel menu, we need to create the two templates specified in the <appearance> element of the configuration file: 
-    * preview.html - to display our content type within the Admin UI. 
-    * master.html - to display our content type within the CMS page on the storefront. 
-
-    Both templates are required. So for now, just create the files within the following directory structure, `view/adminhtml/web/template/content_type/my-content-type/default/`, using the example content that follows. We will discuss them in detail later:
-    
-    ```html
-    <!--preview.html-->
-    <div class="pagebuilder-content-type" event="{ mouseover: onMouseOver, mouseout: onMouseOut }, mouseoverBubble: false">
-        <render args="getOptions().template" />
-        <div attr="data.main.attributes" css="data.main.css" ko-style="data.main.style">
-            <div style="width: 100%; height: 100px; background-color: #f1f1f1; padding: 20px;">Admin template</div>
-        </div>
-    </div>
-    ```
-    
-    ```html
-    <!--master.html-->
-    <div class="pagebuilder-content-type" event="{ mouseover: onMouseOver, mouseout: onMouseOut }, mouseoverBubble: false">
-        <render args="getOptions().template" />
-        <div attr="data.main.attributes" css="data.main.css" ko-style="data.main.style">
-            <div style="width: 100%; height: 100px; background-color: #f1f1f1; padding: 20px;">Admin template</div>
-        </div>
-    </div>
-    ```
-
-4. Flush your config cache `bin/magento cache:flush config` and view Page Builder from the Home Page editor (as a convenience for storefront viewing later). The Page Builder panel menu should show your content type at the top of the layout group:
-   
-   ![Page Builder Panel Config](../images/create-config-file-1.png) 
-   
+If you try to view Page Builder at this point, Page Builder will throw an error noting that the `preview_template` and `render_template` from the `<appearance` element are missing. These templates are required before we can add our content type to Page Builder. Let's do that in [Step 2: Add templates](step-2-add-templates.md).

docs/create-basic-content-type/step-2-add-templates.md

@@ -1 +1,49 @@
 # Step 2: Add templates
+
+Page Builder templates are HTML files that define the appearance of content types within both the Admin UI (using the preview.html) and the storefront UI (using the master.html). Content types cannot be rendered without these templates, so let's create the ones already specified in the `<appearance>` element of our configuration file.
+
+``` xml
+<appearance name="default"
+            default="true"
+            preview_template="Vendor_Module/content-type/my-content-type/default/preview"
+            render_template="Vendor_Module/content-type/my-content-type/default/master"
+            reader="Magento_PageBuilder/js/master-format/read/configurable">
+```
+
+1. Create the `preview_template` and `render_template` files (as noted above) within the specified directory structure, `view/adminhtml/web/template/content_type/my-content-type/default/`, using the example content that follows.
+
+    ![Page Builder templates](../images/templates-directory-structure.png)
+  
+    ```html
+    <!--master.html-->
+    <div attr="data.main.attributes" ko-style="data.main.style" css="data.main.css">
+        <div attr="data.main.attributes" css="data.main.css" ko-style="data.main.style">
+            <div style="width: 100%; height: 100px; background-color: #cccccc;">Storefront UI template</div>
+        </div>
+    </div>
+    ```
+       
+    ```html
+    <!--preview.html-->
+    <div class="pagebuilder-content-type" event="{ mouseover: onMouseOver, mouseout: onMouseOut }, mouseoverBubble: false">
+        <render args="getOptions().template" />
+        <div attr="data.main.attributes" css="data.main.css" ko-style="data.main.style">
+            <div style="width: 100%; height: 100px; background-color: #f1f1f1; padding: 20px;">Admin UI template</div>
+        </div>
+    </div>
+    ```
+
+2. Flush your config cache `bin/magento cache:flush config` and view Page Builder from the Home Page editor (as a convenience for storefront viewing later). The Page Builder panel menu should show your content type at the top of the layout group:
+   
+   ![Page Builder Panel Config](../images/create-config-file-1.png) 
+   
+3. Drag your new content type onto the stage and **Save**. You should see something similar to this:
+
+    ![Admin preview.html template](../images/drag-content-type-to-stage.png) 
+    
+    Notice that you also have an options menu when you hover over your content type. This is provided by including the `<render args="getOptions().template" />` within your `preview.html` template. See [Option menu configurations](option-menu-configurations.md) for more details.
+    
+4. Open the Home Page on the storefront to see how the `master.html` template renders, as shown here:
+
+    ![Storefront master.html template](../images/content-type-master-template.png) 
+    

docs/create-basic-content-type/step-3-add-components.md

@@ -1 +1,5 @@
 # Step 3: Add components
+
+Components are JavaScript files that define the behavior of your content type within the Admin UI stage (using preview.js) and the storefront UI (using master.js).
+
+1. Add a preview.js file to ...