Field Form Element
The <field> element lets you define form fields and how they are validated. It's represented by the dw.web.FormField API class.
| Attribute | Description |
|---|---|
| formid | The identifier of the field. |
| type | The value type of the field. Supported types are: string, integer, number, boolean and date. There are optional attributes if the type is date (for example, timezoned is a Boolean). |
| label | An optional descriptive label for the field. This field can be a key. |
| mandatory | Flag, whether the field is mandatory. ("true" or "false") The default is "false". |
| min-length | For string fields, the minimum allowed length. |
| max-length | For string fields, the maximum allowed length. |
| masked | The number of characters that are unmasked (left to right). For example, when masking social security numbers (USA) five characters are usually masked, with the last (right-most) four visible. |
| description | Optional descriptive text for the user interface, such as "The password must have a minimum of 6 characters." (key or string). |
| missing-error | Optional error text for the user interface if the required value is missing. For example, "The SSN must contain 9 characters." This field can be a key. This attribute can't be used with the validation attribute. |
| parse-error | Optional error text for the user interface when the entered value is in an incorrect format. This field can be a key. This attribute can't be used with the validation attribute. |
| range-error | Optional error text for the user interface when the entered information is out of range. (min-length, max-length, min or max). This field can be a key. This attribute can be used with the validation attribute. |
| validation | Salesforce B2C Commerce script expression that resolves to a custom validation function provided by a B2C Commerce Script Module. The referenced function must return a boolean value: true indicates the field is valid; false, invalid. The range-error attribute, when used with the validation attribute, doesn't necessarily specify an out-of-range error. Instead, the range-error attribute specifies a generic error message that is used whenever your validation function returns false, regardless of the reason why it returns false. See Custom Validation Function Example. This attribute was added in version 15.8. |
| value-error | Optional error text for the user interface when the entered value is unacceptable. This field can be a key. This attribute can't be used with the validation attribute. |
| format | Formatting information on how to convert the value into a string representation. |
| binding | If a business object is assigned to the field, the property name to read the value out of the business object or to set. Also used by the UpdateForm pipelets. |
| default-value | The field's default value. |
| whitespace | Declares if white space characters should be removed at the beginning and end for string data. Possible values are "none" or "remove". The default is "none". |
| min | For integer, number and date: minimum value. |
| max | For integer, number and date: maximum value. |
| default-value | The default value of the field. |
| options | List of option elements (values and labels). For example, selection of the month. |
Note: A <field> element can contain
<options> element children.
Field error attributes maintain an order of precedence, as follows:
- Missing-error
- Parse-error
- Range-error
- Value-error
Note: Starting in version 15.8, if you use the validation attribute to
specify a custom validation function, this precedence is ignored: only the
range-error message is used.
The following are optional attributes based on the type attribute:
| Type attribute | Attribute | Description |
|---|---|---|
| string | regexp | A regular expression for validation of strings. |
| date | timezoned | The date is set by the system as GMT. Customers typically enter information in the site's time zone. But, birthdays for example, are not in a time zone. Having a date field set to a time means it's "timezoned". Thus, timezoned="true" if the site time zone is used; and timezoned="false", when GMT, the system default, is used. The possible values are: "true" or "false". |
| integer or number | min/max | The minimum and maximum values of the field. If min is greater than max, min value is set equal to max value. |
| value | numeric. | |
| date | value | now or any valid date represented as a string based on the current date format. |
| boolean | checked-value | Lets you map a string value to a boolean field when it's selected. For example, if you are rendering a radio button, but want to use a string value instead of "true". The checked-value indicates what is "true" for this button. |
| unchecked-value | Lets you map a string value to a boolean field when it isn't selected. For example, if you are rendering a radio button, but want to use a string value instead of false. Used to map something other than "true" or "false" to a boolean field. |
See Form Validation.
Example
In this example from the cart form, the quantity field is bound to the quantityValue. It's a number field that is in this format: 0.#.
<field formid="quantity" type="number" binding="quantityValue" format="0.#"/>In this example, the couponCode field is of type string and isn't mandatory.
<field formid="couponCode" type="string" mandatory="false"/>Custom Validation Function Example
Starting in version 15.8, you can validate fields using a custom validation function. The following field definition shows how you can reference a custom validation function when setting the validation attribute:
<field formid="password"
label="label.password"
description="resource.customerpassword"
type="string"
mandatory="true"
range-error="resource.customerpassword"
validation="${require('~/cartridge/scripts/forms/my_custom_script.ds').my_custom_validation(formfield);}"
/>The custom validation function might look something like this:
// my_custom_script.ds
importPackage( dw.web );
exports.my_custom_validation = function( customterPasswordFormField : FormField )
{
// Add your validation logic here
return...; // Must return boolean
}