Skip to content

Commit 286c191

Browse files
bdenhambdenham
committed
MAGEDOC-3550: How to add an appearance
Complete third and final step
1 parent ee36459 commit 286c191

File tree

3 files changed

+142
-1
lines changed

3 files changed

+142
-1
lines changed

‎docs/extend-existing-content-type/step-3-extend-forms.md

Lines changed: 142 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,145 @@
11
# Step 3: Extend forms
22

3-
In this step, you will create two forms, one for each of the Banner appearances (`collage-left` and `collage-right`).
3+
In this step, you will extend the Banner form (`pagebuilder_banner_form.xml`) by adding a form field for entering a `max-height` value for the `collage-left` and `collage-right` appearances.
44

5+
## Create the appearance forms
6+
7+
Page Builder forms are UI component forms. This means they follow the same conventions as any other UI component form. If you are not already familiar with UI component forms, you can learn more about them from the [UI Components Guide](https://devdocs.magento.com/guides/v2.3/ui_comp_guide/concepts/ui_comp_xmldeclaration_concept.html). For this tutorial, we provide you with the basic markup for setting up these forms.
8+
9+
Your file structure for the Banner extension forms and corresponding layouts should look like this:
10+
11+
![Extension forms file structure](../images/extension-forms-files.png){:width="433px" height="auto"}
12+
13+
When setting up your extension forms, ensure you are inheriting from the form of the content type you want to extend. In our case, we are extending from the Banner's form: `page-banner-form` . The basic XML configuration for both forms is as follows.
14+
15+
### `collage-left` form
16+
17+
```xml
18+
<?xml version="1.0" encoding="UTF-8"?>
19+
<form xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
20+
xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Ui:etc/ui_configuration.xsd"
21+
extends="pagebuilder_banner_form">
22+
<argument name="data" xsi:type="array">
23+
<item name="js_config" xsi:type="array">
24+
<item name="provider" xsi:type="string">
25+
pagebuilder_banner_collage_left_form.pagebuilder_banner_collage_left_form_data_source
26+
</item>
27+
</item>
28+
<item name="label" xsi:type="string" translate="true">Banner</item>
29+
</argument>
30+
<settings>
31+
<deps>
32+
<dep>pagebuilder_banner_collage_left_form.pagebuilder_banner_collage_left_form_data_source</dep>
33+
</deps>
34+
<namespace>pagebuilder_banner_collage_left_form</namespace>
35+
</settings>
36+
<dataSource name="pagebuilder_banner_collage_left_form_data_source">
37+
<argument name="data" xsi:type="array">
38+
<item name="js_config" xsi:type="array">
39+
<item name="component" xsi:type="string">Magento_PageBuilder/js/form/provider</item>
40+
</item>
41+
</argument>
42+
<dataProvider name="pagebuilder_banner_collage_left_form_data_source" class="Magento\PageBuilder\Model\ContentType\DataProvider">
43+
<settings>
44+
<requestFieldName/>
45+
<primaryFieldName/>
46+
</settings>
47+
</dataProvider>
48+
</dataSource>
49+
50+
<!--Add Fieldsets and fields-->
51+
52+
</form>
53+
```
54+
55+
### `collage-right` form
56+
57+
```xml
58+
<?xml version="1.0" encoding="UTF-8"?>
59+
<form xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
60+
xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Ui:etc/ui_configuration.xsd"
61+
extends="pagebuilder_banner_form">
62+
<argument name="data" xsi:type="array">
63+
<item name="js_config" xsi:type="array">
64+
<item name="provider" xsi:type="string">
65+
pagebuilder_banner_collage_right_form.pagebuilder_banner_collage_right_form_data_source
66+
</item>
67+
</item>
68+
<item name="label" xsi:type="string" translate="true">Banner</item>
69+
</argument>
70+
<settings>
71+
<deps>
72+
<dep>pagebuilder_banner_collage_right_form.pagebuilder_banner_collage_right_form_data_source</dep>
73+
</deps>
74+
<namespace>pagebuilder_banner_collage_right_form</namespace>
75+
</settings>
76+
<dataSource name="pagebuilder_banner_collage_right_form_data_source">
77+
<argument name="data" xsi:type="array">
78+
<item name="js_config" xsi:type="array">
79+
<item name="component" xsi:type="string">Magento_PageBuilder/js/form/provider</item>
80+
</item>
81+
</argument>
82+
<dataProvider name="pagebuilder_banner_collage_right_form_data_source"
83+
class="Magento\PageBuilder\Model\ContentType\DataProvider">
84+
<settings>
85+
<requestFieldName/>
86+
<primaryFieldName/>
87+
</settings>
88+
</dataProvider>
89+
</dataSource>
90+
91+
<!--Add Fieldsets and fields-->
92+
93+
</form>
94+
```
95+
96+
## Add fieldsets and fields
97+
98+
Before you add a field to the form of an existing content type, you need to know where to add it. In other words, you need to decide which fieldset to put your field in. We want to put our new max-height field with the Banner's existing min-height field, which is the `appearance_fieldset`.
99+
100+
The markup for adding the field to the fieldset looks exactly like this for both forms:
101+
102+
```xml
103+
<fieldset name="appearance_fieldset"
104+
sortOrder="10"
105+
component="Magento_PageBuilder/js/form/element/dependent-fieldset">
106+
<field name="max_height" sortOrder="30" formElement="input">
107+
<argument name="data" xsi:type="array">
108+
<item name="config" xsi:type="array">
109+
<item name="default" xsi:type="number">300</item>
110+
</item>
111+
</argument>
112+
<settings>
113+
<label translate="true">Maximum Height</label>
114+
<additionalClasses>
115+
<class name="admin__field-small">true</class>
116+
</additionalClasses>
117+
<addAfter translate="true">px</addAfter>
118+
<dataType>text</dataType>
119+
<dataScope>max_height</dataScope>
120+
<validation>
121+
<rule name="validate-number" xsi:type="boolean">true</rule>
122+
</validation>
123+
</settings>
124+
</field>
125+
</fieldset>
126+
```
127+
128+
Some of the key elements are described here.
129+
130+
| Elements | Description |
131+
| ---------- | ------------------------------------------------------------ |
132+
| `fieldset` | The fieldset `name` should match the name of the fieldset from the Banner's form. The `appearance_fieldset` is common to all the content type forms and, by default, appears at the top of the forms using the `sortOrder` of 10. |
133+
| `field` | The field `name` should match the CSS max-height style property, but in snake_case. Fields also have a `sortOrder` you can use to place your field above or below existing fields. The `formElement` for a field describes the HTML form type, such as input, checkbox, select, and more. |
134+
| `argument` | Provides the way to add a `default` value to your field. Our default value is set to `300`. |
135+
| `settings` | Provides the markup that gives your field a label, CSS styling, validation, and other properties as needed. |
136+
137+
{:style="table-layout:auto"}
138+
139+
After adding max-height field as previously shown, flush your cache, drag a banner to the Admin stage, open the editor, and see your new style property field being rendered in the Banner's form, as shown here:
140+
141+
![Appearance fieldset](../images/appearance-fieldset.png){:width="934px" height="auto"}
142+
143+
## Conclusion
144+
145+
That's it! You should now be familiar with the basics of extending and existing content type. There is much more to learn, but hopefully this gives you a better understanding of how the existing Page Builder content types can be customized to fit your end-user's needs.

‎docs/images/appearance-fieldset.png

97.2 KB
Loading

‎docs/images/extension-forms-files.png

72.4 KB
Loading

0 commit comments

Comments
 (0)