Merge pull request #387 from magento-obsessive-owls/PB-73

PB-73: Create Appearances example and documentation

Author: davemacaulay

docs/how-to/how-to-add-appearance.md

@@ -1,6 +1,6 @@
 # How to add an appearance
 
-Appearances provide different layout and styling options for a content type. For example, the Banner content type has four appearances. Each appearance shows a different layout for the Banner's text and button.
+Appearances provide different layout and styling options for a content type. For example, the Banner content type has four appearances. Each appearance shows a different layout for the Banner's included text and button.
 
 This topic shows how to add appearances to Page Builder's native content types. An overview of the steps and the files you need to add are illustrated here:
 
@@ -18,7 +18,7 @@ First, we need a way select an appearance within the Admin UI. In Page Builder,
 
 _Visual selector for Banner_
 
-To add a new appearance option for one of Page Builder's native content types, like the Banner, create a new `di.xml` file in your module, as shown here:
+To add a new appearance option for one of Page Builder's native content types (such as the Banner), create a new `di.xml` file in your module, as shown here:
 
 ![Add VisualSelect class](../images/add-visualselect-class.png)
 
@@ -51,7 +51,7 @@ The following table describes the configuration arguments for each appearance op
 | --------------- | ------------------------------------------------------------ |
 | `optionsData`   | Grouping array for all the appearance options of a content type. |
 | `item array`    | Grouping array of properties that define an appearance option. We recommend you match the `name` of the item array to the option's `value` string. In our example, the `item` array's name is `simple-poster`, which matches the option's value string `simple-poster`. |
