Skip to content

Commit 330537c

Browse files
bdenhambdenham
authored
Merge pull request #6 from magento-devdocs/MC-6270
MC-6270: Add docs for content type component
2 parents 160c017 + afc8cd0 commit 330537c

File tree

6 files changed

+158
-14
lines changed

6 files changed

+158
-14
lines changed

‎docs/configurations/option-menu-configurations.md

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
11
# Option menu configurations
22

3-
{: .bs-callout .bs-callout-info }
4-
The development of this topic is currently **IN PROGRESS**.
3+
---
4+
5+
The development of this topic is currently **IN PROGRESS**.
6+
7+
---
8+

‎docs/create-basic-content-type/step-3-add-components.md

Lines changed: 152 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,52 @@ The development of this tutorial is currently **IN PROGRESS**.
55

66
***
77

8-
Components are the JavaScript files that define the behaviors of your content type when they appear on the stage in the Admin UI (using the `preview.js` component) and in the storefront (using the `master.js` component). As such, they are complementary to the templates you added previously in Step 2, acting as the view models to the template's views.
8+
In this step, we will create a preview component in order to customize the options menu for our Quote. The options menu is the popup menu that appears when you mouseover a content type, as shown here:
99

10-
## Configuration
10+
![Create config file](../images/options-menu-default.png)
1111

12-
In your configuration file, reference your JavaScript component (`preview.js`) as shown here within the `type` element:
12+
The options menu provides end-users with several functions, including a button to open the content type's form editor, which we will add in [Step 4: Add form](step-4-add-form.md).
13+
14+
## About components
15+
16+
Components are JavaScript files that define the behaviors of your content type when they appear on the Admin stage (using the `preview.js` component) and in the storefront (using the `master.js` component). As such, they are complementary to the templates you added previously in Step 2, acting as the view models to the template's views.
17+
18+
Adding custom component files to your content types is completely optional. Whether you need one or not will depend on the complexity of your content type. If you do not add components to your content type, Page Builder will use these defaults:
19+
20+
- Default preview component: `Magento_PageBuilder/js/content-type/preview`
21+
- Default master component: `Magento_PageBuilder/js/content-type/master`
22+
23+
When you start developing more complex content types, you will need to create custom preview components in order to make these and other functions available on the Admin stage:
24+
25+
- Initiating and using additional 3rd party libraries like sliders and tabs.
26+
- Adding image uploader support.
27+
- Providing dynamic data into your preview templates from the back-end.
28+
- Allowing the back-end to conduct rendering (such as our block and dynamic block content types).
29+
- Declaring special states based on the data stored, for example, showing a disabled state when certain fields are set to specific values.
30+
31+
Examples of implementing these functions will be add to future tutorials and other topics in this documentation.
32+
33+
Adding your own master component is far less common. The master component is only necessary if you want to manipulate the final output of your content type before it is persisted to the database.
34+
35+
## Component conventions
36+
37+
The conventions for naming your components and adding them to your module are as follows:
38+
39+
- Your preview component must be named `preview.js` and placed here in your module (`view/adminhtml/web/js/content-type/example-quote/`):
40+
41+
![Create config file](../images/step3-add-component.png)
42+
43+
- Your master component must be named `master.js` and placed here in your module (`view/frontend/web/js/content-type/example-quote/`):
44+
45+
![Create config file](../images/step3-add-master-component.png)
46+
47+
We will not create a master component for our Quote example, but the location is given here if you need to include one for more complex content types.
48+
49+
Before continuing, add the preview component file (`preview.js`) to your `PageBuilderQuote` module within the directory structure noted.
50+
51+
## Component configuration
52+
53+
In your configuration file, reference your Admin `preview_component` (`preview.js`) as shown here:
1354

1455
```xml
1556
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -24,20 +65,119 @@ In your configuration file, reference your JavaScript component (`preview.js`) a
2465
</config>
2566
```
2667

27-
The following table describes each component-related attribute from the Quote configuration.
68+
A description of each component-related attribute from the Quote configuration follows:
2869

2970
| Attribute | Description |
3071
| ------------------- | ------------------------------------------------------------ |
31-
| `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 (like our Quote). Use `Magento_PageBuilder/js/content-type-collection` for content types that can contain children (container content types). |
32-
| `preview_component` | Optional. The `preview.js` file provides rendering logic to the Admin preview template. If your content type does not require any changes to the standard option menu (shown on mouseover) for a content type or other user-interactivity in the Admin, you can omit this attribute from the the `type` element. When you omit this attribute, Page Builder will use `Magento_PageBuilder/js/content-type/preview` by default. |
33-
| `master_component` | Optional. The `master.js` file provides rendering logic to the master format storefront template. 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` element. When you omit this attribute, Page Builder will use `Magento_PageBuilder/js/content-type/master` by default. In |
72+
| `component` | Page Builder provides 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 (like our Quote). Use `Magento_PageBuilder/js/content-type-collection` for content types that can contain children (container content types). You can also create and specify your own component implementations, provided they conform to the Page Builder interfaces. |
73+
| `preview_component` | Optional. The `preview.js` file provides rendering logic to the Admin preview template. If your content type does not require any changes to Page Builder's standard rendering logic, you can omit this attribute from the the `type` element. When you omit the attribute, Page Builder will use `Magento_PageBuilder/js/content-type/preview` by default.<br /><br />However, if you want to make changes to the option menu for your content type, or other customize other user-interactivity in the Admin, you need to create your own preview component as we have done for the Quote content type. |
74+
| `master_component` | Optional. The `master.js` file provides rendering logic to the master format storefront template. 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` element. When you omit the attribute, Page Builder will use `Magento_PageBuilder/js/content-type/master` by default. <br /><br />In the Quote configuration, the `master_component` attribute is only included for discussion. It simply points to the Page Builder default `master.js` component that would be used the attribute was omitted. |
3475

35-
## Location
76+
## Quote `preview_component`
3677

37-
Add them to your module here (`view/adminhtml/web/js/content-type/example-quote/`):
78+
The Quote `preview_component` (`preview.js`) example is shown here in full for you to copy into your `preview.js` file, followed by an explanation of its key parts.
3879

39-
![Create config file](../images/step3-add-component.png)
80+
```js
81+
define([
82+
'Magento_PageBuilder/js/content-type/preview',
83+
], function (PreviewBase) {
84+
'use strict';
85+
var $super;
86+
87+
function Preview(parent, config, stageId) {
88+
PreviewBase.call(this, parent, config, stageId);
89+
}
90+
91+
Preview.prototype = Object.create(PreviewBase.prototype);
92+
$super = PreviewBase.prototype;
93+
94+
Preview.prototype.retrieveOptions = function retrieveOptions() {
95+
var options = $super.retrieveOptions.call(this, arguments);
96+
97+
// Change option menu icons
98+
options.remove.icon = "<i class='icon-admin-pagebuilder-error'></i>";
99+
100+
// Change tooltips
101+
options.edit.title = "Open Editor";
102+
options.remove.title = "Delete";
103+
// options.move.title = "Move";
104+
// options.duplicate.title = "Duplicate";
105+
106+
// Remove menu options
107+
// delete options.move;
108+
// delete options.duplicate;
109+
// delete options.edit;
110+
// delete options.remove;
111+
112+
return options;
113+
};
114+
return Preview;
115+
});
116+
```
117+
118+
### Extend from `Preview`
119+
120+
The first thing we do in our preview component is extend Page Builder's `Preview` class (`magento2-page-builder/app/code/Magento/PageBuilder/view/adminhtml/web/ts/js/content-type/preview.ts`) by declaring it as a dependency and calling it from the preview component's constructor as follows:
121+
122+
```js
123+
define([
124+
'Magento_PageBuilder/js/content-type/preview',
125+
], function (PreviewBase) {
126+
'use strict';
127+
var $super;
128+
129+
function Preview(parent, config, stageId) {
130+
PreviewBase.call(this, parent, config, stageId);
131+
}
132+
133+
Preview.prototype = Object.create(PreviewBase.prototype);
134+
$super = PreviewBase.prototype;
135+
```
136+
137+
You don't have to extend `Preview` this way, but if you do, you get access to both its public and protected functions. In our Quote example, we need access to one protected function, discussed next.
138+
139+
### Customize the options menu
140+
141+
Our goal for the Quote preview component is to customize the default Page Builder options menu for a content type, as shown here:
142+
143+
![Create config file](../images/options-menu-default.png)
144+
145+
To do this, we need to override the protected `retrieveOptions()` function from the `Preview` class so we can change various options as shown here:
146+
147+
```js
148+
Preview.prototype.retrieveOptions = function retrieveOptions() {
149+
var options = $super.retrieveOptions.call(this, arguments);
150+
151+
// Change option menu icons
152+
options.remove.icon = "<i class='icon-admin-pagebuilder-error'></i>";
153+
154+
// Change tooltips
155+
options.edit.title = "Open Editor";
156+
options.remove.title = "Delete";
157+
// options.move.title = "Move";
158+
// options.duplicate.title = "Duplicate";
159+
160+
// Remove menu options
161+
// delete options.move;
162+
// delete options.duplicate;
163+
// delete options.edit;
164+
// delete options.remove;
165+
166+
return options;
167+
};
168+
```
169+
170+
In the preceding code, we made changes to the options menu icons and tooltips. You can also remove options from the menu. For example, if you don't want end-users to move or duplicate your content type, you can remove those options from your menu using `delete options.move` and `delete options.duplicate` as shown commented out in the code.
171+
172+
![Create config file](../images/options-menu-custom.png)
173+
174+
{: .bs-callout .bs-callout-info }
175+
Even though you can change the base option menu properties as described, we suggest you stick the the default options as much as possible to provide end-users with a consistent experience across Magento's content types and other third-party content types that are included as time goes on.
176+
177+
## Quote `master_component`
178+
179+
As mentioned previously, our Quote content type has no need for a master component. We are using Page Builder's default master component file: `Magento_PageBuilder/js/content-type/master`.
40180
41-
## Create preview component
181+
## Next
42182
43-
The remainder of this topic is in progress.
183+
[Step 4: Add form](step-4-add-form.md)

‎docs/images/options-menu-custom.png

27.1 KB
Loading

‎docs/images/options-menu-default.png

26.9 KB
Loading

‎docs/images/step3-add-component.png

747 Bytes
Loading

‎docs/images/step3-add-master-component.png

17.6 KB
Loading

0 commit comments

Comments
 (0)