SFCC Forms Development Skill

This skill guides you through implementing and troubleshooting the Salesforce B2C Commerce Forms Framework.

It covers:

• XML form definitions (schema, constraints, localization, reuse)
• Controller patterns (SFRA middleware, request handling, persistence)
• Secure validation (server-side first, CSRF/XSS protections)
• Migration guidance (SiteGenesis ➜ SFRA)

When to Use

Use this skill when you need to:

• Create or modify a form definition in cartridge/forms/**.
• Render forms in ISML using the platform’s generated field metadata.
• Process POST submissions safely (CSRF, server-side validation, transactions).
• Add custom validation beyond XML constraints.
• Migrate legacy SiteGenesis form flows to SFRA.

Quick Checklist (Production-Grade Forms)

[ ] Form routes are POST-only and HTTPS-only
[ ] CSRF token is generated on GET and validated on POST
[ ] Server-side validation gate exists (do not trust client validation)
[ ] All string fields have max-length (DoS & storage safety)
[ ] Regex is conservative (avoid catastrophic backtracking)
[ ] Persistence happens inside Transaction.wrap
[ ] SFRA persistence is isolated in route:BeforeComplete where appropriate
[ ] Explicit mapping for writes (avoid mass assignment)
[ ] Form state cleared when appropriate (pre-render or after success)
[ ] User-provided values are output-encoded in ISML

File Locations

Form XML

Forms are defined per cartridge:

/my-cartridge
  /cartridge
    /forms
      /default
        profile.xml
        contact.xml
      /de_DE
        profile.xml

Form Labels + Error Messages (Localization)

Resource bundles typically live in:

/my-cartridge
  /cartridge
    /templates
      /resources
        forms.properties
        forms_de_DE.properties

Architecture Notes (Know the Moving Parts)

• Form XML is a strict server-side contract: it defines types, constraints, and errors.
• Form instances are stored in session scope (stateful across requests) and must be cleared deliberately.
• Client-side validation is UX; server-side validation is authoritative.

For deeper context and SFRA vs SiteGenesis architectural differences, see:

• references/ARCHITECTURE-SGJC-SFRA.md

Form Definition (XML)

Minimal Example

Keep examples small, but always include:

• strict types
• max-length for strings
• mandatory + missing-error where needed
• parse/range errors for format/constraint enforcement

<?xml version="1.0" encoding="UTF-8"?>
<form xmlns="http://www.demandware.com/xml/form/2008-04-19">
    <field formid="email" type="string"
           label="form.email.label"
           mandatory="true"
           max-length="254"
           regexp="^[^@\s]+@[^@\s]+\.[^@\s]+$"
           missing-error="form.email.required"
           parse-error="form.email.invalid"/>

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

Reuse and Modularity

Prefer include to avoid duplicating complex groups (e.g., an address group reused in checkout, profile, and gift registry).

See the cheat sheet:

• references/FORM-XML-CHEATSHEET.md

Controller Patterns

SFRA: Render Form (GET)

Goals:

• clear stale state when rendering an “empty” form
• generate a CSRF token

'use strict';

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

server.get('Show',
    server.middleware.https,
    csrfProtection.generateToken,
    function (req, res, next) {
        var form = server.forms.getForm('contact');
        form.clear();

        res.render('forms/contact', {
            contactForm: form
        });
        next();
    }
);

module.exports = server.exports();

SFRA: Handle Submission (POST)

Goals:

• validate CSRF first
• gate all business logic on form.valid
• isolate DB writes inside Transaction.wrap
• prefer route:BeforeComplete for persistence to keep transaction boundaries tight

'use strict';

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

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

        if (!form.valid) {
            // SFRA base commonly provides a helper like */cartridge/scripts/formErrors.
            // Prefer using it when available.
            res.json({
                success: false,
                fieldErrors: getFormErrorsSafe(form)
            });
            return next();
        }

        var email = form.email.value;
        var message = form.message && form.message.value;

        this.on('route:BeforeComplete', function () {
            Transaction.wrap(function () {
                // Persist explicitly (no mass assignment)
                // e.g. save a Custom Object, update profile, create a case, etc.
                // Keep only assignments inside the transaction.
            });

            form.clear();
        });

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

function getFormErrorsSafe(form) {
    try {
        var formErrors = require('*/cartridge/scripts/formErrors');
        if (formErrors && typeof formErrors.getFormErrors === 'function') {
            return formErrors.getFormErrors(form);
        }
    } catch (e) {
        // Optional dependency; fall back if not present.
    }
    return {};
}

module.exports = server.exports();

Notes:

• Use csrfProtection.validateAjaxRequest if your route expects AJAX conventions.
• Keep transactions short: no remote API calls, no heavy computation inside Transaction.wrap.

SiteGenesis (SGJC): Key Differences

• Form is typically accessed via app.getForm('id') and rendered via pdict.CurrentForms.
• Templates must use generated htmlName (SiteGenesis uses dwfrm_ prefixes + session-specific IDs).
• CSRF is often handled manually via dw.web.CSRFProtection.

Use this for migration and pitfalls:

• references/ARCHITECTURE-SGJC-SFRA.md

ISML Rendering Rules

Always Use Generated Field Metadata

• Prefer field.htmlName over hardcoded names.
• Use server-provided pdict.csrf.* when using SFRA CSRF middleware.

Typical SFRA token:

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

XSS Safety

When outputting user-provided values, ensure the context is encoded (default output encoding is usually safe, but be deliberate):

<isprint value="${pdict.contactForm.email.value}" encoding="htmlcontent" />

Custom Validation

Use custom validation for business rules that XML cannot express (uniqueness checks, cross-field constraints, etc.).

Patterns:

• Field-level: invalidate a specific field.
• Group-level: invalidate the group for cross-field rules.
• Form-level: invalidate the form for global errors.

Keep custom validation server-side. Client-side validation is optional and must never be the security gate.

Related Skills

• sfcc-security (CSRF, XSS, input validation)
• sfcc-sfra-controllers (middleware patterns, response handling)
• sfcc-isml-development (safe output encoding, template constraints)
• sfcc-localization (resource bundles, locale fallback)

References

• references/FORM-XML-CHEATSHEET.md
• references/ARCHITECTURE-SGJC-SFRA.md