Form Framework

 

Forms Framework

 

The Demandware platform provides a set of tools that help simplify form display and processing. Using the Demandware Forms framework, you can control how consumer-entered values are validated by the application, rendered on a browser and possibly stored on a server.

 

You need the following four files:

1. An xml form to define and store the metadata

2. A pipeline that will validate and process the form

3. A properties file that contains externalized form labels and possible error messages

4. An ISML template that will display the form to the user 

 There are 3 objects that interact:

1. XML metadata file: located in the cartridge/forms/default directory. It describes the fields, labels, validation rules and actions that apply when the field is used in an ISML template.

2. ISML template: it uses the form metadata fields and actions to show an HTML form to the user.

3. Object (optional): this object represents a single system or custom object in the pdict, and it can be used to pre-fill the metadata file as well as to store submitted form data to the database.

    

    

XML Metadata File

As a developer, you will need to identify which fields a user will need to enter, and what actions can be taken when implementing a form. They will need to be created in an xml form that will set the form field parameters and hold the data for the form.

 

The form metadata file uses the following XML elements: 

Element	Description
form	Required: top level tag that contains all other elements inside <form>…</form>
field	Required: Defines data field with many attributes
options	Use as a child element inside a field to pre-fill multiple options like months, days, etc
option	Use as a child element inside an options element to specify a single option
action	Required: Defines a possible action the user might take on the form
include	Allows inclusion of one form metadata definition into another.
list	Allows inclusion of several items (i.e. collection of addresses) as a single field
group	Allows grouping of elements to be invalidated together

 

The field element may use the following attributes:

Attributes	Description
formid	Required: unique ID to identify the field for ISML templates and pipelines.
type	Required: data type for field
label	Usually a key to an externalized string in the forms.properties resource bundle.
description	Description for field, might be used in tooltips.
min-length, max-length	Restricts the field length for data entry.
min, max	Valid range for integer, number and dates.
range-error 长度错误	Message shown if value provided does not fall within the specified range.
regexp 正则	Regular expression for string fields: email, phone, zipcode, etc.
parse-error 正则错误	Message shown when the data entered does not match the regex. Usually a key to an externalized string.
mandatory 经过后端验证	Field is required via server side validation when true.
missing-error 主键验证错误	Message shown if the primary key validation error is generated in a pipeline.
value-error 主键验证错误解释	解释 if a primary key validation error is generated in a pipeline.
binding	Used to match field to a persistent object attribute.
masked	Specify # of characters to mask.
format	Format for display of dates, numbers, etc.
whitespace	Specify whitespace handling (none or remove).
timezoned	Optional flag for date objects (true or false).
default-value 预先定义值	Pre-defines a value for a field.
checked-value	Value when field is checked in a form.
unchecked-value	Value when field is unchecked in form.

 

Here is an example of a simple form metadata file:

<?xml version="1.0"?>

<form>

<field formid="fname"

label="forms.contactus.firstname.label"

type="string" mandatory="true"

binding="custom.firstName"

max-length="50"/>

<field formid="lname"

label="forms.contactus.lastname.label"

type="string" mandatory="true"

binding="custom.lastName"

max-length="50"/>

<field formid="email"

label="forms.contactus.email.label"

type="string"

         mandatory="true"

         regexp="^[\w-\.]{1,}\@([\da-zA-Z-]{1,}\.){1,}[\da-zA-Z-]{2,6}$"

parse-error="forms.contactus.email.parse-error"

         value-error="forms.contactus.email.value-error"

         binding="custom.email"

         max-length="50"/>

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

</form>

 

In the example above, the fields fname, lname and email store the information needed to send a newsletter to a non-registered user. The fields are:

• Mandatory 后端验证

• Contain label keys that point to 翻译文件位置

  the cartridge/templates/resources/forms.properties file

The email field has an extra requirement: it uses a regular expression to define what an acceptable email can be. Additionally, it specifies a parse-error key which matches an error message in the forms.properties file.

 

Finally, the action subscribe identifies the possible actions that a user may take on the form. The attribute valid-form="true" means that this form requires validation: 3 required fields plus a valid email format for the last one will be enforced on the server side.

 

IMPORTANT NOTE

Although it is not a requirement, it is a best practice to use lower-case letters when naming your xml forms（小写字母命名）. Pipelines are also xml files and use camel-case naming in SiteGenesis.

 

ISML Form Template

You define an ISML template with the same tags needed for a valid HTML form: <form>…</form>

You can choose to implement your own form action by specifying a pipeline URL, but that would circumvent（绕过） the Forms Framework. When using the framework you specify an Interaction Continue Node for the form action to post to, as follows:

 

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

name="SendToFriendForm" id="SendToFriendForm">

 

The method dw.web.URLUtils.continueURL() ensures that the form gets submitted back to the Interaction Continue Node that displayed the form template.

 

When creating input fields, you must use the  object： pdict.CurrentForms.<form metadata file>.<formid> to reference the specific formid in the form metadata. SiteGenesis has an <isinputfield> custom tag which facilitates(促进) the creation of form fields. For example, to show the fname field from the

newsletter.xml file as a text field in an ISML template, you use:

 

<isinputfield formfield="${pdict.CurrentForms.newsletter.fname}" type="input">

 

The custom tag will use the fname formid from the metadata file and build an HTML label using the forms.properties file to pull the text for the

 

forms.contactus.firstname.label key. It also creates an HTML input field to the right of the label with the necessary client-side JavaScript to enforce required fields:

 

You can modify the behavior of the <isinputfield> tag since it is a custom tag implemented in the SiteGenesis cartridge.

 

The final requirement in the ISML template is to implement the button that matches the action in the form metadata. For this we create a standard HTML button with a name attribute that points to a specific action in the form metadata:

 

<input type="submit"  value="${Resource.msg('global.submit','locale',null)}"

     name="${pdict.CurrentForms.newsletter.subscribe.htmlName}"/>

 

Here the pdict.CurrentForms.newsletter.subscribe.htmlName refers to the htmlName property of the action subscribe in the form metadata. In the debugger you can view the value of this property at runtime: dwfrm_newsletter_subscribe. This value identifies a specific action for a specific form, which is necessary when the pipeline ICN determines which form action to process.

 

Form Pipeline Elements

A pipeline that uses the Demandware forms framework has a very distinctive pattern(独特模式) because it uses the following elements:

• ClearFormElement pipelet to clear an existing form object in the pdict using a specified form metadata file.

• InvalidateFormElement invalidates the specified FormElement.

• ICN to show the ISML form, and to perform server-side validation

• Transitions that match actions from the form metadata

• A “next” transition that goes back to the ICN to handle validation errors.

 To create a form using the form framework, follow these steps:

1. Create an xml metadata file that will hold your form data

2. Create an ISML template that will display a form to a visitor.

3. Create a pipeline that includes at minimum:

1. Start node

2. ClearFormElement pipelet that clears the form object next time you run the pipeline again.

3. Interaction Continue node that links to the ISML template you created in step 2.

4. Transition nodes to handle the following scenarios: