Skip to content

Commit 3cac900

Browse files
davemacaulaydavemacaulay
authored
Merge pull request #200 from magento-devdocs/1.0.0-beta-release
[Owls] Beta 5 documentation update
2 parents 1895939 + aab59ba commit 3cac900

32 files changed

+842
-1612
lines changed

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

+2-9
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,5 @@
11
# Overview
22

3-
***
4-
The development of this tutorial is currently **IN PROGRESS**.
5-
6-
***
7-
83
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.
94

105
![Page Builder Content Types](../images/panel-horizontal.png)
@@ -19,8 +14,6 @@ And the same three Quote controls are shown rendered here on a mock testimonial
1914

2015
![StorefrontTestimonials](../images/StorefrontTestimonials.png)
2116

22-
23-
2417
## Quote module
2518

2619
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.
@@ -35,14 +28,14 @@ After registering your module (`bin/magento setup:upgrade`) you will be ready to
3528

3629
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.
3730

38-
![Creating Custom Content Types](../images/content-type-overview.png)
31+
![Creating Custom Content Types](../images/content-type-overview.svg)
3932

4033
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.
4134
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`).
4235
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`).
4336
4. **Add form**: Create a UI component form and a layout so Admin users can edit your content type within the Page Builder editor.
4437
5. **Add styles**: Create LESS files to style your content types when rendered in the Admin UI and on the storefront.
45-
6. **Add frontend widget**: Create a JavaScript file to control the UI behavior (user interactivity) of your content type on the storefront.
38+
6. **Add an icon**: Create an SVG icon to visually identify your content type within the Page Builder panel.
4639

4740
## Quote file structure
4841

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

+14-19
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,5 @@
11
# Step 1: Add configuration
22

3-
***
4-
The development of this tutorial is currently **IN PROGRESS**.
5-
6-
***
7-
83
The configuration file defines the settings and references to your content type files. You will return to this file often to update references and change settings during the development process.
94

105
Files referenced from the configuration include the HTML templates, the JavaScript components, the icon displayed for your content type in the Page Builder panel, and the UI component form for your content type editor within the Admin.
@@ -20,7 +15,7 @@ The name of your configuration file should reflect the name of your content type
2015
![Create config file](../images/step1-add-config-file.png)
2116

2217
{: .bs-callout .bs-callout-info }
23-
The reason we suggest prefIxing your content type with your vendor name is to prevent Magento from merging your content type configuration file with another configuration file of the same name, or with a future content type published by Magento.
18+
The reason we suggest prefixing your content type with your vendor name is to prevent Magento from merging your content type configuration file with another configuration file of the same name, or with a future content type published by Magento.
2419

2520
## The `example_quote` configuration
2621

@@ -32,30 +27,30 @@ The following configuration is from the Quote content type. An overview of these
3227
```xml
3328
<?xml version="1.0"?>
3429
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_PageBuilder:etc/content_type.xsd">
35-
<type name="example_quote"
30+
<type name="example_quote"
3631
label="Quote"
3732
group="elements"
3833
component="Magento_PageBuilder/js/content-type"
39-
preview_component="Magento_PageBuilder/js/content-type/preview"
34+
preview_component="Example_PageBuilderQuote/js/content-type/example-quote/preview"
4035
master_component="Magento_PageBuilder/js/content-type/master"
4136
form="pagebuilder_example_quote_form"
4237
icon="icon-pagebuilder-heading"
4338
sortOrder="21"
4439
translate="label">
4540
<children default_policy="deny"/>
4641
<parents default_policy="deny">
47-
<parent name="column" policy="allow"/>
42+
<parent name="column" policy="allow"/>
4843
</parents>
4944
<appearances>
50-
<appearance name="default"
45+
<appearance name="default"
5146
default="true"
5247
preview_template="Example_PageBuilderQuote/content-type/acme_quote/default/preview"
5348
render_template="Example_PageBuilderQuote/content-type/acme_quote/default/master"
5449
reader="Magento_PageBuilder/js/master-format/read/configurable">
5550
<elements...>
56-
</appearance>
51+
</appearance>
5752
</appearances>
58-
</type>
53+
</type>
5954
</config>
6055
```
6156

