Forms

Intellij SFCC types every form from its XML in cartridge/forms, with no generated files. Fields, groups, lists and actions complete in scripts and templates, open in the XML with Cmd+Click and rename everywhere they are used

MembersGo to the XML

STstorefrontSandbox 01version2

Newsletter.js

1'use strict';

2

3var server = require('server');

4

5server.post('Subscribe', function (req, res, next) {

6 var newsletterForm = server.forms.getForm('newsletter');

7 var email = newsletterForm.contact.

8 res.json({ success: newsletterForm.valid });

9 next();

10});

11

12module.exports = server.exports();

email: SfraFormFieldString Email address requiredapp_custom

firstName: SfraFormFieldString First nameapp_custom

optIn: SfraFormFieldBoolean Send me offersapp_custom

attributesstring

errorstring | null

storefrontapp_customcartridgecontrollersNewsletter.jsGlobal scopeLFUTF-8

Before you start

XSD validation, highlighting and the RegExp injection in the form XML are free, see XML & JSON Validation

Where forms are typed

A form passed to res.render keeps its type in the template's pdict, see ISML scripting

var newsletterForm = server.forms.getForm('newsletter');
var email = newsletterForm.contact.email.value; // string
var optIn = newsletterForm.contact.optIn.value; // boolean

Which copy is used

The types come from one copy of the form, as B2C Commerce picks it

• The first default copy on the site's cartridge path wins the whole file. Copies are never merged
• Without a site scope, every linked cartridge counts, in the linked order. A copy in a cartridge that isn't on the path never wins
• Locale copies such as forms/fr_FR/ don't change the types
• <include> elements are expanded, so an included form's fields complete as members

Name a form's type

Three types name a form in JSDoc and TypeScript

/** @param {SfraFormOf<'newsletter'>} form */
function subscribe(form) {
    return form.contact.email.value;
}

In a .ts file an unannotated require('server') is any, so annotate the form with SfraFormOf

Completion

Each member shows the icon of its kind, the base type such as SfraFormFieldString, its label from the resource bundle and required, with the cartridge of the form on the right

Navigation and documentation

HTML names

dwfrm_ names complete, open the field with Cmd+Click and rename with it wherever they appear

CompletionGo to the fieldCopy HTML Name

STstorefrontSandbox 01version2

newsletter.js

1'use strict';

2

3module.exports = function () {

4 $('form.newsletter').on('submit', function () {

5 var email = $('#dwfrm_newsletter_contact_').val();

6 var optIn = $('[name=""]').is(':checked');

7 $(this).trigger('newsletter:submit', { email: email, optIn: optIn });

8 });

9};

email requiredstring

firstNamestring

optInboolean

Copy

Absolute Path

File Name

Path From Content Root

Reference

Copy HTML Name

storefrontapp_customcartridgeclientdefaultjsnewsletter.jsGlobal scopeLFUTF-8

• Strings in scripts, client scripts in client/ and static/ included, and jQuery selectors such as $('#dwfrm_newsletter_contact_email')
• ISML attributes, such as name="dwfrm_newsletter_contact_email"
• req.form.dwfrm_newsletter_contact_email and request.httpParameterMap.dwfrm_newsletter_contact_email

A name that matches no form isn't marked as an error. The Hard-coded form HTML name inspection, off by default, suggests htmlName instead of a literal

Find Usages and rename

Find Usages (Option+F7, Alt+F7) on a form, a field in the XML or any member read groups the results by kind

Rename (Shift+F6) of a field, group or form updates every usage above. Rename copies in other cartridges and locales, on by default, renames the element in the other copies too. Names in _i0_ list items and names built at run time aren't found

In the form XML

Copies and locales

OverridesLocale copy

STstorefrontSandbox 01version2

newsletter.xml

6 usages

1<form xmlns="http://www.demandware.com/xml/form/2008-04-19">

4 usages

2 <group formid="contact">

