Skip to content

Commit badb5e3

Browse files
committed
MC-6270: Add docs for content type components
commit 160c017 Merge: d6cd01b a80ff0d Author: Bruce Denham <bdenham@adobe.com> Date: Mon Dec 17 02:51:54 2018 -0600 Merge pull request #7 from magento-devdocs/MC-5769 MC-5769: Complete content type tutorial commit a80ff0d Merge: 8e21928 4b574a1 Author: Bruce Denham <bdenham@adobe.com> Date: Mon Dec 17 02:39:07 2018 -0600 Merge branch 'MC-5769' of github.com:magento-devdocs/magento2-page-builder into MC-5769 commit 8e21928 Author: Bruce Denham <bdenham@adobe.com> Date: Mon Dec 17 02:38:49 2018 -0600 MC-5769: Complete content type tutorial Updated from PR review. commit d6cd01b Merge: 5ea0280 4b574a1 Author: Bruce Denham <bdenham@adobe.com> Date: Mon Dec 17 02:35:00 2018 -0600 Merge pull request #5 from magento-devdocs/MC-5769 MC-5769: Complete content type tutorial commit 4b574a1 Author: Kevin Harper <keharper@users.noreply.github.com> Date: Mon Dec 17 02:14:14 2018 -0600 MC-5769: Complete content type tutorial Updated from suggestion feature Co-Authored-By: bdenham <bdenham@adobe.com> commit b3d4dcb Author: Kevin Harper <keharper@users.noreply.github.com> Date: Mon Dec 17 02:13:10 2018 -0600 MC-5769: Complete content type tutorial Updated from suggestion feature Co-Authored-By: bdenham <bdenham@adobe.com> commit 939ef44 Author: Kevin Harper <keharper@users.noreply.github.com> Date: Mon Dec 17 02:11:46 2018 -0600 MC-5769: Complete content type tutorial Updated from suggestion feature Co-Authored-By: bdenham <bdenham@adobe.com> commit a8fe52c Author: Kevin Harper <keharper@users.noreply.github.com> Date: Mon Dec 17 02:11:20 2018 -0600 MC-5769: Complete content type tutorial Updated from suggestion feature Co-Authored-By: bdenham <bdenham@adobe.com> commit f9a637e Author: Kevin Harper <keharper@users.noreply.github.com> Date: Mon Dec 17 02:10:47 2018 -0600 MC-5769: Complete content type tutorial Updated from suggestion feature Co-Authored-By: bdenham <bdenham@adobe.com> commit 471781b Author: Bruce Denham <bdenham@adobe.com> Date: Sun Dec 16 10:44:17 2018 -0600 MC-5769: Complete content type tutorial Minor updates commit 82efac4 Author: Bruce Denham <bdenham@adobe.com> Date: Sat Dec 15 21:35:42 2018 -0600 MC-5769: Complete content type tutorial fixed typo commit 5ea0280 Merge: c83410a d4d31a7 Author: Cari Spruiell <spruiell@adobe.com> Date: Mon Dec 10 14:44:58 2018 -0600 Merge pull request #181 from magento-obsessive-owls/1.0.0-beta-release Sync Develop w/ 1.0.0-Beta-Release Branch commit c83410a Merge: 9ebaf06 e04033e Author: Dave Macaulay <daavem@googlemail.com> Date: Tue Nov 20 11:05:23 2018 +0100 Merge pull request #177 from magento/1.0.0-release Sync develop with release branch
1 parent cb1c691 commit badb5e3

File tree

4 files changed

+26
-25
lines changed

4 files changed

+26
-25
lines changed

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

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Introduction
1+
# Overview
22

33
***
44
The development of this tutorial is currently **IN PROGRESS**.
@@ -11,11 +11,11 @@ Page Builder comes with several content types (controls) you can use to build yo
1111

1212
## Quote preview
1313

14-
A preview of the Qoute content type you will build is shown in the following screenshot, which shows three instances of the Quote control, on in each column shown here on the Admin stage:
14+
The following screenshot shows three instances of the Quote control you will build in this tutorial:
1515

1616
![QuoteTypeDisplay](../images/AdminTestimonials.png)
1717

18-
And here are the same three Quote controls rendered on a mock testimonial page in the storefront:
18+
And the same three Quote controls are shown rendered here on a mock testimonial page in the storefront:
1919

2020
![StorefrontTestimonials](../images/StorefrontTestimonials.png)
2121

@@ -38,9 +38,9 @@ The steps for creating the Quote content type are illustrated and described belo
3838
![Creating Custom Content Types](../images/content-type-overview.png)
3939

