Skip to content

Commit c810c6d

Browse files
bdenhambdenham
committed
MC-5710: Beta docs tutorial
Updates to steps
1 parent dc7f11a commit c810c6d

10 files changed

+368
-100
lines changed

‎docs/configurations/iconography.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ They are simple, flat, and monochromatic to prevent the loss of detail at smalle
1111

1212
The following image shows all available PageBuilder Admin icons:
1313

14-
![PageBuilder admin icons](images/pagebuilder-icons.png)
14+
![PageBuilder admin icons](../images/pagebuilder-icons.png)
1515

1616
You can use these icons when extending or customizing the PageBuilder module or [create your own icons].
1717

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

Lines changed: 2 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,5 @@
1-
<!-- {% raw %} -->
2-
31
# Overview
42

5-
{: .bs-callout .bs-callout-warning }
6-
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 topic.
7-
83
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.
94

105
![Page Builder Content Types](../images/panel-horizontal.png)
@@ -17,8 +12,6 @@ Page Builder creates content types from modules. So this topic assumes you have
1712

1813
## Overview
1914

20-
An overview of the steps for creating a Page Builder content type are briefly illustrated and described here.
21-
2215
![Creating Custom Content Types](../images/content-type-overview.png)
2316

2417
1. **Add configuration**: Create an XML file to setup all the other files that control the appearances and behaviors of your content type.
@@ -34,7 +27,5 @@ The files you will need to create in order to build a basic content type are sho
3427

3528
![Before and after content type](../images/content-type-files.png)
3629

37-
This tutorial walks you through creating these files, starting with [Step 1: Add configuration](step-1-add-configuration.md).
38-
39-
40-
<!-- {% endraw %} -->
30+
## Tutorial
31+
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

Lines changed: 46 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
# Step 1: Add configuration
44

5-
The configuration file gives your content type its existence. It's where you set the name, display label, and references to the other files that define the appearance and behavior of your content type. Add it to your module in the following location (`view/adminhtml/pagebuilder/content_type/`):
5+
The configuration file gives your content type its existence. It's where you set the name, display label, and references to the other files that define the appearance and behavior of your content type. Add it to your module here (`view/adminhtml/pagebuilder/content_type/`):
66

77
![Create config file](../images/step1-add-config-file.png)
88