@@ -72,8 +67,8 @@ The `type` element defines the key properties of your content type. The attribut
7267
| `preview_component` | Optional. JavaScript file (`preview.js`) that provides rendering logic within the Admin UI. The preview component does not need to specify the `.js` extension. If you don't provide the `preview_component`, Page Builder uses the base `Preview` component shown in the code: `Magento_PageBuilder/js/content-type/preview`. |
7368
| `master_component` | Optional. JavaScript file (`master.js`) that provides rendering logic generic for all appearances of your content type when rendered on the storefront. The master component does not need to specify the `.js` extension. If you don't provide the `master_component`, Page Builder uses the base `Master` component shown in the code: `Magento_PageBuilder/js/content-type/master`. |
7469
| `form` | UI component form that provides the form controls for editing your content type. |
75-
| `icon` | Optional. PNG or SVG image displayed in the Page Builder panel alongside the label. If no icon value is provided, the content type will simply be displayed in the Page Builder panel without an icon. |
76-
| `sortOrder` | Optional. The listed order within the menu group. For example, `sortOrder=21` puts the content type third in the `Elements` menu group, after the content types with `sortOrder`s of 10 and 20. |
70+
| `icon` | Optional. Class name for your PNG or SVG image (or font icon) displayed in the Page Builder panel alongside the label. If you don't provide an icon value, the Page Builder panel displays the content type name without an icon. |
71+
| `sortOrder` | Optional. The listed order within the menu group. For example, `sortOrder=21` puts the content type third in the `Elements` menu group, after the content types with `sortOrder` values of 10 and 20. |
7772
| `translate` | Identifies the attribute you want Magento to translate. Here, the `label` value is set for translation. |
7873

7974
## The `children` element
@@ -92,7 +87,7 @@ The `parents` element determines if other content types can be a parent to your
9287

9388
```xml
9489
<parents default_policy="deny">
95-
<parent name="column" policy="allow"/>
90+
<parent name="column" policy="allow"/>
9691
</parents>
9792
```
9893

@@ -108,10 +103,10 @@ Each of these views is defined as an `appearance` within the Banner configuratio
108103

109104
```xml
110105
<appearances>
111-
<appearance name="collage-left"...>
112-
<appearance name="collage-centered"...>
113-
<appearance name="collage-right"...>
114-
<appearance name="poster" default="true" ...>
106+
<appearance name="collage-left"...>
107+
<appearance name="collage-centered"...>
108+
<appearance name="collage-right"...>
109+
<appearance name="poster" default="true" ...>
115110
</appearances>
116111
```
117112

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

+35-39
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,5 @@
11
# Step 2: Add templates
22

3-
***
4-
The development of this tutorial is currently **IN PROGRESS**.
5-
6-
***
7-
83
Content type templates are the HTML files (HTML fragments) that define how your content type *appears* on both the Admin stage and within your storefront. The combination of these templates (one `preview.html` and one `master.html`) creates an `appearance`. As discussed in the previous configuration step, you must have at least one `appearance` (two templates) defined for your content type. But like the Banner, you can define several appearances for users to choose from as shown here:
94

105
![banner-appearances](../images/banner-appearances.png)
@@ -21,10 +16,10 @@ Conventions for adding content type templates are as follows.
2116

2217
```xml
2318
<appearances>
24-
<appearance name="collage-left"...>
25-
<appearance name="collage-centered"...>
26-
<appearance name="collage-right"...>
27-
<appearance name="poster" default="true" ...>
19+
<appearance name="collage-left"...>
20+
<appearance name="collage-centered"...>
21+
<appearance name="collage-right"...>
22+
<appearance name="poster" default="true" ...>
2823
</appearances>
2924
```
3025

@@ -38,8 +33,8 @@ The Quote example defines only one `appearance`. Therefore, by convention, set t
3833

3934
```xml
4035
<appearances>
41-
<appearance name="default"
42-
...
36+
<appearance name="default"
37+
...
4338
```
4439

4540
![Create config file](../images/step2-add-templates.png)
@@ -48,13 +43,13 @@ These files can be blank initially; they just need to exist in their proper loca
4843

4944
```xml
5045
<appearances>
51-
<appearance name="default"
46+
<appearance name="default"
5247
default="true"
5348
preview_template="Example_PageBuilderQuote/content-type/example-quote/default/preview"
5449
render_template="Example_PageBuilderQuote/content-type/example-quote/default/master"
5550
reader="Magento_PageBuilder/js/master-format/read/configurable">
5651
<elements...>
57-
</appearance>
52+
</appearance>
5853
</appearances>
5954
```
6055