-| `value`         | The `value` string should match the appearance name defined in the content type's configuration file. Page Builder uses this value to link the option to the appearance.|
+| `value`         | String that matches the appearance name defined in the content type's configuration file. Page Builder uses this string value to link the option to the appearance.|
 | `title`         | Display name for the appearance option. Banner example: Poster. |
 | `icon`          | Path to the `.svg` icon for the appearance: `view/adminthtml/web/css/images/content-type/[content-type-name]/appearance/*.svg`. See [Creating an icon for your appearance](#create-an-appearance-icon) |
 | `noticeMessage` | (Not shown in example.) The `noticeMessage` displays a message below the appearance options when the appearance is selected. For example, two of the Row appearances (`full-width` and `full-bleed`) define `noticeMessage` strings that display when selected. |
@@ -75,11 +75,11 @@ _Example of additional appearance options_
 
 ### Create an appearance icon
 
-Appearance icons are `.svg` files that graphically depict the layout of an appearance. Add all the appearance icons for your content type within the following directory: `css/images/content-type/[content-type-name]/appearance/`.
+Appearance icons are `.svg` files that graphically depict the layout of an appearance. Add your additional appearance icons to your module's css appearance directory (`css/images/content-type/[content-type-name]/appearance/`). Additional appearance icons for the Banner would be added as shown here:
 
 ![Add appearance icons](../images/appearance-icon-location.png)
 
-_Add appearance icons for Banner content type_
+_Additional appearance icons for Banner_
 
 You can use any design tool to create your SVG. But if you want to match your appearance icons to Page Builder's icons _perfectly_, use the SVG structure and dimensions shown here:
 
@@ -96,7 +96,7 @@ You can use any design tool to create your SVG. But if you want to match your ap
 ```
 _SVG appearance template_
 
-These specific dimensions ensure that your icon fits seamlessly with the existing appearance icons:
+These specific dimensions ensure that your icon fits seamlessly with Page Builder's existing appearance icons:
 
 | Property                       | Value       |
 | ------------------------------ | ----------- |
@@ -114,7 +114,7 @@ These specific dimensions ensure that your icon fits seamlessly with the existin
 
 ## Step 2: Add appearance configurations
 
-Appearance configurations connect the data entered in a content type's form to its HTML templates. For example, the Heading content type has an `<html>` config element (`<html name="heading_text" />`)  that maps the text entered into the content type's `heading_text` form field (`<field name="heading_text" formElement="input">`) to the Heading's Knockout template binding (`html="data.main.html"`), as illustrated here:
+Appearance configurations connect the data entered in a content type's form to its HTML templates. For example, the Heading content type has an `<html>` config element (`<html name="heading_text" />`) that maps the text entered into the content type's `heading_text` field (`<field name="heading_text" formElement="input">`) to the Heading's Knockout template binding (`html="data.main.html"`), as illustrated here:
 
 ![Appearance configurations](../images/appearance-configurations.png)
 
@@ -129,7 +129,7 @@ To add a new Banner appearance configuration, create a content type config file
 _Add additional appearances to Banner content type_
 
 {: .bs-callout .bs-callout-info }
-This procedure applies to any native content type you want to extend. In other words, you can use the file name (`heading.xml`) and type name (`<type name="heading">`) of any native Page Builder content type to extend it based on Magento's XML merging behavior.
+This procedure applies to any native content type you want to extend. In other words, you can use the file name (such as `heading.xml`) and type name (such as `<type name="heading">`) of any content type to extend it based on Magento's XML merging behavior.
 
 An example `banner.xml` config file for a new `simple-poster` appearance is shown here:
 
@@ -165,7 +165,7 @@ _Additional simple-poster appearance for the Banner content type_
 
 Appearances for a content type can share the same form or use different forms. For example, the Products content type uses two different forms, one for each appearance. The Grid appearance uses the `pagebuilder_products_form.xml` to provide options for displaying products in a grid. While the Carousel appearance uses the `pagebuilder_products_carousel_form.xml` to provide extra options for displaying products in a carousel.
 
-When you select an appearance with its own form, Page Builder replaces the content type's form (defined in the `<type>` element) with the appearance's form. But when you select an appearance that does not have a form defined, the appearance switches back to using the content type's form.
+When you select an appearance with a form, Page Builder replaces the content type's form (defined in the `<type>` element) with the appearance's form. But when you select an appearance that does _not_ have a form defined, the appearance switches back to using the content type's form.
 
 ```xml
 <config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"...>
@@ -174,7 +174,7 @@ When you select an appearance with its own form, Page Builder replaces the conte
 ```
 _Content type form used by default for all appearances_
 
-To add a form for an appearance, add a `<form>` element as a child of the `<appearance>` element in your content type's config file. As mentioned, the Products content type does this for its Carousel appearance, shown here:
+To add a form for an appearance, add a `<form>` element as a child of the `<appearance>` element in your content type's config file. As mentioned, the Products content type uses a form for its Carousel appearance, as shown here:
 
 ```xml
 <appearance name="carousel"
@@ -189,19 +189,20 @@ _Adding a form to an appearance_
 
 ## Step 4: Add appearance templates
 
-Appearances use different HTML templates to create different layouts and apply different styles to those layouts. For example, the Banner content type uses four sets of `preview.html` and `master.html` templates to create the visual differences for each content type:
+Appearances use different HTML templates to create different layouts. They also use templates to apply different styles to the same layouts. For example, the Banner uses four sets of `preview.html` and `master.html` templates, one set for each appearance:
 
 ![Appearance configuration config file](../images/appearance-templates-banner.png)
 
 _Banner appearance templates_
 
+{: .bs-callout .bs-callout-info }
 Notice how Page Builder organizes the Banner templates by appearance name. We recommend the same practice when adding templates for your appearances.
 
-To create appearance templates for additional Banner appearances, such as the `simple-poster` appearance described in steps 1 and 2, add a new appearance folder for your module's templates, as shown here:
+To create templates for additional Banner appearances, such as the `simple-poster` described in steps 1 and 2, add a new appearance folder with your `master.html` and `preview.html` templates, as shown here:
 
 ![Appearance templates](../images/appearance-templates-additional.png)
 
-_Adding additional appearance templates_
+_Add additional templates to `template/content-type/[content-type-name]/[appearance-name]`_
 
 ## Step 5: Add appearance styles
 
@@ -211,11 +212,11 @@ Appearances use different CSS/LESS files to create different visual styles for a
 
 _Banner stylesheets_
 
-To create a LESS stylesheet for an additional Banner appearances, such as the `simple-poster`, you must add a new appearance folder for your module's templates, as shown here:
+To create a stylesheet for an additional Banner appearance, such as the `simple-poster`, add a folder named `banner` and a `.less` file with the name of the appearance, as shown here:
 
 ![Additional appearance stylesheets](../images/appearance-css-additional.png)
 
-_Adding additional stylesheets_
+_Add additional stylesheets to `css/source/content-type/[content-type-name]/`_
 
 The `_module.less` file is an import file that ensures the additional stylesheet gets added to the existing Banner styles. The `_module.xml` file for our `simple-poster.less` file looks like this:
 
@@ -224,10 +225,10 @@ The `_module.less` file is an import file that ensures the additional stylesheet
 ```
 _Use _module.less for import statements_
 
-## Conclusion
-
-Using appearances to extend Page Builder's native content types represents one of Page Builder's best practices for creating a variety of new content building blocks based on existing content types. We hope this topic has helped adequately describe this best practice.
-
 ## Example Module
 
 An example module for this topic is available for download in the [pagebuilder-examples repository](https://github.com/magento-devdocs/pagebuilder-examples/tree/master/Example/PageBuilderBannerAppearance).
+
+## Conclusion
+
+Using appearances to extend Page Builder's native content types represents one of Page Builder's best practices for creating a variety of new content building blocks based on existing content types.