@@ -14,37 +14,48 @@ The file name should reflect the name of your content type. Use underscores to s
1414
Only a subset of configuration elements are described in this example (enough to understand the configuration file's role within a content type). For more details, refer to [Main configurations](../configurations/content-type-configuration.md) and [Additional configurations](../configurations/additional-configurations.md).
1515

1616

17-
The following configuration shows the minimal requirements for defining a content type, described in the tables that follow.
17+
The following configuration shows the minimal requirements for defining a content type called `example`. The `example` content type is nearly identical to the built-in `heading` content type in order to help you learn the fundamental parts of a content type as seen in the configuration file here. An overview of these elements and attributes are described in the tables that follow.
1818

1919
``` xml
2020
<?xml version="1.0"?>
21-
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_PageBuilder:etc/content_type.xsd">
22-
<type name="my-content-type"
23-
label="My Content Type"
24-
group="layout"
25-
component="Magento_PageBuilder/js/content-type-collection"
26-
preview_component="Magento_PageBuilder/js/content-type/preview"
27-
master_component="Magento_PageBuilder/js/content-type/master"
28-
form=""
29-
icon=""
30-
sortOrder="100"
31-
is_hideable="false"
32-
translate="label">
33-
<appearances>
34-
<appearance name="default"
35-
default="true"
36-
preview_template="Vendor_Module/content-type/my-content-type/default/preview"
37-
render_template="Vendor_Module/content-type/my-content-type/default/master"
38-
reader="Magento_PageBuilder/js/master-format/read/configurable">
39-
<elements>
40-
<element name="main">
41-
<attribute name="name" source="data-role"/>
42-
<attribute name="appearance" source="data-appearance"/>
43-
</element>
44-
</elements>
45-
</appearance>
46-
</appearances>
47-
</type>
21+
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
22+
xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_PageBuilder:etc/content_type.xsd">
23+
<type name="heading"
24+
label="Heading"
25+
component="Magento_PageBuilder/js/content-type"
26+
preview_component="Magento_PageBuilder/js/content-type/heading/preview"
27+
form="pagebuilder_heading_form"
28+
group="elements"
29+
icon="icon-pagebuilder-heading"
30+
sortOrder="20"
31+
translate="label">
32+
<children default_policy="deny"/>
33+
<appearances>
34+
<appearance default="true"
35+
name="default"
36+
preview_template="Magento_PageBuilder/content-type/heading/default/preview"
37+
render_template="Magento_PageBuilder/content-type/heading/default/master"
38+
reader="Magento_PageBuilder/js/master-format/read/configurable">
39+
<elements>
40+
<element name="main">
41+
<style name="text_align" source="text_align"/>
42+
<style name="border" source="border_style" converter="Magento_PageBuilder/js/converter/style/border-style"/>
43+
<style name="border_color" source="border_color"/>
44+
<style name="border_width" source="border_width" converter="Magento_PageBuilder/js/converter/style/border-width"/>
45+
<style name="border_radius" source="border_radius" converter="Magento_PageBuilder/js/converter/style/remove-px"/>
46+
<style name="display" source="display" converter="Magento_PageBuilder/js/converter/style/display" preview_converter="Magento_PageBuilder/js/converter/style/preview/display"/>
47+
<style name="margins" storage_key="margins_and_padding" reader="Magento_PageBuilder/js/property/margins" converter="Magento_PageBuilder/js/converter/style/margins"/>
48+
<style name="padding" storage_key="margins_and_padding" reader="Magento_PageBuilder/js/property/paddings" converter="Magento_PageBuilder/js/converter/style/paddings"/>
49+
<attribute name="name" source="data-role"/>
50+
<attribute name="appearance" source="data-appearance"/>
51+
<tag name="heading_type"/>
52+
<html name="heading_text" converter="Magento_PageBuilder/js/converter/html/tag-escaper"/>
53+
<css name="css_classes"/>
54+
</element>
55+
</elements>
56+
</appearance>
57+
</appearances>
58+
</type>
4859
</config>
4960
```
5061

@@ -68,11 +79,11 @@ The `<type>` node defines the key properties of your content type. The attribute
6879

6980
## The `appearance` node
7081

71-
The purpose of the `<appearance>` node in a configuration is to define the appearance of your content type as a preview in the Admin (using the`preview.html` template) and in the storefront for customers (using the `master.html` template).
82+
The purpose of the `<appearance>` node in a configuration is to define how your content type appears when it is dragged on the stage in the in the Admin UI (using the`preview.html` template) and when it's displayed in the storefront for customers (using the `master.html` template).
7283

7384
The `<appearance>` attributes are described as follows:
7485

75-
| attribute | description |
86+
| Attribute | Description |
7687
| ---------------- | ------------------------------------------------------------ |
7788
| name | Name of the appearance for extending as needed. |
7889
| default | Content types must specify one of the appearances as the default appearance. That means if you only have one appearance, it must be set as the default. |
@@ -81,18 +92,14 @@ The `<appearance>` attributes are described as follows:
8192
| reader | Reads data for the content type from the master format |
8293
{:style="table-layout:auto"}
8394

84-
All content types must have at least one `<appearance>` defined within the `<appearances>` collection.
95+
All content types must have at least one `<appearance>` defined within the `<appearances>` node.
8596

86-
## The `element` node
97+
## The `elements` node
8798

88-
**[Dave, I know the following sentence is incorrect. Please rewrite to correct it and add more information as needed. :) ]**
89-
90-
The purpose of the `<element>` nodes in a configuration is to map the data from the content type from the given source back to the master format so that the content type can be updated and rendered correctly within both the Admin preview and the storefront.
91-
92-
**[Add table to describe element attributes and nodes]**
99+
The purpose of `<elements>` node in the configuration is to map the data from the editor to the content type's master format so that the values entered in the editor can be stored and rendered correctly within both the Admin preview and the storefront. These nodes will be explained more fully in Step 4: Add editor.
93100

