Merge pull request #187 from magento-devdocs/develop

[Owls] Beta 3 docs release notes

Author: davemacaulay

.gitignore

@@ -5,4 +5,5 @@
 /dev/tests/acceptance/vendor
 static-error-log.xml
 .DS_Store
-.vscode
+.vscode
+.history/

README.md

@@ -1,6 +1,6 @@
-## PageBuilder Early Access Program
+## PageBuilder Early Adopters Program
 
-The Page Builder Early Access Program (EAP) gives partners the following perks:
+The Page Builder Early Adopters Program (EAP) gives partners the following perks:
 
 * Explore extension points to build custom modules and integrations for 3rd party services, such as Facebook and Instagram.
 * Try out customization options and extend its functionality beyond its default features.

docs/component-status.md

@@ -1,6 +1,7 @@
 # Component status
 
-**Last Updated: November 27, 2018**
+
+**Last Updated: December 10, 2018**
 
 <style type="text/css" style="display: none">
 .status {

docs/component-status2.md

@@ -0,0 +1,61 @@
+# Component status
+
+**Last Updated: December 19, 2018**
+
+<style type="text/css" style="display: none">
+.status {
+  padding: 3px 5px;
+  border-radius: 2px;
+}
+.status.red {
+  color: #fff;
+  background-color: #d04437;
+}
+.status.yellow {
+  background-color: #f6c342;
+}
+.status.green {
+  background-color: #14892c;
+  color: #fff;
+}
+</style>
+
+This page shows the status of each content type and component in Page Builder beta as a measure of readiness for each.
+
+Each status color indicates the severity and number of issues for a particular component.
+
+- <span class="status red">Red</span> - The content type or component has critical and blocking issues that make this module unstable.
+- <span class="status yellow">Yellow</span> - The content type or component has some issues that may cause problems, but it is still functional.
+- <span class="status green">Green</span> - The content type or component has no significant or outstanding issues.
+
+The issues used to generate the status of these components come from verified internal and GitHub reports for Page Builder beta.
+Issues that are not related to Page Builder beta are not part of this report.
+
+## Content Types
+
+| Name               | Status                                    | Notes                                     |
+| ------------------ | ----------------------------------------- | ----------------------------------------- |
+| Row                | <span class='status green'>Green</span>   |  |
+| Column             | <span class='status green'>Green</span>   |  |
+| Tabs               | <span class='status green'>Green</span>   |  |
+| Text               | <span class='status green'>Green</span>   |  |
+| Heading            | <span class='status green'>Green</span>   |  |
+| Buttons            | <span class='status green'>Green</span>   |  |
+| Divider            | <span class='status green'>Green</span>   |  |
+| HTML Code          | <span class='status green'>Green</span>   |  |
+| Image              | <span class='status green'>Green</span>   |  |
+| Video              | <span class='status green'>Green</span>   |  |
+| Banner             | <span class='status green'>Green</span>   |  |
+| Slider             | <span class='status green'>Green</span>   |  |
+| Map                | <span class='status green'>Green</span>   |  |
+| Block              | <span class='status green'>Green</span>   |  |
+| Dynamic Block      | <span class='status green'>Green</span>   |  |
+| Products           | <span class='status green'>Green</span>   |  |
+{:style="table-layout:auto"}
+
+## Migration
+
+| Name                              | Status                                  | Notes                                     |
+| --------------------------------- | --------------------------------------- | ----------------------|
+| Bluefoot to Page Builder          | <span class='status red'>Red</span>     | The renderers provided out of the box are not fully updated with the latest changes to their respective content types.|
+{:style="table-layout:auto"}

docs/configurations/block-chooser-configuration.md

@@ -1,19 +1,9 @@
-# Block chooser <!-- omit in toc -->
+# Block chooser
 
-<!-- {% raw %} -->
-
-## What's in this topic <!-- omit in toc -->
+## What's in this topic
 
 This topic describes how to use the block chooser UI component for a custom content type.
 
-## Overview <!-- omit in toc -->
-
-To use the block chooser component for your custom content type:
-
-- [Configuration options](#configuration-options)
-- [Add the block select grid listing modal to content type XML](#add-the-block-select-grid-listing-modal-to-content-type-xml)
-- [Add component to content type XML](#add-component-to-content-type-xml)
-
 ## Configuration options
 
 Extends all `abstract` configuration.
@@ -137,5 +127,3 @@ To insert the block chooser UI component, `Magento_PageBuilder/js/form/element/b
 The `block_id` field pulls in the selected value from the modal.
 
 Then the `block_chooser` component pulls in the value from the `block_id` field to ascertain when it should commence updating.
-
-<!-- {% endraw %} -->

docs/configurations/content-type-configuration.md

@@ -497,6 +497,14 @@ define([], function () {
 });
 ```
 
+### Form
+
+Individual appearances may have different uiComponent forms in order to use different customizable content.
+
+``` xml
+<form>pagebuilder_banner_collage_left_form</form>
+```
+
 ## Preview component settings
 
 | Property                 | Description                                                                                                                         | Example        |

docs/configurations/option-menu-configurations.md

@@ -1,4 +1,8 @@
 # Option menu configurations
 
-{: .bs-callout .bs-callout-info }
-The development of this topic is currently **IN PROGRESS**.
+---
+
+The development of this topic is currently **IN PROGRESS**.
+
+---
+

docs/configurations/panel-configurations.md

@@ -1,5 +1,3 @@
-<!-- {% raw %} -->
-
 # Panel groups and configurations
 
 By default, the Page Builder panel has four groups (Layout, Elements, Media, Add Content) and 16 content types as shown here:
@@ -19,11 +17,10 @@ These groups are defined in the Page Builder `group.xml` file and can be extende
 ## Overview
 
 This topic describes four ways to customize the Page Builder panel:
-
-- [Rename panel groups](#rename-panel-groups)
-- [Reorder panel groups](#reorder-panel-groups)
-- [Add new panel groups](#add-new-panel-groups)
-- [Add content types to different panel group](#add-content-types-to-different-panel-groups).
+    - [Rename panel groups](#rename-panel-groups)
+    - [Reorder panel groups](#reorder-panel-groups)
+    - [Add new panel groups](#add-new-panel-groups)
+    - [Add content types to different panel groups](#add-content-types-to-different-panel-groups)
 
 {: .bs-callout .bs-callout-info }
 For the sake of the user experience, please don't forget the affect your panel configurations may have on the end user. User's should have access the most important content types first, so be careful how you reorder groups and content types within groups. We strongly encourage you to place your content types into the existing groups when possible, instead of creating your own group.
@@ -103,6 +100,3 @@ To add your content type to a new group or one of the existing groups, set your
 The result looks like this:
 
 ![Group with content type](../images/group-with-content-type.png)
-
-
-<!-- {% endraw %} -->

docs/configurations/server-side-rendered-previews.md

@@ -1,27 +1,14 @@
-# Server-side rendered previews <!-- omit in toc -->
-
-<!-- {% raw %} -->
+# Server-side rendered previews
 
 ## What's in this topic
 
 This topic describes how to use the `RenderPool` on the stage to render a backend [content type] preview. 
 
 Using this method, you can preview content types that cannot be rendered on the stage and require further backend processing to be previewed.
 
-The following steps utilize some example values; substitute those with values specific to your situation.
-
-## Overview
-
-To use the stage's `RenderPool` to produce a content type preview:
+The following steps utilize some example values. Substitute those with values specific to your situation.
 
-- [What's in this topic](#whats-in-this-topic)
-- [Overview](#overview)
-- [Create a renderer](#create-a-renderer)
-- [Add the renderer to the pool](#add-the-renderer-to-the-pool)
-- [Submit an HTTP request to the preview controller](#submit-an-http-request-to-the-preview-controller)
-- [Render the element](#render-the-element)
-
-## Create a renderer
+## Step 1: Create a renderer
 
 Create a renderer that implements the renderer interface, `Magento\PageBuilder\Model\Stage\RendererInterface`:
 
@@ -38,7 +25,7 @@ class AwesomeElement implements \Magento\PageBuilder\Model\Stage\RendererInterfa
 }
 ```
 
-## Add the renderer to the pool
+## Step 2: Add the renderer to the pool
 
 Add the renderer you just created as an argument to the `Magento\PageBuilder\Model\Stage\RendererPool` type that specifies your custom content type role as the name in the `di.xml` file:
 
@@ -52,7 +39,7 @@ Add the renderer you just created as an argument to the `Magento\PageBuilder\Mod
 </type>
 ```
 
-## Submit an HTTP request to the preview controller
+## Step 3: Submit an HTTP request to the preview controller
 
 To invoke the renderer from the stage, submit an HTTP request to the PageBuilder preview controller:
 
@@ -95,12 +82,10 @@ To invoke the renderer from the stage, submit an HTTP request to the PageBuilder
         });
     ```
 
-## Render the element
+## Step 4: Render the element
 
 Your exact configuration and situation determine when, and how, you render the element. 
 
 Generally, you would perform this operation when the properties change, by overriding the `afterObservablesUpdated` method with this logic (as shown in the previous example).
 
 To update the Document Object Model (DOM) to display your content, amend the JavaScript property that represents the HTML variable of your main element with the response from the HTTP request, `this.data.main.html(response.content);` from the previous example.
-
-<!-- {% endraw %} -->

docs/configurations/storefront-configuration.md

@@ -1,14 +1,8 @@
-# Storefront customization <!-- omit in toc -->
+# Storefront customization
 
-<!-- {% raw %} -->
-You can customize PageBuilder content types by adding your own logic on the frontend.
+You can customize Page Builder content types by adding your own logic on the frontend, as described here.
 
-To add custom logic to content types:
-
-- [Create a JavaScript widget](#create-a-javascript-widget)
-- [Add XML configuration](#add-xml-configuration)
-
-## Create a JavaScript widget
+## Step 1: Create a JavaScript widget
 
 Create a JavaScript widget in your module's `/view/frontend/web/js/content-type/{content-type-name}/appearance/{appearance-name}/widget.js` file:
 
@@ -48,7 +42,7 @@ define([
 
 ```
 
-## Add XML configuration
+## Step 2: Add XML configuration
 
 The XML configuration loads the widget on the frontend, and on the stage, so that you can preview content inside both the block and dynamic block content types.
 
@@ -75,6 +69,4 @@ Add the following configuration to the `etc/di.xml` file in your custom module d
         </argument>
     </arguments>
 </type>
-```
-
-<!-- {% endraw %} -->
+```

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

@@ -1,34 +1,58 @@
 # Overview
 
-{: .bs-callout .bs-callout-info }
+***
 The development of this tutorial is currently **IN PROGRESS**.
 
-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 comes with several content types (controls) you can use to build your storefront pages. In this tutorial, you will add a new content type: a **Quote** control, which you can use to show customer testimonials or other types of quotations within your storefront.
 
 ![Page Builder Content Types](../images/panel-horizontal.png)
 
-## Prerequisites
+## Quote preview
+
+The following screenshot shows three instances of the Quote control you will build in this tutorial: 
+
+![QuoteTypeDisplay](../images/AdminTestimonials.png)
+
+And the same three Quote controls are shown rendered here on a mock testimonial page in the storefront:
+
+![StorefrontTestimonials](../images/StorefrontTestimonials.png)
+
+
 
-Page Builder creates content types from modules. So this topic assumes you have a basic module structure in which to add your content type files.
+## Quote module
+
+As with most things in Magento, content types for Page Builder are housed in modules. The convention for naming modules that are solely dedicated to Page Builder, such as our Quote content type, is to prefix all the content type name with `PageBuilder`. This helps visually group content type modules within your vendor directory. Of course, this convention doesn't apply If you are adding a content type as part of an existing module.
+
+Applying this convention to the module for our Quote content type, we get the name `PageBuilderQuote`, and can set up our module as shown here:
 
 ![Minimum module structure](../images/module-minimum-structure.png)
 
-## Overview
+After registering your module (`bin/magento setup:upgrade`) you will be ready to begin this tutorial by following the content type creation process outlined next.
+
+## Quote creation
+
+The steps for creating the Quote content type are illustrated and described below. The reality is not quite this linear, but these steps do represent the basic phases and flow for building new Page Builder content types.
 
 ![Creating Custom Content Types](../images/content-type-overview.png)
 
-1. **Add configuration**: Create an XML file to setup all the other files that control the appearances and behaviors of your content type.  
-2. **Add templates**: Create HTML files that define the appearance of your content types on the Admin stage (preview.html) and the storefront (master.html).
-3. **Add component**: Create 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**: Create a UI component form (XML file) and layout so users can edit your content type.
+1. **Add configuration**: Create an XML file to define your content type and reference the other files that control the appearance and behavior of your content type.  
+2. **Add templates**: Create HTML templates that define the appearance of your content types on the Admin stage (`preview.html`) and the storefront (`master.html`).
+3. **Add component**: Create a JavaScript file that defines the behavior of your content type on the Admin stage (`preview.js`) and the storefront (`master.js`).
+4. **Add form**: Create a UI component form and a layout so Admin users can edit your content type within the Page Builder editor.
 5. **Add styles**: Create LESS files to style your content types when rendered in the Admin UI and on the storefront. 
 6. **Add frontend widget**: Create a JavaScript file to control the UI behavior (user interactivity) of your content type on the storefront.  
 
-## Content type files
+## Quote file structure
 
-The files you will need to create in order to build a basic content type are shown here.
+Before we get started, take a look at what you will be building. The directory structure on the left shows the basic `PageBuilderQuote` module you will start with (as previously described). The directory structure on the right shows all the files you will add to the `PageBuilderQuote` module throughout this tutorial, labeled by the steps in the process. 
 
 ![Before and after content type](../images/content-type-files.png)
 
-## Tutorial
-This tutorial walks you through creating these files, starting with [Step 1: Add configuration](step-1-add-configuration.md). 
+## Conventions
+
+The `PageBuilderQuote` module structure represents an overview of the conventions used for content types. Many of these conventions are simply those defined for developing UI components. However, the conventions specific to Page Builder content types appropriately start within the directories called `content_type` or `content-type`. Page Builder instantiates a content type from the files defined within these directories. We will discuss these content type conventions within each step of the process.
+
+## Next
+[Step 1: Add configuration](step-1-add-configuration.md)