4040
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.
41-
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).
42-
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).
43-
4. **Add form**: Create a UI component form and a layout so users can edit your content type within the Page Builder editor.
41+
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`).
42+
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`).
43+
4. **Add form**: Create a UI component form and a layout so Admin users can edit your content type within the Page Builder editor.
4444
5. **Add styles**: Create LESS files to style your content types when rendered in the Admin UI and on the storefront.
4545
6. **Add frontend widget**: Create a JavaScript file to control the UI behavior (user interactivity) of your content type on the storefront.
4646

@@ -55,4 +55,4 @@ Before we get started, take a look at what you will be building. The directory s
5555
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.
5656

5757
## Next
58-
[Step 1: Add configuration](step-1-add-configuration.md)
58+
[Step 1: Add configuration](step-1-add-configuration.md)

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

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,9 @@ Files referenced from the configuration include the HTML templates, the JavaScri
1111

1212
![configuration-hub](../images/configuration-hub.png)
1313

14-
## Conventions
14+
## Configuration conventions
1515

16-
By convention, Page Builder requires the configuration for a content type to be in the `adminhtml` area within a directory named `pagebuilder` and a subdirectory named `content_type` or `content-type`.
16+
By convention, Page Builder requires the configuration file to be in the `<module_name>/adminhtml/pagebuilder/content_type` or `content-type` directory.
1717

1818
The name of your configuration file should reflect the name of your content type prefixed by your module vendor name and separated by an underscore (_). For example, our module name is `Example/PageBuilderQuote` and our content type is a quote control, so we name our configuration file `example_quote.xml` and add it to our module within the following directory structure (`view/adminhtml/pagebuilder/content_type/`):
1919

@@ -22,9 +22,9 @@ The name of your configuration file should reflect the name of your content type
2222
{: .bs-callout .bs-callout-info }
2323
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.
2424

25-
## Example configuration
25+
## The `example_quote` configuration
2626

27-
In this example, only a subset of configuration elements are described in our Quote example (enough to understand the basic role of the configuration file). For more details, refer to [Content type configurations](../configurations/content-type-configuration.md) and [Additional configurations](../configurations/additional-configurations.md).
27+
Only a subset of configuration elements are described in our Quote example (enough to understand the basic role of the configuration file). For more details, refer to [Content type configurations](../configurations/content-type-configuration.md) and [Additional configurations](../configurations/additional-configurations.md).
2828

2929

3030
The following configuration is from the Quote content type. An overview of these elements and attributes are described in the tables that follow.
@@ -69,10 +69,10 @@ The `type` element defines the key properties of your content type. The attribut
6969
| `label` | Label displayed in the Page Builder panel, option menu, and on the Admin stage. |
7070
| `group` | Group or category in the panel menu where your content type is displayed. The default groups are Layout, Elements, Media, and Add Content. See [Panel configurations](../configurations/panel-configurations.md) for more details. |
7171
| `component` | 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. Use `Magento_PageBuilder/js/content-type-collection` for content types that can contain children, otherwise known as container content types. |
72-
| `preview_component` | Optional. JavaScript file (`preview.js`) that provides rendering logic within the Admin UI. |
73-
| `master_component` | Optional. JavaScript file (`master.js`) that provides rendering logic generic for all appearances of your content type when rendered on the storefront. |
72+
| `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`. |
73+
| `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`. |
7474
| `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. |
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. |
7676
| `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. |
7777
| `translate` | Identifies the attribute you want Magento to translate. Here, the `label` value is set for translation. |
7878

@@ -119,7 +119,7 @@ Going further, each `appearance` is defined by exactly two HTML templates, one t
119119

120120
## The `elements` element
121121

122-
The purpose of `<elements>` as defined within an appearance is to map the data from the content type's edit form to the content type's master format so that the values entered in the form can be stored and rendered correctly on the Admin stage and storefront. We will describe the `elements` in [Step 4: Add form](step-4-add-form.md)
122+
The `<elements>` element as defined within an `appearance` is to map the data from the content type's form editor to the content type's master format so that the values entered in the form can be stored and rendered correctly on the Admin stage and storefront. We discuss content type `elements` in [Step 4: Add form](step-4-add-form.md)
123123

124124
## Next
125125

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

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ Conventions for adding content type templates are as follows.
1717

1818
- Page Builder requires the name of an `appearance` to match the name of the directory containing the appearance templates. If they don't match, your content type appearances will not render.
1919

20-
For example, if you navigate to the Banner's appearance templates (`app/code/Magento/PageBuilder/view/adminhtml/web/template/content-type/banner`) you can see that the names of the template directories match the names of the four appearances defined in the `banner.xml` configuration file as shown here:
20+
For example, if you navigate to the Banner's appearance templates (`PageBuilder/view/adminhtml/web/template/content-type/banner`) you can see that the names of the template directories match the names of the four appearances defined in the `banner.xml` configuration file as shown here:
2121

