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/step-4-add-form.md
+58-52Lines changed: 58 additions & 52 deletions
Original file line number
Diff line number
Diff line change
@@ -5,7 +5,7 @@ The development of this tutorial is currently **IN PROGRESS**.
5
5
6
6
***
7
7
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.
8
+
In this step, we will create a UI component form. This form will give users another way to enter text for the quote and style its appearance.
9
9
10
10
## About forms
11
11
@@ -21,38 +21,62 @@ Inheriting from either base form gives you an editor for your content type that
21
21
22
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:
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:
The base form you decide to inherit from depends on the type of content type you create and/or the level of customization you want to give to end-users.
32
+
The base form you inherit from depends on the complexity of the content type you create and the level of customization you want to give to end-users.
33
33
34
34
## Form and layout conventions
35
35
36
36
The conventions for naming your form and its layout are as follows:
37
37
38
-
-Your form should be named `pagebuilder_` + `content_type_name_` + `form.xml`. For example `pagebuilder_example_quote_form.xml`
39
-
- The layout for the form must match the name of your form, in this case: `pagebuilder_example_quote_form.xml`.
38
+
-The name for your form should follow this pattern: `pagebuilder_` + `content_type_name_` + `form.xml`. For example `pagebuilder_example_quote_form.xml`.
39
+
- The name for your layout must match the name of your form, in this case: `pagebuilder_example_quote_form.xml`.
40
40
41
-
The form and layout files should be added to your module in the following locations:
41
+
Add your form and layout files to your module in the following locations:
|`form`| Name of the UI component form that provides the form editor for your content type. |
49
64
50
-
## Quote form
65
+
## The Quote form
51
66
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:
67
+
In our Quote form, we will inherit from `pagebuilder_base_form_with_background_attributes`. This will give end-users all the native Page Builder form fields shown in the two previous screenshots. In addition to those fields, we want to add four specific content entry and styling fields, as shown here:
| Quote | A textarea for writing or pasting in the quote's text. |
76
+
| Author | A text input field for the author's name. |
77
+
| Description | A text input field to describe the author's title or origin of the quote. |
78
+
| CSS for Quote | A text input field for end-users to add css class names for styling the text in the Quote field. |
79
+
56
80
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
81
58
82
```xml
@@ -141,12 +165,12 @@ The Quote form is shown in full here for you to copy into your `pagebuilder_exam
141
165
142
166
### fieldset
143
167
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.
168
+
Page Builder requires fields to be grouped within named `<fieldset>`s. Fieldsets provide your fields with a basic grouping mechanism and an optional label. You can define as many fieldsets as you want.
|`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. |
173
+
|`sortOrder`| Determines where Page Builder puts the fieldset within the editor in relation to other fieldsets. Page Builder sets the `sortOrder` for the `pagebuilder_base_form` fieldset to `90`. Setting your fieldset to a value less than that (such as `20`) will put your fieldset above both inherited fieldsets. A value greater than `90` will put your fieldset below the inherited fieldsets. |
150
174
151
175
### field
152
176
@@ -155,23 +179,24 @@ The `<field>` element creates the actual HTML form element as specified by the `
|`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. |
182
+
|`sortOrder`| Determines where Page Builder puts the field within the fieldset in relation to other fields. |
159
183
|`formElement`| Determines the HTML form element to render for the field. |
160
184
161
-
### argument data source
162
-
163
-
Defines the data source for the field.
185
+
### data source
164
186
165
-
[Need more info. What does it mean for the `page` to be specified as the data source?]
187
+
Defines the data source for the field. The source` node's value corresponds to a key (`page`) in the data array returned by the `\Magento\Framework\View\Element\UiComponent\DataProvider\DataProviderInterface::getData` method of your UI component.
For example, the `quote_text` field above specifies that the `source` of its data should come from tthe data stored under the key `page` returned by the page's DataProvider.
199
+
175
200
### settings
176
201
177
202
The `<settings>` element defines the data scope, data type, and label to use for the field, as shown here:
@@ -184,9 +209,11 @@ The `<settings>` element defines the data scope, data type, and label to use for
184
209
</settings>
185
210
```
186
211
187
-
The `dataType` values are typically `text` and `boolean`.
188
-
189
-
[What is the dataScope? What's its significance? How is it used?]
|`dataScope`| Specifies the name of your input field for data binding. The `dataScope` node allows you to change the value of the `name` attribute for your input field. We do not need to change the field name value, so we keep our dataScope value the same as our field name. |
215
+
|`dataType`| Specifies the data type for the field's data. Common values are `text` and `boolean`. |
216
+
|`label`| Specifies the text label applied to the input field on the form. |
190
217
191
218
## Quote form layout
192
219
@@ -204,30 +231,11 @@ The layout for our Quote form is shown in full here for you to copy into your `p
204
231
</page>
205
232
```
206
233
234
+
## Configuration data mapping
207
235
236
+
As mentioned in [Step 1: Add configuration](step-1-add-configuration.md), the `elements` section of your configuration file, maps the data from your 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.
208
237
209
-
## Form configuration
210
-
211
-
In your configuration file, reference your UI component form as shown here within the `<type>` element:
|`form`|`pagebuilder_example_quote_form` - UI component form that provides the form editor for your content type. |
225
-
226
-
### Configuration elements
227
-
228
-
As mentioned previously in the add configuration step, the `elements` section, within the `appearance` of your configuration file, maps the data and the styles from your 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.
229
-
230
-
The following elements are from the `example_quote.xml` configuration. The elements are shown here in full, followed by descriptions of the key attributes:
238
+
The following elements are from our `example_quote.xml` configuration. These elements are shown here in full for you to copy into your configuration file. Descriptions of the key attributes follow.
231
239
232
240
```xml
233
241
<elements>
@@ -268,9 +276,7 @@ The `<element>` element provides a scope for the data bindings within it.
|`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">`|
|`name`| Specifies the name of the element's scope for data binding when applied to template elements. In our example, we use the element name of `main` 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">`|
274
280
275
281
#### style
276
282
@@ -296,7 +302,7 @@ The `<attribute>` element provides... [Please describe the purpose of this eleme
296
302
297
303
#### css
298
304
299
-
The `<css>` element sets the binding for the CSS Classes form field (`css_classes`) from the `pagebuilder_base_form`, or from any custom input field you add to your form. When the `<css>` element is defined, class names entered into the CSS Classes field are applied to the template elements that use them.
305
+
The `<css>` element sets the binding for the CSS Classes form field (`css_classes`) from the `pagebuilder_base_form`, or from any custom input field you add to your form. When we define the `<css>` element, Page Builder applies the class names from the form's CSS Classes field to the template elements that use the `css` binding element.
0 commit comments