@@ -79,24 +74,24 @@ The Quote `preview_template` (`preview.html`) is shown here in full, followed b
7974
class="pagebuilder-content-type"
8075
css="data.main.css"
8176
event="{ mouseover: onMouseOver, mouseout: onMouseOut }, mouseoverBubble: false">
82-
<render args="getOptions().template" />
83-
<blockquote attr="data.quote.attributes"
77+
<render args="getOptions().template" />
78+
<blockquote attr="data.quote.attributes"
8479
ko-style="data.quote.style"
8580
css="data.quote.css"
8681
data-bind="liveEdit: { field: 'quote_text', placeholder: $t('Enter Quote') }">
87-
</blockquote>
88-
<div class="quote-author"
82+
</blockquote>
83+
<div class="quote-author"
8984
attr="data.author.attributes"
9085
ko-style="data.author.style"
9186
css="data.author.css"
9287
data-bind="liveEdit: { field: 'quote_author', placeholder: $t('Enter Author') }">
93-
</div>
94-
<div class="quote-title"
88+
</div>
89+
<div class="quote-title"
9590
attr="data.author_title.attributes"
9691
ko-style="data.author_title.style"
9792
css="data.author_title.css"
9893
data-bind="liveEdit: { field: 'quote_author_desc', placeholder: $t('Enter Description') }">
99-
</div>
94+
</div>
10095
</div>
10196
```
10297

@@ -109,8 +104,8 @@ The value for `attr` is derived from the `element` name in the configuration fil
109104
```xml
110105
<!-- quote.xml -->
111106
<element name="quote">
112-
<html name="quote_text" converter="Magento_PageBuilder/js/converter/html/tag-escaper"/>
113-
<css name="quote_css"/>
107+
<html name="quote_text" converter="Magento_PageBuilder/js/converter/html/tag-escaper"/>
108+
<css name="quote_css"/>
114109
</element>
115110
```
116111

@@ -123,15 +118,15 @@ The `ko-style` attribute applies the `<style>` attributes from the form to a tem
123118
```xml
124119
<!-- quote.xml -->
125120
<element name="main">
126-
<style name="text_align" source="text_align"/>
127-
<style name="border" source="border_style" converter="Magento_PageBuilder/js/converter/style/border-style"/>
128-
<style name="border_color" source="border_color"/>
129-
<style name="background_color" source="background_color"/>
130-
<style name="border_width" source="border_width" converter="Magento_PageBuilder/js/converter/style/border-width"/>
131-
<style name="border_radius" source="border_radius" converter="Magento_PageBuilder/js/converter/style/remove-px"/>
132-
<style name="margins" storage_key="margins_and_padding" reader="Magento_PageBuilder/js/property/margins" converter="Magento_PageBuilder/js/converter/style/margins"/>
133-
<style name="padding" storage_key="margins_and_padding" reader="Magento_PageBuilder/js/property/paddings" converter="Magento_PageBuilder/js/converter/style/paddings"/>
134-
...
121+
<style name="text_align" source="text_align"/>
122+
<style name="border" source="border_style" converter="Magento_PageBuilder/js/converter/style/border-style"/>
123+
<style name="border_color" source="border_color"/>
124+
<style name="background_color" source="background_color"/>
125+
<style name="border_width" source="border_width" converter="Magento_PageBuilder/js/converter/style/border-width"/>
126+
<style name="border_radius" source="border_radius" converter="Magento_PageBuilder/js/converter/style/remove-px"/>
127+
<style name="margins" storage_key="margins_and_padding" reader="Magento_PageBuilder/js/property/margins" converter="Magento_PageBuilder/js/converter/style/margins"/>
128+
<style name="padding" storage_key="margins_and_padding" reader="Magento_PageBuilder/js/property/paddings" converter="Magento_PageBuilder/js/converter/style/paddings"/>
129+
...
135130
</element>
136131
```
137132

@@ -178,23 +173,24 @@ The Quote `render_template` (`master.html`) is shown here in full. The same attr
178173
```html
179174
<!--master.html-->
180175
<div attr="data.main.attributes">
181-
<blockquote attr="data.quote.attributes"
176+
<blockquote class="quote-content"
177+
attr="data.quote.attributes"
182178
ko-style="data.quote.style"
183179
css="data.quote.css"
184180
html="data.quote.html">
185-
</blockquote>
186-
<div class="quote-author"
181+
</blockquote>
182+
<div class="quote-author"
187183
attr="data.author.attributes"
188184
ko-style="data.author.style"
189185
css="data.author.css"
190186
html="data.author.html">
191-
</div>
192-
<div class="quote-title"
187+
</div>
188+
<div class="quote-title"
193189
attr="data.author_title.attributes"
194190
ko-style="data.author_title.style"
195191
css="data.author_title.css"
196192
html="data.author_title.html">
197-
</div>
193+
</div>
198194
</div>
199195
```
200196

@@ -221,8 +217,8 @@ The `html` value is derived from the configuration `element` name (`quote`) and
221217

222218
```xml
223219
<element name="quote">
224-
<html name="quote_text" converter="Magento_PageBuilder/js/converter/html/tag-escaper"/>
225-
...
220+
<html name="quote_text" converter="Magento_PageBuilder/js/converter/html/tag-escaper"/>
221+
...
226222
</element>
227223
```
228224

0 commit comments

Comments
 (0)