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
@@ -53,4 +53,4 @@ Before you get started, take a look at what you will be building. The block on t
53
53
The file structure represents an overview of the conventions used for content types. Many of the conventions used are simply those defined for developing UI components. However, the conventions specific to Page Builder start within the directories called `content_type` or `content-type`. Page Builder instantiates a content type from the files defined within these directories. We discuss these conventions within each step of the process.
Copy file name to clipboardExpand all lines: docs/create-basic-content-type/step-1-add-configuration.md
+4-27Lines changed: 4 additions & 27 deletions
Original file line number
Diff line number
Diff line change
@@ -103,9 +103,9 @@ In our configuration, the `parents` element first prevents our content type from
103
103
104
104
The `<appearances>` element specifies one or more views for displaying your content type. For example, the Banner has four appearances you can choose from within its editor as shown here:
Each of these appearances are defined as an `appearance` within the Banner configuration file (`app/code/Magento/PageBuilder/view/adminhtml/pagebuilder/content_type/banner.xml`):
108
+
Each of these views is defined as an `appearance` within the Banner configuration file (`app/code/Magento/PageBuilder/view/adminhtml/pagebuilder/content_type/banner.xml`):
109
109
110
110
```xml
111
111
<appearances>
@@ -118,34 +118,11 @@ Each of these appearances are defined as an `appearance` within the Banner confi
118
118
119
119
Going further, each `appearance` is defined by exactly two HTML templates, one to display a preview appearance in the Admin (`preview.html`) and the other to display the master appearance (`master.html`) on your storefront. We will discuss HTML templates more in [Step 2: Add templates](step-2-add-templates.md).
120
120
121
-
Our Quote only has one appearance, so we define it as the default:
|`name`| Name of the appearance so it can be extended as needed. |
140
-
|`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. |
141
-
|`preview_template`|`preview.html` - the HTML template for rendering the preview appearance of a content type on the Admin stage during page development. |
142
-
|`render_template`|`master.html` - the HTML template for rendering the storefront appearance of a content type for customers. |
143
-
|`reader`| Reads data for the content type from the master format |
144
-
145
121
## The `elements` element
146
122
147
123
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)
@@ -5,31 +5,45 @@ The development of this tutorial is currently **IN PROGRESS**.
5
5
6
6
***
7
7
8
-
Content type templates are the HTML files (fragments) that define how your content type *appears* on both the Admin stage and on a storefront page. In Page Builder this is called an `appearance`, as discussed in the previous configuration step.
8
+
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:
9
9
10
-
Each `appearance` is defined by exactly two HTML template files: `preview.html` and `master.html`. For example, if you look at the template files for the Page Builder Banner, you see a set of these templates defined for each of Banner's four appearances:
In contrast, the Block content type only has one `appearance`, so it defines it as the default with one set of master-preview template files.
14
+
Conventions for adding content type templates are as follows.
15
15
16
-
## Conventions
16
+
- Page Builder requires you to name your templates `preview.html` for the Admin template and `master.html` for the storefront template.
17
17
18
-
Conventions for adding content type templates are as follows:
18
+
- Page Builder requires the name of an `appearance` to match the name of the directory containing the appearance templates. For example, `default` is the conventional name for content types with only one `appearance`. Therefore, the directory name should also be `default`.
19
19
20
-
- Page Builder requires at least one `appearance` (two HTML templates) for every contenttype: `preview.html` for the Admin stage, `master.html` for the storefront page. If your content type has only one appearance (like the Block), then it only needs these two templates.
20
+
If you navigate to the Banner 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:
21
21
22
-
- Page Builder requires the names of your templates to be `preview` and `master`.
22
+
```xml
23
+
<appearances>
24
+
<appearancename="collage-left"...>
25
+
<appearancename="collage-centered"...>
26
+
<appearancename="collage-right"...>
27
+
<appearancename="poster"default="true" ...>
28
+
</appearances>
29
+
```
23
30
24
-
Content types cannot be rendered without these templates, so add them to your module (they can be blank initially) within the following directory structure (`view/adminhtml/web/template/content-type/<content-type-name>/default/`):
As mentioned, these files can be empty initially; they just need to exist in their proper location within your module.
34
+
## Template Configuration
29
35
30
-
## Configuration
36
+
The Quote example defines only one `appearance`. Therefore, by convention, set the names of the Quote `appearance` and the template directory to `default` as shown in the code and directory structure that follows:
31
37
32
-
In your configuration file, you need to reference your templates within the `<appearance>` element as follows:
These files can be blank initially; they just need to exist in their proper location for now so we can reference them in the `appearance` element of our `quote.xml` configuration file as shown here:
33
47
34
48
```xml
35
49
<appearances>
@@ -43,11 +57,174 @@ In your configuration file, you need to reference your templates within the `<ap
|`name`| As noted by convention, the name of the appearance and the name of the directory for the appearance templates *must* match. |
65
+
|`default`| Every content type must have a default appearance. If you only define one appearance for your content type, you must set the default to `true`. |
48
66
|`preview_template`| References the`preview.html` template for rendering the preview appearance of your content type on the stage within the Admin UI. |
49
-
|`render_template`| References the `master.html` template for rendering the appearance of your content type on the storefront for customers to see. |
67
+
|`render_template`| References the `master.html` template for rendering the appearance of your content type on the storefront for customers to see. |
68
+
|`reader`| Reads data for the content type from the master format. |
69
+
70
+
## Quote `preview.html`
71
+
72
+
The `preview.html` template defined for the Quote appearance, is shown here in full followed by descriptions to help you understand the basics of this template.
The `attr` attribute allows binding of data from the content type form (UI component) to the html elements in the template. Without defining the `attr` for an HTML element in your template, bindings like `ko-style`, `css`, `html`, and `events` won't work.
105
+
106
+
The value for `attr` is derived from the `element` name in the configuration file followed by `attributes`. For example, the `attr` value used to bind data for the `blockquote` on line 8 of the Quote `preview.html` is `attr="data.quote.attributes"`. This corresponds to the `element` named `quote` in the `quote.xml` configuration file, as shown here:
The nodes declared within an `element` define the bindings that can be applied to your templates.
117
+
118
+
### ko-style
119
+
120
+
The `ko-style` attribute applies the `<style>` attributes from the form to a template element. For example, the `main` element for the Quote configuration defines several style bindings as shown here:
As we discuss more in [Step 4: Add form](step-4-add-form.md), the `element` styles define bindings to fields in our form. In turn, these form fields provide user-entered data or default values that we apply to the HTML elements in our templates using the `k0-style` attribute.
138
+
139
+
The following snippet shows the `ko-style` (Knockout binding) that applies the styles defined in the main `element` to the `div` node of the Quote's preview template:
The `ko-style` value is derived from the configuration `element` name (`main`) and the attribute to be bound (`style`) to give us `data.main.style`.
149
+
150
+
### css
151
+
152
+
The `css` attribute applies CSS classes entered by users on the form to a template element. More on this when we discuss forms in [Step 4: Add form](step-4-add-form.md).
153
+
154
+
### class
155
+
156
+
Just as with any other html template, you can add your own classes to your template elements. Defining those classes for your content type is discussed in [Step 5: Add styles](step-5-add-styles.md).
157
+
158
+
### liveEdit
159
+
160
+
The `liveEdit` binding enables end users to enter HTML content directly on the Admin stage. The basic usage from the Quote control includes specifying the form field it binds to and adding placeholder text as follows:
The `master.html` template defined for the Quote appearance is shown here in full. The same attributes and descriptions from the preview template apply to this template as well, with one addition, the `html` attribute.
176
+
177
+
```html
178
+
<!--master.html-->
179
+
<divattr="data.main.attributes">
180
+
<blockquoteattr="data.quote.attributes"
181
+
ko-style="data.quote.style"
182
+
css="data.quote.css"
183
+
html="data.quote.html">
184
+
</blockquote>
185
+
<divclass="quote-author"
186
+
attr="data.author.attributes"
187
+
ko-style="data.author.style"
188
+
css="data.author.css"
189
+
html="data.author.html">
190
+
</div>
191
+
<divclass="quote-title"
192
+
attr="data.author_title.attributes"
193
+
ko-style="data.author_title.style"
194
+
css="data.author_title.css"
195
+
html="data.author_title.html">
196
+
</div>
197
+
</div>
198
+
```
199
+
200
+
### html
201
+
202
+
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.
Copy file name to clipboardExpand all lines: docs/create-basic-content-type/step-3-add-components.md
-2Lines changed: 0 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -28,8 +28,6 @@ In your configuration file, reference your JavaScript component (`preview.js`) a
28
28
| `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. |
29
29
| `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). |
30
30
31
-
{:style="table-layout:auto"}
32
-
33
31
## Location
34
32
35
33
Add them to your module here (`view/adminhtml/web/js/content-type/<content-type-name>/`):
0 commit comments