Forms Skill

This skill guides you through creating forms with validation in Salesforce B2C Commerce using the SFRA patterns.

Overview

B2C Commerce forms consist of three parts:

•Form Definition - XML file defining fields, validation, and actions
•Controller Logic - Server-side form handling and processing
•Template - ISML template rendering the HTML form

File Location

Forms are defined in the cartridge's forms directory:

code

/my-cartridge
    /cartridge
        /forms
            /default              # Default locale
                profile.xml
                contact.xml
            /de_DE               # German-specific (optional)
                address.xml

Form Definition (XML)

Basic Structure

xml

<?xml version="1.0" encoding="UTF-8"?>
<form xmlns="http://www.demandware.com/xml/form/2008-04-19">
    <field formid="email" label="form.email.label" type="string"
           mandatory="true" max-length="50"
           regexp="^[\w.%+-]+@[\w.-]+\.\w{2,6}$"
           parse-error="form.email.invalid"/>

    <field formid="password" label="form.password.label" type="string"
           mandatory="true" min-length="8" max-length="255"
           missing-error="form.password.required"/>

    <field formid="rememberMe" label="form.remember.label" type="boolean"/>

    <action formid="submit" valid-form="true"/>
    <action formid="cancel" valid-form="false"/>
</form>

Field Types

Type	Description	HTML Input
`string`	Text input	`<input type="text">`
`integer`	Whole number	`<input type="number">`
`number`	Decimal number	`<input type="number">`
`boolean`	Checkbox	`<input type="checkbox">`
`date`	Date value	`<input type="date">`

Key Field Attributes

Attribute	Purpose	Example
`formid`	Field identifier (required)	`formid="email"`
`label`	Resource key for label	`label="form.email.label"`
`type`	Data type (required)	`type="string"`
`mandatory`	Required field	`mandatory="true"`
`max-length`	Max string length	`max-length="100"`
`min-length`	Min string length	`min-length="8"`
`regexp`	Validation pattern	`regexp="^\d{5}$"`

Validation Error Messages

Attribute	When Triggered
`missing-error`	Mandatory field is empty
`parse-error`	Value doesn't match regexp or type
`range-error`	Value outside min/max range
`value-error`	General validation failure

See Form XML Reference for complete field attributes, groups, lists, and validation patterns.

Controller Logic (SFRA)

Rendering a Form

javascript

'use strict';

var server = require('server');
var csrfProtection = require('*/cartridge/scripts/middleware/csrf');

server.get('Show',
    csrfProtection.generateToken,
    function (req, res, next) {
        var form = server.forms.getForm('profile');
        form.clear();  // Reset previous values

        res.render('account/profile', {
            profileForm: form
        });
        next();
    }
);

module.exports = server.exports();

Processing Form Submission

javascript

server.post('Submit',
    server.middleware.https,
    csrfProtection.validateAjaxRequest,
    function (req, res, next) {
        var form = server.forms.getForm('profile');

        if (!form.valid) {
            res.json({
                success: false,
                fields: getFormErrors(form)
            });
            return next();
        }

        // Access form values
        var email = form.email.value;
        var firstName = form.firstName.value;

        // Process and save data
        this.on('route:BeforeComplete', function () {
            var Transaction = require('dw/system/Transaction');
            Transaction.wrap(function () {
                customer.profile.email = email;
                customer.profile.firstName = firstName;
            });
        });

        res.json({ success: true });
        next();
    }
);

function getFormErrors(form) {
    var errors = {};
    Object.keys(form).forEach(function (key) {
        if (form[key] && form[key].error) {
            errors[key] = form[key].error;
        }
    });
    return errors;
}

Prepopulating Forms

javascript

server.get('Edit', function (req, res, next) {
    var form = server.forms.getForm('profile');
    form.clear();

    var profile = req.currentCustomer.profile;
    form.firstName.value = profile.firstName;
    form.lastName.value = profile.lastName;
    form.email.value = profile.email;

    res.render('account/editProfile', { profileForm: form });
    next();
});

Template (ISML)

Basic Form Template

html

<form action="${pdict.actionUrl}" method="POST" name="profile-form"
      class="form-horizontal" data-action="${URLUtils.url('Profile-Submit')}">

    <!-- CSRF Token -->
    <input type="hidden" name="${pdict.csrf.tokenName}" value="${pdict.csrf.token}"/>

    <div class="form-group ${pdict.profileForm.email.mandatory ? 'required' : ''}">
        <label for="email" class="form-control-label">
            ${Resource.msg('form.email.label', 'forms', null)}
        </label>
        <input type="email"
               id="email"
               name="email"
               class="form-control ${pdict.profileForm.email.error ? 'is-invalid' : ''}"
               value="${pdict.profileForm.email.value || ''}"
               <isif condition="${pdict.profileForm.email.mandatory}">required</isif>
               maxlength="${pdict.profileForm.email.maxLength || 50}"/>
        <isif condition="${pdict.profileForm.email.error}">
            <div class="invalid-feedback">${pdict.profileForm.email.error}</div>
        </isif>
    </div>

    <button type="submit" class="btn btn-primary">
        ${Resource.msg('button.submit', 'forms', null)}
    </button>
</form>

Localization

Form labels and errors use resource bundles:

forms.properties:

properties

form.email.label=Email Address
form.email.required=Email is required
form.email.invalid=Please enter a valid email address
form.password.label=Password
button.submit=Submit

forms_de_DE.properties:

properties

form.email.label=E-Mail-Adresse
form.email.required=E-Mail ist erforderlich

Best Practices

•Always use CSRF protection for form submissions
•Clear forms before displaying to reset state
•Use resource keys for labels and errors (localization)
•Validate server-side even with client-side validation
•Use route:BeforeComplete for database operations
•Return JSON for AJAX form submissions

Detailed Reference

For comprehensive form patterns:

•Form XML Reference - Complete XML schema, validation patterns, and examples