94101
## Next
95102

96-
At this point, if you try to view Page Builder you get an error noting that the `preview_template` and `render_template` from the `<appearance>` element are missing. These templates are referenced in the example config file, but we have not yet created them. Let's do that next in [Step 2: Add templates](step-2-add-templates.md).
103+
At this point, if you try to view Page Builder you get an error noting that the `preview_template` and `render_template` from the `<appearance>` element are missing. These templates are referenced in the `example.xml` config file, but we have not yet created them. Let's do that next in [Step 2: Add templates](step-2-add-templates.md).
97104

98105
<!-- {% endraw %} -->

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

Lines changed: 50 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -2,53 +2,74 @@
22

33
# Step 2: Add templates
44

5-
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. Add them to your module in the following location (`view/adminhtml/web/template/content-type/<content-type-name>/default/`):
5+
Templates are the 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`).
66

7-
![Create config file](../images/step2-add-templates.png)
7+
## Configuration
8+
9+
Templates are referenced from the `<appearance>` element of the configuration file as shown here:
810

9-
``` xml
11+
```xml
1012
<appearance name="default"
1113
default="true"
12-
preview_template="Vendor_Module/content-type/my-content-type/default/preview"
13-
render_template="Vendor_Module/content-type/my-content-type/default/master"
14+
preview_template="Vendor_Module/content-type/example/default/preview"
15+
render_template="Vendor_Module/content-type/example/default/master"
1416
reader="Magento_PageBuilder/js/master-format/read/configurable">
1517
```
1618

17-
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.
19+
| Attribute | Description |
20+
| ---------------- | ------------------------------------------------------------ |
21+
| preview_template | `preview.html` - the HTML template for rendering the preview appearance of a content type on the stage within the Admin UI. |
22+
| render_template | `master.html` - the HTML template for rendering the appearance of a content type on the storefront for customers to see. |
23+
24+
## Location
25+
26+
Content types cannot be rendered without these templates. Add them to your module here (`view/adminhtml/web/template/content-type/<content-type-name>/default/`):
27+
28+
![Create config file](../images/step2-add-templates.png)
29+
30+
31+
32+
## Create the `preview_template`
33+
34+
1. Create the `preview.html` file (as noted above) using the example content that follows.
1835

19-
![Page Builder templates](../images/templates-directory-structure.png)
20-
21-
```html
22-
<!--master.html-->
23-
<div attr="data.main.attributes" ko-style="data.main.style" css="data.main.css">
24-
<div attr="data.main.attributes" css="data.main.css" ko-style="data.main.style">
25-
<div style="width: 100%; height: 100px; background-color: #cccccc;">Storefront UI template</div>
26-
</div>
27-
</div>
28-
```
29-
3036
```html
3137
<!--preview.html-->
32-
<div class="pagebuilder-content-type" event="{ mouseover: onMouseOver, mouseout: onMouseOut }, mouseoverBubble: false">
33-
<render args="getOptions().template" />
34-
<div attr="data.main.attributes" css="data.main.css" ko-style="data.main.style">
35-
<div style="width: 100%; height: 100px; background-color: #f1f1f1; padding: 20px;">Admin UI template</div>
36-
</div>
38+
<div class="pagebuilder-content-type"
39+
event="{ mouseover: onMouseOver, mouseout: onMouseOut }, mouseoverBubble: false">
40+
<render args="getOptions().template" />
41+
<h2 attr="data.main.attributes"
42+
ko-style="data.main.style"
43+
css="data.main.css"
44+
data-bind="liveEdit: { field: 'example_text', placeholder: $t('Edit Example Text') }">
45+
</h2>
3746
</div>
3847
```
3948

