MAGEDOC-3550: How to add an appearance

Extending content type tutorial

Author: bdenham

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

@@ -16,7 +16,7 @@ And the same three Quote controls are shown rendered here on a mock testimonial
 
 ## 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.
+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 content type names with `PageBuilder`. This helps visually group content type modules within your vendor directory. Of course, this convention does not 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:
 
@@ -28,7 +28,7 @@ After registering your module (`bin/magento setup:upgrade`) you will be ready to
 
 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)
+![Creating Custom Content Types](../images/content-type-overview.svg)
 
 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`).

docs/extend-existing-content-type/overview.md

@@ -1,3 +1,52 @@
-# Overview
+# Extending existing content types
+
+One of quickest ways to customize Page Builder is by changing how _existing_ content types look and behave. End-users can already edit Page Builder's content types in several ways. But sometimes your end-users will want to change the structure or modify properties that do not exist on a given content type. In those cases, you can extend an existing content type by customizing its existing _appearance_ or adding a new _appearance_.
+
+## Appearances
+
+An **appearance** is an XML element in a content type's configuration file that lets you modify existing properties, templates, styles, and form fields, or create new ones. In other words, all Page Builder content types (existing or custom) are extended through appearances.
+
+Many of Page Builder's content types have only one `appearance` element. These include the Heading, Text, Image, Video, Tabs, and more. Other content types have several appearances. For example, the Banner content type has four appearances, as shown here:
+
+![banner-appearances](../images/banner-appearances.png)  
+
+Page Builder defines these appearances in the Banner's configuration file (`Magento/PageBuilder/view/adminhtml/pagebuilder/content_type/banner.xml`), as shown here:
+
+```
+<appearances>
+    <appearance name="collage-left"...>
+    <appearance name="collage-centered"...>
+    <appearance name="collage-right"...>
+    <appearance name="poster" default="true" ...>
+</appearances>
+```
+
+Within each `appearance` element, you can change content types in the following ways:
+
+- Add new style properties.
+
+- Add or change templates.
+- Add to or change existing forms.
+- Add new attributes.
+- Move data between elements.
+
+## Banner extension tutorial
+
+In this tutorial, you will extend the Banner content type by adding a new `max-height` style property to two of the Banner's existing appearances: `collage-left` and `collage-right`.
+
+![Page Builder Banner menu item](../images/extend-banner-menu.png){:width="815px" height="auto"}
+
+## Banner extension steps
+
+These steps show the basic pattern for adding style properties using existing appearances to extend a content type:
+
+![Creating Custom Content Types](../images/extension-steps-overview.svg)
+
+1. **Create an extension module**: Create a basic module for your Banner extensions.
+2. **Extend appearances**: Extend the existing content type's configuration file by customizing an existing appearance with new style properties.
+3. **Extend forms**: Extend the existing content type's UI component form by adding new form fields and changing defaults for existing fields.
+
+## Next
+
+[Step 1: Create an extension module](step-1-create-extension-module.md)
 
-This topic is currently under development. It will be completed by the GA release of Page Builder.

docs/extend-existing-content-type/step-1-create-extension-module.md

@@ -0,0 +1,49 @@
+# Step 1: Create an extension module
+
+Appearance extensions for Page Builder are implemented using modules. In this step, we will create an empty module so we can add our appearance and form extensions in steps 2 and 3, as shown here:
+
+![Completed extension file structure](../images/extension-file-structure-complete.png){:width="826px" height="auto"}
+
+## Add directory structure
+
+To create a module for the Banner extensions, name your vendor directory `Example` and name your module `PageBuilderExtensionBanner`, as shown here:
+
+![Minimum extension module structure](../images/banner-extension-file-structure.png){:width="530px" height="auto"}
+
+The convention for naming extension modules is to prefix your extension of an existing content type with `PageBuilderExtension`, followed by the name of the content type. This is not a required convention, but we find that it helps visually group extension modules within your vendor directory.
+
+## Add module file
+
+Your module file should look like this:
+
+```xml
+<?xml version="1.0"?>
+<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
+    <module name="Example_PageBuilderExtensionBanner" setup_version="1.0.0">
+        <sequence>
+            <module name="Magento_PageBuilder"/>
+        </sequence>
+    </module>
+</config>
+```
+
+## Add registration file
+
+Your registration file should look like this:
+
+```php
+<?php
+
+use \Magento\Framework\Component\ComponentRegistrar;
+
+ComponentRegistrar::register(ComponentRegistrar::MODULE, 'Example_PageBuilderExtensionBanner', __DIR__);
+```
+
+## Install your module
+
+From your Magento root directory, use `bin/magento setup:upgrade` to install and enable your module.
+
+## Next
+
+[Step 2: Extend appearances](step-2-extend-appearances.md) 
+

docs/extend-existing-content-type/step-2-extend-appearances.md

@@ -0,0 +1,6 @@
+# Step 2: Extend appearances
+
+In progress
+
+
+

docs/extend-existing-content-type/step-3-extend-forms.md

@@ -0,0 +1,4 @@
+# Step 3: Extend forms
+
+In progress
+