🔥💣🔥 Salesforce B2C Commerce Developer Certification Exam Practice Test Buy

Handling Forms with Forms Framework

Introduction

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:

XML Metadata File

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

ElementDescription
formRequired: top-level tag that contains all other elements inside <form>...</form>
fieldRequired: Defines data field with many attributes (see table below)
optionsUse as a child element inside a field to pre-fill multiple options like months, days, etc.
OptionUse as a child element inside an options element to specify a single option
actionDefines a possible action the user might take on the form
includeAllows inclusion of one form metadata definition into another
listAllows inclusion of several items (i.e. the collection of addresses) as a single field
groupAllows grouping of elements to be invalidated together

The field element may use the following attributes:

AttributesDescription
formidRequired: unique ID to identify the field for ISML templates and controllers.
typeRequired: 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>
labelUsually a key to an externalized string in the forms.properties resource bundle.
regexpRegular expression for string fields: email, phone, zip code, etc
descriptionDescription for field, might be used in tooltips.
mandatoryThe field is required via server-side validation when true.
min, maxThe valid range for integer, number, and dates.
min-length, max-lengthRestricts the field length for data entry.
bindingUsed to match field to a persistent object attribute.
maskedSpecify # of characters to mask.
formatThe format for display of dates, numbers, etc.
whitespaceSpecify whitespace handling (none or remove).
timezonedOptional flag for date objects (true or false).
default-valuePre-defines a value for a field.
checked-valueValue when the field is checked in a form.
unchecked- valueValue 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 typeDescription
stringUse for text data.
integerUse for numeric data like days, months.
numberUse for quantity fields.
booleanUse with multiple-choice fields.
dateUse this when timezoned or format are needed for dates.

Below you can see part of the metadata definition of the address form:

Address form definition. Salesforce Commerce Cloud

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.

ISML Template

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>
Form address isml example. Salesforce Commerce Cloud

Controller

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:

Edit address controller. Save form data in SFCC

As you can see, the controller, does the following:

  1. Retrieve address ID from parameters that were sent to the function call
  2. Retrieve the customer data (lines 92-96)
  3. Create a model (line 97)
  4. Create data from the form object from the current session using the metadata file definition(line 98)
  5. Clear an existing form object in the pdict using a specified form metadata file. (line 99)
  6. Populate the form object with the data retrieved from the API (line 101)
  7. Renders the template file (line 103)
  8. Sends values / objects to be used in the template (lines 104 and 105)

Resource Bundle

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

How to translate form labels in Commerce Cloud

route:beforeComplete event

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.

route:BeforeComplete event
🔥💣🔥 Salesforce B2C Commerce Developer Certification Exam Practice Test Buy