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
+25-5Lines changed: 25 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,32 +5,52 @@ The development of this tutorial is currently **IN PROGRESS**.
5
5
6
6
***
7
7
8
-
Page Builder comes with 16 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 quotations on a page.
8
+
Page Builder comes with 16 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 quotations within your storefront.
Page Builder creates content types from a module with UI components. This tutorial assumes you have a basicmodule structure (as follows) in which to add your content type files.
26
+
This tutorial assumes you are starting with a basic, registered module, as follows.
The steps for building the Quote content type are illustrated and described below. While the reality is not quite this linear, these steps do represent the basic phases and flow for building new Page Builder content types.
1.**Add configuration**: Create an XML file to define your content type and reference the other files that control the appearances and behaviors of your content type.
38
+
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.
23
39
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).
24
40
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).
25
41
4.**Add form**: Create a UI component form and a layout so users can edit your content type within the Page Builder editor.
26
42
5.**Add styles**: Create LESS files to style your content types when rendered in the Admin UI and on the storefront.
27
43
6.**Add frontend widget**: Create a JavaScript file to control the UI behavior (user interactivity) of your content type on the storefront.
28
44
29
-
## Content type files
45
+
## File structure
30
46
31
-
The files you will need to create in order to build a basic content type are shown here.
47
+
Before you get started, take a look at what you will be building. The block on the left shows the empty module structure you will start with. The block on the right shows all the files you will add to your module, labeled by the steps in the process.
32
48
33
49
34
50
51
+
## Conventions
52
+
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
+98-27Lines changed: 98 additions & 27 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,65 +5,87 @@ The development of this tutorial is currently **IN PROGRESS**.
5
5
6
6
***
7
7
8
-
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/`):
8
+
The configuration file defines the basic settings and files that compose your content type.
9
+
10
+
## Convention
11
+
12
+
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`.
13
+
14
+
The name of your configuration file should also reflect the name of your content type. Our example content type is called Quote, so we should name our configuration file `quote.xml` and add it to our module within the following directory structure (`view/adminhtml/pagebuilder/content_type/`):
The file name should reflect the name of your content type. Use underscores to separate multi-word names as needed.
18
+
{: .bs-callout .bs-callout-info }
19
+
If your content type name uses multiple words, use underscores to separate the words in the name.
13
20
14
21
## Example configuration
15
22
16
23
{: .bs-callout .bs-callout-info }
17
-
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).
24
+
In this example, only a subset of configuration elements are described (enough to understand the configuration file's basic role). For more details, refer to [Content type configurations](../configurations/content-type-configuration.md) and [Additional configurations](../configurations/additional-configurations.md).
18
25
19
26
20
-
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.
27
+
The following configuration shows the complete configuration file for our Quote content type. An overview of these elements and attributes are described in the tables that follow.
@@ -78,26 +100,75 @@ The `<type>` node defines the key properties of your content type. The attribute
78
100
|`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. |
79
101
|`translate`| Identifies the attribute you want Magento to translate. Here, the `label` value is set for translation. |
80
102
81
-
## The `appearance` node
103
+
## The `children` element
104
+
105
+
The `children` element determines if your content type can contain other content types as children. In the Admin UI, it either allows or prevents you from dragging and dropping *other* content types from the panel into *your* content type.
106
+
107
+
```xml
108
+
<childrendefault_policy="deny"/>
109
+
```
110
+
111
+
In our configuration, we don't allow any other content types to be children of our content type. Put another way, our content type cannot be a parent; we only want it to be the child of other content types, which leads us to the `parents` element.
112
+
113
+
## The `parents` element
82
114
83
-
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).
115
+
The `parents` element determines if other content types can be a parent to your content type. In the Admin UI, it either allows or prevents you from dragging and dropping *your* content type into *other* content types on the stage.
116
+
117
+
```xml
118
+
<parentsdefault_policy="deny">
119
+
<parentname="column"policy="allow"/>
120
+
</parents>
121
+
```
122
+
123
+
In our configuration, the `parents` element first prevents our content type from having any parents. If we left it there, we could not drag our content type onto the stage at all because even the stage is a parent. So we limit our content type's parents to only one: the `column` content type. This allows you to drag and drop your content type into columns, but nowhere else.
124
+
125
+
## The `appearances` element
126
+
127
+
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`):
132
+
133
+
```xml
134
+
<appearances>
135
+
<appearancename="collage-left"...>
136
+
<appearancename="collage-centered"...>
137
+
<appearancename="collage-right"...>
138
+
<appearancename="poster"default="true" ...>
139
+
</appearances>
140
+
```
141
+
142
+
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).
143
+
144
+
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.|
90
163
|`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. |
91
-
|`preview_template`|`preview.html` - the HTML template for rendering the preview appearance of a content type within the Admin. |
92
-
|`render_template`|`master.html` - the HTML template for rendering the storefront appearance of a content type for customers. |
93
-
|`reader`| Reads data for the content type from the master format |
94
-
95
-
All content types must have at least one `<appearance>` defined within the `<appearances>` node.
164
+
|`preview_template`|`preview.html` - the HTML template for rendering the preview appearance of a content type on the Admin stage during page development. |
165
+
|`render_template`|`master.html` - the HTML template for rendering the storefront appearance of a content type for customers. |
166
+
|`reader`| Reads data for the content type from the master format |
96
167
97
-
## The `elements`node
168
+
## The `elements`element
98
169
99
-
The purpose of `<elements>`node in the configuration is to map the data from the form 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.
170
+
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. These elements will be explained more fully in [Step 4: Add form](step-4-add-form.md)
100
171
101
172
## Next
102
173
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).
0 commit comments