sfcc-forms-development

name	sfcc-forms-development
description	Guide for building, validating, securing, and persisting SFCC storefront forms (SFRA + SiteGenesis patterns). Use this when creating or troubleshooting form XML, controller handling, CSRF, and validation.

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