Skip to content

Commit de22d05

Browse files
bdenhambdenham
committed
MC-6271: Add docs for content type forms
Fixed more merge issues
1 parent f34d944 commit de22d05

File tree

3 files changed

+193
-176
lines changed

3 files changed

+193
-176
lines changed

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -181,3 +181,4 @@ As mentioned previously, our Quote content type has no need for a master compone
181181
## Next
182182
183183
[Step 4: Add form](step-4-add-form.md)
184+

‎docs/create-basic-content-type/step-4-add-form.md

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

66
***
77

8-
In this step, we will create a UI component form to give our Quote example an editor we can use to edit content and style its appearance in various ways.
8+
In this step, we will create a UI component form so that we can give end-users an editor for entering content for the Quote and for styling its appearance when it is displayed in the Admin and on the storefront.
99

1010
## About forms
1111

@@ -19,15 +19,13 @@ Inheriting from either base form gives you an editor for your content type that
1919

2020
### `pagebuilder_base_form`
2121

22-
The `pagebuilder_base_form` gives you the following form fields in the editor, along with the Close, Reset, and Save buttons as shown here:
22+
The `pagebuilder_base_form` gives you the following form fields in a fieldset named Advance, along with the Close, Reset, and Save buttons as shown here:
2323

2424
![Create config file](../images/pagebuilder_base_form.png)
2525

26-
27-
2826
### `pagebuilder_base_form_with_background_attributes`
2927

30-
In addition the the "Advanced" form fields from `pagebuilder_base_form`, the `pagebuilder_base_form_with_background_attributes` gives you the following "Background" form fields as shown here:
28+
In addition to all the fields from `pagebuilder_base_form`, the `pagebuilder_base_form_with_background_attributes` gives you the following "Background" form fields as shown here:
3129

3230
![Create config file](../images/pagebuilder_base_form_with_background_attributes.png)
3331

@@ -49,6 +47,165 @@ The form and layout files should be added to your module in the following locati
4947

5048
Make sure you add these files as shown before continuing.
5149

50+
## Quote form
51+
52+
The Quote form inherits from `pagebuilder_base_form_with_background_attributes` to provide all the form fields available for customizing our content type. In addition to the fields we get from inheritance, we want to add specific entry and styling fields for our Quote, as shown here:
53+
54+
![Create config file](../images/custom-form-fields.png)
55+
56+
The Quote form is shown in full here for you to copy into your `pagebuilder_example_form.xml` file, followed by descriptions of the key parts.
57+
58+
```xml
59+
<?xml version="1.0" encoding="UTF-8"?>
60+
<form xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Ui:etc/ui_configuration.xsd" extends="pagebuilder_base_form_with_background_attributes">
61+
<argument name="data" xsi:type="array">
62+
<item name="js_config" xsi:type="array">
63+
<item name="provider" xsi:type="string">pagebuilder_example_quote_form.pagebuilder_example_quote_form_data_source</item>
64+
</item>
65+
<item name="label" xsi:type="string" translate="true">Quote</item>
66+
</argument>
67+
<settings>
68+
<namespace>pagebuilder_example_quote_form</namespace>
69+
<deps>
70+
<dep>pagebuilder_example_quote_form.pagebuilder_example_quote_form_data_source</dep>
71+
</deps>
72+
</settings>
73+
<dataSource name="pagebuilder_example_quote_form_data_source">
74+
<argument name="data" xsi:type="array">
75+
<item name="js_config" xsi:type="array">
76+
<item name="component" xsi:type="string">Magento_PageBuilder/js/form/provider</item>
77+
</item>
78+
</argument>
79+
<dataProvider name="pagebuilder_example_quote_form_data_source" class="Magento\PageBuilder\Model\ContentType\DataProvider">
80+
<settings>
81+
<requestFieldName/>
82+
<primaryFieldName/>
83+
</settings>
84+
</dataProvider>
85+
</dataSource>
86+
<fieldset name="general" sortOrder="20">
87+
<settings>
88+
<label/>
89+
</settings>
90+
<field name="quote_text" sortOrder="10" formElement="textarea">
91+
<argument name="data" xsi:type="array">
92+
<item name="config" xsi:type="array">
93+
<item name="source" xsi:type="string">page</item>
94+
</item>
95+
</argument>
96+
<settings>
97+
<dataScope>quote_text</dataScope>
98+
<dataType>text</dataType>
99+
<label translate="true">Quote</label>
100+
</settings>
101+
</field>
102+
<field name="quote_author" sortOrder="20" formElement="input">
103+
<argument name="data" xsi:type="array">
104+
<item name="config" xsi:type="array">
105+
<item name="source" xsi:type="string">page</item>
106+
</item>
107+
</argument>
108+
<settings>
109+
<dataScope>quote_author</dataScope>
110+
<dataType>text</dataType>
111+
<label translate="false">Author</label>
112+
</settings>
113+
</field>
114+
<field name="quote_author_desc" sortOrder="30" formElement="input">
115+
<argument name="data" xsi:type="array">
116+
<item name="config" xsi:type="array">
117+
<item name="source" xsi:type="string">page</item>
118+
</item>
119+
</argument>
120+
<settings>
121+
<dataScope>quote_author_desc</dataScope>
122+
<dataType>text</dataType>
123+
<label translate="false">Author Description</label>
124+
</settings>
125+
</field>
126+
<field name="quote_css" sortOrder="40" formElement="input">
127+
<argument name="data" xsi:type="array">
128+
<item name="config" xsi:type="array">
129+
<item name="source" xsi:type="string">page</item>
130+
</item>
131+
</argument>
132+
<settings>
133+
<dataScope>quote_css</dataScope>
134+
<dataType>text</dataType>
135+
<label translate="true">CSS for Quote</label>
136+
</settings>
137+
</field>
138+
</fieldset>
139+
</form>
140+
```
141+
142+
### fieldset
143+
144+
The `<fieldset>` element is required and provides a basic grouping mechanism (with an optional label) for the fields in your form. You can define as many fieldsets as you want.
145+
146+
| Attribute | Description |
147+
| ----------- | ------------------------------------------------------------ |
148+
| `name` | You can name your fieldset whatever you want. Currently, it has no significance for data binding. |
149+
| `sortOrder` | Determines where the fieldset is placed in the editor. The `sortOrder` for the `pagebuilder_base_form` fieldset is set to `90`. Setting your fieldset to a value less than that (such as `20`) will put your fieldset above the inherited fieldsets. A value greater than `90` will put your fieldset below the inherited fieldsets. |
150+
151+
### field
152+
153+
The `<field>` element creates the actual HTML form element as specified by the `formElement` attribute, such as input, select, textarea, and colorPicker.
154+
155+
| Attribute | Description |
156+
| ------------- | ------------------------------------------------------------ |
157+
| `name` | The name of the field used for data bindings. |
158+
| `sortOrder` | Determines where the field is placed within the fieldset in relation to other fields. |
159+
| `formElement` | Determines the HTML form element to render for the field. |
160+
161+
### argument data source
162+
163+
Defines the data source for the field.
164+
165+
[Need more info. What does it mean for the `page` to be specified as the data source?]
166+
167+
```xml
168+
<argument name="data" xsi:type="array">
169+
<item name="config" xsi:type="array">
170+
<item name="source" xsi:type="string">page</item>
171+
</item>
172+
</argument>
173+
```
174+
175+
### settings
176+
177+
The `<settings>` element defines the data scope, data type, and label to use for the field, as shown here:
178+
179+
```xml
180+
<settings>
181+
<dataScope>quote_text</dataScope>
182+
<dataType>text</dataType>
183+
<label translate="true">Quote</label>
184+
</settings>
185+
```
186+
187+
The `dataType` values are typically `text` and `boolean`.
188+
189+
[What is the dataScope? What's its significance? How is it used?]
190+
191+
## Quote form layout
192+
193+
The layout for our Quote form is shown in full here for you to copy into your `pagebuilder_example_form.xml` layout file. For more information about layouts, see [Layout instructions](https://devdocs.magento.com/guides/v2.3/frontend-dev-guide/layouts/xml-instructions.html).
194+
195+
```xml
196+
<?xml version="1.0"?>
197+
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" layout="admin-1column" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
198+
<update handle="styles"/>
199+
<body>
200+
<referenceContainer name="content">
201+
<uiComponent name="pagebuilder_example_quote_form"/>
202+
</referenceContainer>
203+
</body>
204+
</page>
205+
```
206+
207+
208+
52209
## Form configuration
53210

54211
In your configuration file, reference your UI component form as shown here within the `<type>` element:
@@ -113,6 +270,8 @@ The `<element>` element provides a scope for the data bindings within it.
113270
| --------- | ------------------------------------------------------------ |
114271
| `name` | Specifies the name of the element scope for the data binding when applied to template elements. In our example, the element name of `main` is used as the scope for binding styles and other attributes to the top-level `<div>` element in our template: `<div attr="data.main.attributes" ko-style="data.main.style">` |
115272

273+
![Create config file](../images/step4-add-form.png)
274+
116275
#### style
117276

118277
The `<style>` element configures the bindings from the form style fields to the template elements.
@@ -222,162 +381,6 @@ And the application of the binding in the `master.html` template is shown here:
222381
<blockquote css="data.quote.css" html="data.quote.html"></blockquote>
223382
```
224383

225-
## Quote form
226-
227-
The Quote form inherits from `pagebuilder_base_form_with_background_attributes` to provide all the form fields available for customizing our content type. In addition to the fields we get from inheritance, we want to add specific entry and styling fields for our Quote, as shown here:
228-
229-
![Create config file](../images/custom-form-fields.png)
230-
231-
The Quote form is shown in full here for you to copy into your `pagebuilder_example_form.xml` file, followed by descriptions of the key parts.
232-
233-
```xml
234-
<?xml version="1.0" encoding="UTF-8"?>
235-
<form xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Ui:etc/ui_configuration.xsd" extends="pagebuilder_base_form_with_background_attributes">
236-
<argument name="data" xsi:type="array">
237-
<item name="js_config" xsi:type="array">
238-
<item name="provider" xsi:type="string">pagebuilder_example_quote_form.pagebuilder_example_quote_form_data_source</item>
239-
</item>
240-
<item name="label" xsi:type="string" translate="true">Quote</item>
241-
</argument>
242-
<settings>
243-
<namespace>pagebuilder_example_quote_form</namespace>
244-
<deps>
245-
<dep>pagebuilder_example_quote_form.pagebuilder_example_quote_form_data_source</dep>
246-
</deps>
247-
</settings>
248-
<dataSource name="pagebuilder_example_quote_form_data_source">
249-
<argument name="data" xsi:type="array">
250-
<item name="js_config" xsi:type="array">
251-
<item name="component" xsi:type="string">Magento_PageBuilder/js/form/provider</item>
252-
</item>
253-
</argument>
254-
<dataProvider name="pagebuilder_example_quote_form_data_source" class="Magento\PageBuilder\Model\ContentType\DataProvider">
255-
<settings>
256-
<requestFieldName/>
257-
<primaryFieldName/>
258-
</settings>
259-
</dataProvider>
260-
</dataSource>
261-
<fieldset name="general" sortOrder="20">
262-
<settings>
263-
<label/>
264-
</settings>
265-
<field name="quote_text" sortOrder="10" formElement="textarea">
266-
<argument name="data" xsi:type="array">
267-
<item name="config" xsi:type="array">
268-
<item name="source" xsi:type="string">page</item>
269-
</item>
270-
</argument>
271-
<settings>
272-
<dataScope>quote_text</dataScope>
273-
<dataType>text</dataType>
274-
<label translate="true">Quote</label>
275-
</settings>
276-
</field>
277-
<field name="quote_author" sortOrder="20" formElement="input">
278-
<argument name="data" xsi:type="array">
279-
<item name="config" xsi:type="array">
280-
<item name="source" xsi:type="string">page</item>
281-
</item>
282-
</argument>
283-
<settings>
284-
<dataScope>quote_author</dataScope>
285-
<dataType>text</dataType>
286-
<label translate="false">Author</label>
287-
</settings>
288-
</field>
289-
<field name="quote_author_desc" sortOrder="30" formElement="input">
290-
<argument name="data" xsi:type="array">
291-
<item name="config" xsi:type="array">
292-
<item name="source" xsi:type="string">page</item>
293-
</item>
294-
</argument>
295-
<settings>
296-
<dataScope>quote_author_desc</dataScope>
297-
<dataType>text</dataType>
298-
<label translate="false">Author Description</label>
299-
</settings>
300-
</field>
301-
<field name="quote_css" sortOrder="40" formElement="input">
302-
<argument name="data" xsi:type="array">
303-
<item name="config" xsi:type="array">
304-
<item name="source" xsi:type="string">page</item>
305-
</item>
306-
</argument>
307-
<settings>
308-
<dataScope>quote_css</dataScope>
309-
<dataType>text</dataType>
310-
<label translate="true">CSS for Quote</label>
311-
</settings>
312-
</field>
313-
</fieldset>
314-
</form>
315-
```
316-
317-
### fieldset
318-
319-
The `<fieldset>` element is required and provides a basic grouping mechanism (with an optional label) for the fields in your form. You can define as many fieldsets as you want.
320-
321-
| Attribute | Description |
322-
| ----------- | ------------------------------------------------------------ |
323-
| `name` | _What significance or conventions apply to the fieldset name?_ |
324-
| `sortOrder` | Determines where the fieldset is placed in the editor. The `sortOrder` for the `pagebuilder_base_form` fieldset is set to `90`. Setting your fieldset to a value less than that (such as `20`) will put your fieldset above the inherited fieldsets. A value greater than `90` will put your fieldset below the inherited fieldsets. |
325-
326-
### field
327-
328-
The `<field>` element creates the actual HTML form element as specified by the `formElement` attribute, such as input, select, textarea, and colorPicker.
329-
330-
| Attribute | Description |
331-
| ------------- | ------------------------------------------------------------ |
332-
| `name` | The name of the field used for bindings. |
333-
| `sortOrder` | Determines where the field is placed within the fieldset in relation to other fields. |
334-
| `formElement` | Determines the HTML form element to render for the field. |
335-
336-
### argument data source
337-
338-
Defines the data source for the field.
339-
340-
[Need more info. What does it mean for the `page` to be specified as the data source?]
341-
342-
```xml
343-
<argument name="data" xsi:type="array">
344-
<item name="config" xsi:type="array">
345-
<item name="source" xsi:type="string">page</item>
346-
</item>
347-
</argument>
348-
```
349-
350-
### settings
351-
352-
The `<settings>` element defines the data scope, data type, and label to use for the field, as shown here:
353-
354-
```xml
355-
<settings>
356-
<dataScope>quote_text</dataScope>
357-
<dataType>text</dataType>
358-
<label translate="true">Quote</label>
359-
</settings>
360-
```
361-
The `dataType` values are typically `text` and `boolean`.
362-
363-
[What is the dataScope? What's its significance? How is it used?]
364-
365-
## Quote form layout
366-
367-
The layout for our Quote form is shown in full here for you to copy into your `pagebuilder_example_form.xml` layout file. For more information about layouts, see [Layout instructions](https://devdocs.magento.com/guides/v2.3/frontend-dev-guide/layouts/xml-instructions.html).
368-
369-
```xml
370-
<?xml version="1.0"?>
371-
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" layout="admin-1column" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
372-
<update handle="styles"/>
373-
<body>
374-
<referenceContainer name="content">
375-
<uiComponent name="pagebuilder_example_quote_form"/>
376-
</referenceContainer>
377-
</body>
378-
</page>
379-
```
380-
381384
## Next
382385

383386
[Step 5: Add styles](step-5-add-styles.md)

0 commit comments

Comments
 (0)