Forms

Create HTML forms in B2C Commerce using templates and controllers. Using form definitions, persist form data during a session and store it in system objects or custom objects.

Create a standard HTML form that uses AJAX for validation and error rendering. If you’re creating a simple form that doesn’t store data, is easily localized, and only requires client-side validation, this type of form is appropriate. Create a complex form that stores data, requires server-side validation, and has sophisticated localization requirements. Sophisticated localization can include adding, removing, or rearranging fields in the form or changing the data object you have to store with form data.

If you’re creating a complex form, use a B2C Commerce form definition. A form definition results in an in-memory object that persists during the session. Use this object with various platform features for localization, server-side validation, and data storage.

The following example uses a form definition. The form has a text field to input a nickname, a submit button, and a cancel button. After the form is submitted, another page is rendered that shows the nickname entered in the previous form.

The first thing you create for a form is the form definition. The form definition describes the data you need from the form, the data validation, and the system objects you want to store the data in. This example only has one input field and two buttons. This form doesn’t validate or store data permanently.

SFRAFormDef.xml

The form definition determines the structure of the in-memory form object. The in-memory form object persists data during the session, unless you explicitly clear the data.

In the Storefront Reference Architecture (SFRA), the first step to create a form is to create a JSON object to contain the form data. The server.getForm function uses the form definition to create this object. Data from the form is accessible in templates using the pdict variable. However, the form is available only if the server.getForm object is passed to the template by the controller.

The controller in this example exposes a Start function that renders an empty form.

The Start function sets the actionURL that’s used to handle the submit action for the form and creates a JSON object based on the form definition.

In this example, SFRAFormTemplate.isml is the empty form rendered for the user and the SFRAResultTemplate.isml shows data entered into the form.

The form action uses the actionUrl property passed to it by the controller.

The client-side JavaScript and css files are included using the assets.js module.

After a form is submitted, data from the form is available as part of the req.form property. In the following example, the nickname entered in the original form is passed to a new template for rendering.

This template prints the form field label and data stored from the form.

Most SFRA forms are standard HTML forms, so use input type="hidden" to hide form fields in templates.

The form you create in your template can contain fields from multiple form definitions. The same fields can be reused in other forms as many times as required. This ability can be useful for prepopulating form data that the customer has already entered. For example, address or payment preference data.

Use the metadata entered for a custom or system object in Business Manager to determine form definition information. This manages data attributes in one place without having to change code. For example, if you wanted to let merchants change the labels on form fields, you could include label as a metadata attribute and reference it.

SFRA doesn’t include dynamic forms.

However, if you want to create them, use the isdynamicform tag to generate dynamic forms. The dynamicform.isml template and the dynamicForm.js script control how code is generated using the isdynamicform tag.

SFRA doesn’t include multi-part, embedded, or nested forms. We don’t recommend them as a best practice.

Change the structure of a form depending on the locale. For example, include different address fields, such as state or province, depending on the country. To localize the form structure, create different form definitions for each locale. These form definitions have the same name, but a different structure or different fields for different locales.

In your cartridge, create a forms/default folder for the standard locale and then separate folders that are named for each locale of the form. Store a different form definition in each locale folder. If a locale doesn’t have a separate folder, the default form definition is used.

Use resource strings directly from a form. The following example is of the loginform.isml that logs customers into the site. In this case, the form uses the label.input.login.email resource string identifier.

Depending on the locale, this resource identifier resolves to different values

In the English app_storefront_base/cartridge/templates/resources/login.properties file:

In the French app_storefront_base/cartridge/templates/resources/login_fr_FR.properties file:

All form strings can be replaced with resource strings. Resource strings for forms are located by default in the forms.properties file for your cartridge and referenced from the form definition file. Add files with the name forms_locale_.properties to add localized strings. For example, add a forms_it_IT.properties file for an Italian version of the same properties. Different fields for the form may be needed, depending on the locale. Make sure that the strings for those fields are included in the localized version of the properties files.

The following form definition file defines a form to enter contact information. This example doesn’t show the entire form definition, just some of the fields that use localized strings for labels and error messages. Find this file as the contactus.xml form in the SiteGenesis app_storefront_core cartridge.

The label and error strings in bold reference the properties set in the forms.properties file, which contains entries like the following for the default site locale:

The form is localized in the forms_it_IT.properties file (along with the other locale-specific forms_locale_.properties files) with entries like the following:

Server-side validation on form data is configured in the form definition. SFRA uses jQuery AJAX methods to render a page after server-side validation.

The attributes set on the form field are used for validation. In the following example, the mandatory attribute requires a value for the field. The regexp attribute determines the content of the field. And the max-length attribute sets the maximum length of the data for the field.

Errors shown for attribute validation:

• Default error for form invalidation: value-error

• Mandatory flag invalid: missing-error

• Entered value invalid: parse-error

Use the validation attribute to specify a function to run to validate form data. Run these validations on container elements, such as form or group, or on individual fields.

Selectively invalidate form elements using the InvalidateFormElement pipelet in pipelines or the invalidateFormElement function in the FormModel or any model that requires it. If any element in a form is invalid, the entire form is invalid. However, in your form definition, create error messages that are specific to a field. See the example of range-error, which points to a resource string with a message for the customer on why the field is invalid.

Simple forms are standard HTML forms, so use any client-side validation method you choose. B2C Commerce uses default HTML5 validation for client-side validation. Find the client-side JavaScript for a page by identifying the script added by the assets.AddJs function.

B2C Commerce provides two utility scripts for validating form data:

• form-validation: This script validates a specific field in the form. It uses the validation criteria set in the form definition and included in the attributes for the form JSON object. This script is required by the client-side JavaScript doing the validation for a specific form and is loaded at document.ready. This file is located in app_storefront_base/cartridge/client/js/default/components/form-validation.js.
• client-side-validation: This script validates the entire form and clears a form for validation. This file is required by main.js. It’s located in app_storefront_base/cartridge/client/js/default/components/client-side-validation.js

The route:BeforeComplete event is used to store form data. Different APIs are used to save data, depending on the type of form.

This example constructs an object that contains the relevant information from the form and saves it to the ViewData object, so it can be passed. This example can be seen in the Account.js SavePassword function.

In SFRA, you use the server.getForms function to get the form data structure from the relevant form definition and convert it into a JSON object. The object is then added to the data passed to the template, so that it’s available to the template via the pdict variable. To clear the form, you must manually call the clear method.

This example gets the profile form and clears it.

Prepopulate forms with information from system objects, custom objects, and form data.

Use the server module form.jscopyObjectToForm` method to get data from an existing form object. Use the metadata attributes for a system or custom object to prefill form data.

Use the FormModel.js copyFrom function to get data from an existing form object. Usually, if you have used app.getForm to get a copy of a form model, it makes more sense to use the function. Transfer form data from one form to another directly. In the following example, if a customer decides to use the shipping address for billing, the values from one form are copied to the other.

To copy values from one custom object to another, don’t use the dw.web.FormGroup copyFrom() and copyTo() methods. The copyTo() method requires a form submit to set values in the custom object. Instead, use Javascript to directly copy the values, as in this example:

Prepopulate forms with information from system objects, custom objects, and in-memory form data. This data is available directly from the model you’re working with or from the ViewData object used for rendering the template. The server module in the modules folder includes a forms.js module that converts form data into JSON objects. For more information, see the following functions in the server-side JSDoc.

• parseForm(Form)
• copyObjectToForm(object, CurrentForm)
• findValue(formGroup, name)
• clearOptions(obj)

SFRA provides a forms module that abstracts the form definition into a JSON representation. If you want to work with JSON objects, use the modules and forms methods to get and store data.

Use the new CSRF (Cross-Site Request Forgery) framework to add fields that are protected from request forgery.

CSRF in SFRA is provided as middleware by B2C Commerce. CSRF checks are performed as the middleware step csrfProtection.validateAjaxRequest.

Example: CSRF check is made for login information. This example is available in the Account.js controller.

For more information, see validateRequest and validateAjaxRequest in the JSDoc.