4049
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:
41-
50+
4251
![Page Builder Panel Config](../images/create-config-file-1.png)
43-
52+
4453
3. Drag your new content type onto the stage and **Save**. You should see something similar to this:
4554

4655
![Admin preview.html template](../images/drag-content-type-to-stage.png)
47-
56+
4857
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.
49-
50-
4. Open the Home Page on the storefront to see how the `master.html` template renders, as shown here:
5158

52-
![Storefront master.html template](../images/content-type-master-template.png)
53-
59+
## Create the `master_template`
60+
61+
62+
63+
```html
64+
<!--master.html-->
65+
<h2 attr="data.main.attributes"
66+
ko-style="data.main.style"
67+
css="data.main.css"
68+
html="data.main.html">
69+
</h2>
70+
```
71+
72+
73+
74+
5475
<!-- {% endraw %} -->

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

Lines changed: 34 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,42 @@
11
<!-- {% raw %} -->
22

3-
# Step 3: Add component
3+
# Step 3: Add components (optional)
44

5-
A component is a JavaScript file that defines the behavior of your content type within the Admin UI stage (using preview.js). Add it to your module in the following location (`view/adminhtml/web/js/content-type/<content-type-name>/`):
5+
Components are the JavaScript files that define the behaviors of your content type when they appear on the stage in the Admin UI (using the `preview.js` component) and in the storefront (using the `master.js` component). As such, they are complementary to the templates you added previously in Step 2.
6+
7+
## Configuration
8+
9+
Components are referenced from the `<type>` element of the configuration file as shown here:
10+
11+
```XML
12+
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
13+
xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_PageBuilder:etc/content_type.xsd">
14+
<type name="example"
15+
label="Example"
16+
component="Magento_PageBuilder/js/content-type"
17+
preview_component="Vendor_Module/js/content-type/example/preview"
18+
master_component="Magento_PageBuilder/js/content-type/master"
19+
...
20+
```
21+
22+
| Attribute | Description |
23+
| ----------------- | ------------------------------------------------------------ |
24+
| component | Currently there are two component types to choose from: `content-type` and `content-type-collection`. Use `Magento_PageBuilder/js/content-type` for static content types that do not have children (as shown in the example). Use `Magento_PageBuilder/js/content-type-collection` for content types that can contain children, called container content types. |
25+
| preview_component | `preview.js` - Optional JavaScript file that provides preview-specific rendering logic within the Admin UI. If your content type does not require any specific user-interactivity or other behavior in the Admin, you can simply omit this attribute from the the `<type>`. Page Builder will use `Magento_PageBuilder/js/content-type/preview` by default. |
26+
| master_component | `master.js` - Optional JavaScript file that provides master format rendering logic generic for all appearances of your content type when rendered on the storefront. Same as with the `preview_component`, if your content type does not require any specific user-interactivity or other behavior when it's displayed in the storefront, you can simply omit this attribute from the the `<type>`. Page Builder will use `Magento_PageBuilder/js/content-type/master` by default (as shown in the example). |
27+
28+
{:style="table-layout:auto"}
29+
30+
## Location
31+
32+
Add them to your module here (`view/adminhtml/web/js/content-type/<content-type-name>/`):
633

734
![Create config file](../images/step3-add-component.png)
835

9-
{: .bs-callout .bs-callout-warning }
10-
The development of this tutorial is currently **IN PROGRESS**, **INCOMPLETE**, and potentially **INCORRECT**. The expected completion time is Nov. 27.
36+
37+
38+
## Create preview component
39+
40+
1141

1242
<!-- {% endraw %} -->

0 commit comments

Comments
 (0)