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:

  1. Missing-error
  2. Parse-error
  3. Range-error
  4. 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
}