2222
```xml
2323
<appearances>
@@ -68,9 +68,9 @@ The following table describes each `appearance` attribute in our example.
6868
| `render_template` | References the `master.html` (the master format storefront template) for rendering the appearance of your content type on the storefront for customers to see. |
6969
| `reader` | Reads content type data from the master format. |
7070

71-
## Quote `preview.html`
71+
## Quote `preview_template`
7272

73-
The `preview.html` template defined for our Quote's appearance, is shown here in full followed by descriptions to help you understand the basics of this template.
73+
The Quote `preview_template` (`preview.html`) is shown here in full, followed by the attribute descriptions to help you understand the basics of content type templates.
7474

7575
```html
7676
<!-- preview.html -->
@@ -154,7 +154,7 @@ The `css` attribute applies CSS classes entered by users on the form to a templa
154154

155155
### class
156156

157-
Just as with any other html template, you can add your own classes to your template elements. However, you should **always add the `pagebuilder-content-type` as the first class in the top node in your `preview.html` template** as shown for the Quote. Page Builder uses the `pagebuilder-content-type` class to add visual indicators and mouseover effects to the Admin preview template, such as correctly positioning the options menu. Defining custom LESS/CSS classes for your content type is discussed in [Step 5: Add styles](step-5-add-styles.md).
157+
Just as with any other HTML template, you can add your own classes to your template elements. However, **always add the `pagebuilder-content-type` as the first class in the top node in your `preview.html` template** as shown for the Quote. Page Builder uses the `pagebuilder-content-type` class to add visual indicators and mouseover effects to the Admin preview template, such as correctly positioning the options menu. Defining custom LESS/CSS classes for your content type is discussed in [Step 5: Add styles](step-5-add-styles.md).
158158

159159
### liveEdit
160160

@@ -171,9 +171,9 @@ The `liveEdit` binding enables end users to enter HTML content directly on the A
171171

172172
The `event` attribute enables the options menu to be shown and hidden when users interact with the content type using the mouse. If you have a special circumstance with the way you wish to handle your option menus, you can modify this logic to suit your needs.
173173

174-
## Quote `master.html`
174+
## Quote `render_template`
175175

176-
The `master.html` template defined for the Quote appearance is shown here in full. The same attributes and descriptions from the Admin preview template apply to this template as well, with one addition, the `html` attribute.
176+
The Quote `render_template` (`master.html`) is shown here in full. The same attributes and descriptions from the `preview.html` template apply to the `master.html` template as well. However, the `master.html` template introduces one addition attribute, `html`, which is described after the code.
177177

178178
```html
179179
<!--master.html-->
@@ -200,17 +200,17 @@ The `master.html` template defined for the Quote appearance is shown here in ful
200200

201201
### html
202202

203-
The `html` attribute applies the actual user-entered HTML to the template element. In our Quote example, the end-user enters their quote text either from the Admin stage using `liveEdit`, which is bound to the `quote_text` field, or from the form.
203+
The `html` attribute applies the actual user-entered HTML content to the template element. In our Quote example, the end-user enters their quote text either on the Admin stage using `liveEdit` (which is bound to the `quote_text` field in the form editor) or on the form, directly into the`quote_text` field itself.
204+
205+
For example, from the Quote `preview.html` template, the `liveEdit` binding on the `blockquote` is bound to the `quote_text` field that stores the HTML content, as shown here (`{ field: 'quote_text'...}`):
204206

205207
```html
206208
<!--preview.html-->
207209
<blockquote data-bind="liveEdit: { field: 'quote_text', placeholder: $t('Enter Quote') }">
208210
</blockquote>
209211
```
210212

211-
From `liveEdit`, we see that the content of `blockquote` is bound to the `quote_text` field that stores the html.
212-
213-
The master format storefront template uses the `html` attribute to retrieve the HTML content and display it in the `blockquote` element:
213+
The master format storefront template uses the `html` attribute to retrieve the HTML content and display it in the `blockquote` element as follows:
214214

215215
```html
216216
<!--master.html-->
@@ -223,6 +223,7 @@ The `html` value is derived from the configuration `element` name (`quote`) and
223223
<element name="quote">
224224
<html name="quote_text" converter="Magento_PageBuilder/js/converter/html/tag-escaper"/>
225225
...
226+
</element>
226227
```
227228

228229
## Next

docs/images/content-type-files.png

68 Bytes
Loading

0 commit comments

Comments
 (0)