You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/create-basic-content-type/overview.md
+7-7Lines changed: 7 additions & 7 deletions
Original file line number
Diff line number
Diff line change
@@ -1,4 +1,4 @@
1
-
# Introduction
1
+
# Overview
2
2
3
3
***
4
4
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
11
11
12
12
## Quote preview
13
13
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 screenshotshows three instances of the Quote control you will build in this tutorial:
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.
44
44
5.**Add styles**: Create LESS files to style your content types when rendered in the Admin UI and on the storefront.
45
45
6.**Add frontend widget**: Create a JavaScript file to control the UI behavior (user interactivity) of your content type on the storefront.
46
46
@@ -55,4 +55,4 @@ Before we get started, take a look at what you will be building. The directory s
55
55
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.
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.
17
17
18
18
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/`):
19
19
@@ -22,9 +22,9 @@ The name of your configuration file should reflect the name of your content type
22
22
{: .bs-callout .bs-callout-info }
23
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.
24
24
25
-
## Example configuration
25
+
## The `example_quote` configuration
26
26
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).
28
28
29
29
30
30
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
69
69
|`label`| Label displayed in the Page Builder panel, option menu, and on the Admin stage. |
70
70
|`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. |
71
71
|`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`. |
74
74
|`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. |
76
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. |
77
77
|`translate`| Identifies the attribute you want Magento to translate. Here, the `label` value is set for translation. |
78
78
@@ -119,7 +119,7 @@ Going further, each `appearance` is defined by exactly two HTML templates, one t
119
119
120
120
## The `elements` element
121
121
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)
Copy file name to clipboardExpand all lines: docs/create-basic-content-type/step-2-add-templates.md
+11-10Lines changed: 11 additions & 10 deletions
Original file line number
Diff line number
Diff line change
@@ -17,7 +17,7 @@ Conventions for adding content type templates are as follows.
17
17
18
18
- 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.
19
19
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:
21
21
22
22
```xml
23
23
<appearances>
@@ -68,9 +68,9 @@ The following table describes each `appearance` attribute in our example.
68
68
|`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. |
69
69
|`reader`| Reads content type data from the master format. |
70
70
71
-
## Quote `preview.html`
71
+
## Quote `preview_template`
72
72
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.
74
74
75
75
```html
76
76
<!-- preview.html -->
@@ -154,7 +154,7 @@ The `css` attribute applies CSS classes entered by users on the form to a templa
154
154
155
155
### class
156
156
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).
158
158
159
159
### liveEdit
160
160
@@ -171,9 +171,9 @@ The `liveEdit` binding enables end users to enter HTML content directly on the A
171
171
172
172
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.
173
173
174
-
## Quote `master.html`
174
+
## Quote `render_template`
175
175
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.
177
177
178
178
```html
179
179
<!--master.html-->
@@ -200,17 +200,17 @@ The `master.html` template defined for the Quote appearance is shown here in ful
200
200
201
201
### html
202
202
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'...}`):
0 commit comments