Salesforce Commerce Cloud Digital provides tools to simplify form display and processing. Use the Digital Forms framework to control how consumer-entered values are validated by the application, rendered in a browser, and possibly stored on a server.
To use the DigitalForms framework, you need the following files:
There are a few objects that interact with each other when working with Digital forms:
Identify the fields that a user will need to enter, and what actions can be taken when implementing a form.
This information typically comes from a wireframe or a functional specification. Once the form fields are determined, create them in an XML form that will set the form field parameters and hold the data for the form.
This table shows all elements that can be used in your XML form file e.g signupform.xml
Element | Description |
---|---|
form | Required: top-level tag that contains all other elements inside <form>...</form> |
field | Required: Defines data field with many attributes (see table below) |
options | Use as a child element inside a field to pre-fill multiple options like months, days, etc. |
Option | Use as a child element inside an options element to specify a single option |
action | Defines a possible action the user might take on the form |
include | Allows inclusion of one form metadata definition into another |
list | Allows inclusion of several items (i.e. the collection of addresses) as a single field |
group | Allows grouping of elements to be invalidated together |
The field element may use the following attributes:
Attributes | Description |
---|---|
formid | Required: unique ID to identify the field for ISML templates and controllers. |
type | Required: data type for field (see table below to check accepted values). |
range-error | (*) Message shown if value provided does not fall within the specified range. |
parse-error | (*) Message shown when the data entered does not match the regex. Usually a key to an externalized string. |
value-error | (*) Shown if an element is invalidated in a pipeline. |
missing-error | (*) Message shown if the primary key validation error is generated in a pipeline./td> |
label | Usually a key to an externalized string in the forms.properties resource bundle. |
regexp | Regular expression for string fields: email, phone, zip code, etc |
description | Description for field, might be used in tooltips. |
mandatory | The field is required via server-side validation when true. |
min, max | The valid range for integer, number, and dates. |
min-length, max-length | Restricts the field length for data entry. |
binding | Used to match field to a persistent object attribute. |
masked | Specify # of characters to mask. |
format | The format for display of dates, numbers, etc. |
whitespace | Specify whitespace handling (none or remove). |
timezoned | Optional flag for date objects (true or false). |
default-value | Pre-defines a value for a field. |
checked-value | Value when the field is checked in a form. |
unchecked- value | Value when field is unchecked in form. |
There are 4 types of error: range-error, parse-error, missing-error, value-error. And 2 required attributes: formid and type. For definition read the cell that contained the sign (*).
Data type to be used for the "type" attribute on <field> element can be as follows:
Data type | Description |
---|---|
string | Use for text data. |
integer | Use for numeric data like days, months. |
number | Use for quantity fields. |
boolean | Use with multiple-choice fields. |
date | Use this when timezoned or format are needed for dates. |
Below you can see part of the metadata definition of the address form:
In this example, the fields firstname, lastname and others store some of the information needed in the user profile. You will notice that some fields are mandatory because of the attribute mandatory="true".
Also, all of them contain label keys that point to the cartridge/templates/resources/forms.properties file (by default, labels used on forms are defined inside this file)
Finally, the postalCode field has an extra requirement. It uses a regular expression (regexp) to define what an acceptable postalCode can be and it specifies a parse-error key that matches an error message in the forms.properties file.
The action tag, when present, identifies the possible actions that a user may take on the form and the attribute valid-form="true" in this tag means that this form requires validation: the mandatory fields will be enforced on the server-side.
Define an ISML template with the same tags needed for a valid HTML form:
<form>
...
</form>
You can implement your own form action by specifying a controller URL, but that would circumvent the Forms framework.
<form action="${URLUtils.url('<Controller>-<Function>')}" method="post">
...
</form>
There is usually a controller behind the scenes which is responsible for rendering the template file and also sending the form object to it.
Below you can see part of the Address Controller file:
As you can see, the controller, does the following:
By default, all labels, messages and titles that you will use in your forms should be added inside the <cartridge>\cartridge\templates\resources\forms.properties
The callback function for this event its executed before middleware completion. Official Salesforce Commerce Cloud docs says "The route:BeforeComplete event is used to store form data. Different APIs are used to save data, depending on the type of form."
In practice, this is not mandatory but at least you know it is a possibility if you have a specific situation where you have to save form data, you expect the endpoint to be extended and you must make sure that your logic to save the form data will be the last part to be executed.