3 usages

3 <field formid="email" label="label.email"Email address type="string" mandatory="true"/>

1 usage

4 <field formid="firstName" label="label.firstname"First name type="string"/>

5 <field formid="optIn" label="label.optin"Send me offers type="boolean"/>

6 </group>

1 usage

7 <action formid="subscribe" valid-form="true"/>

8</form>

Locale Copies

newsletter.xml app_custom/cartridge/forms/fr_FR

Copy 'optIn' from the default copy

Open the default copy

Overrides newsletter.xml in app_storefront_base

Locale copies: fr_FR in app_custom

Missing from this locale copy: 'optIn' of the default copyCopy 'optIn' from the default copy⌥⇧↩

storefrontapp_customcartridgeformsdefaultnewsletter.xmlGlobal scopeLFUTF-8

Gutter icons on the root element link the copies of a form. Each kind has its own switch under Settings › Editor › General › Gutter Icons

Icon	Switch	Opens
	SFCC form overrides	The copies this one hides, further right on the cartridge path
	SFCC form overridden by	The copies that hide this one
	SFCC form locale copies	The copies in other locale folders

Compare with Default Copy, Compare with Overridden Copy and Compare with Copy in Use open the two copies in the diff viewer. They are on the icons' right-click menu, the editor, editor tab and Project view menus, and Compare With

SiteGenesis handlers

Missing handlerGo to the action

STstorefrontSandbox 01version2

Newsletter.js

1'use strict';

2

3var app = require('~/cartridge/scripts/app');

4var guard = require('~/cartridge/scripts/guard');

5

6function subscribe() {

7 app.getForm('newsletter').handleAction({

8 subscribe: function (formGroup) {

9 newsletterHelpers.subscribe(formGroup.contact.email.value);

10 }

11 });

12}

13

14exports.Subscribe = guard.ensure(['post'], subscribe);

Add handler 'unsubscribe'

No handler for action 'unsubscribe': handleAction throws when it is triggeredAdd handler 'unsubscribe'⌥⇧↩

storefrontapp_storefront_controllerscartridgecontrollersNewsletter.jsGlobal scopeLFUTF-8

app.getForm('newsletter').handleAction({ ... }) checks its handlers against the form's actions. A handler for an action the form lacks never runs, and an action without a handler throws when it is triggered. Add handler writes the missing ones with the formGroup and action parameters, which are typed

Pipelines

In pipeline XML, key-binding alias="CurrentForms.newsletter.contact" resolves to the form and its elements, and the branches of an interaction-continue node to the actions of the form its template reads. Both complete, count as usages and rename with the form. Pipeline form bindings and branches that do not match the form reports a binding or branch the form lacks

Inspections

STstorefrontSandbox 01version2

signup.isml

1<form action="${URLUtils.continueURL()}" method="post">

2 <input name="${pdict.CurrentForms.newsletter.contact.email.htmlName}"/>

3 <input name="${pdict.CurrentForms.newsletter.contact.phone.htmlName}"/>

4 <button name="${pdict.CurrentForms.newsletter.subscribe.htmlName}">

5 ${Resource.msg('button.subscribe', 'newsletter', null)}

6 </button>

7</form>

Add field 'phone' to newsletter.xml

No element 'phone' in 'newsletter.contact'Add field 'phone' to newsletter.xml⌥⇧↩

storefrontapp_customcartridgetemplatesdefaultnewslettersignup.ismlGlobal scopeLFUTF-8

Form checks are under Settings › Editor › Inspections › SFCC › Forms

Two more checks join the existing ones

• An SFRA member the form lacks is reported by JavaScript's unresolved reference warning, as "No element 'phone' in 'newsletter.contact'", with Add field. options on a field without <options> reads "options is undefined at runtime"
• <isinputfield formfield="${...}"> with a value that isn't a dw.web form field is reported by the ISML Attribute expression type mismatch inspection

Troubleshooting

Related