List Form Element

The <list> element lets you generate a list within a form, so that the contained fields appear more than once. It can be a list of anything, including an <include>. All contained fields are automatically grouped together to form a complex data structure.

Salesforce B2C Commerce automatically generates the required number of fields and binds objects to those fields. For each element in a collection, B2C Commerce generates a set of fields representing each collection element.

This element is represented by the dw.web.FormList API class.

Attribute	Description
formid	The identifier of the list (required).
binding	The method that acts on the business object. For example, in the following xml: `<list formid="products" binding="products"> <field formid="name" type="string" binding="name"/>` B2C Commerce binds the products method to the designated business object (for example, productlineitem), then for that object, binds the name method to the designated business object (for example, productlineitem.name).
selectmany-fieldid	When a list is represented by an HTML table and a column contains checkboxes, the selectmany-fieldid attribute tells B2C Commerce which of the fields is used to represent that selection checkbox. B2C Commerce then provides direct access to all selected objects. Note: selectmany-fieldid and selectone-fieldid are mutually exclusive.
selectone-fieldid	When a list is represented by an HTML table and a column is a radio button, the selectone-fieldid attribute tells the framework which field is used to map the boolean state of the radio buttons. Note: selectmany-fieldid and selectone-fieldid are mutually exclusive.
form-error	The error message to use for the form container. If the container is considered invalid, this is the error message that is set on the container. See the invalidateFormElement pipelet.
object-def	The value of object-def must be the name of a business object, for example, CustomerAddress, or the name of custom business object that is prefixed with Custom (for example, Custom.MyObject).
validation	B2C Commerce script expression that resolves to a custom validation function provided by a B2C Commerce Script Module. The referenced function can return a `dw.web.FormElementValidationResult` object. The form-error attribute specifies a generic error message that is used whenever your validation function returns false (that is, if the `FormElementValidationResult.isValid()` method evaluates to `false`). The validation attribute was added in version 16.1.

Note: A list is a group. It can contain the same type of objects that a group can contain.

Example:

The following shows a list element in the compare form:

<list formid="products" binding="products">
	<action formid="addtocart" valid-form="false"/>
	<action formid="addtowishlist" valid-form="false"/>
	<action formid="remove" valid-form="false"/>
</list>

This form definition defines a product along with the name field and three actions (represented on the browser page as buttons). For each product line item, the following elements will exist:

Addtocart button
Addtowishlist button
Remove button

Object Binding

In the previous example, the options are hard-coded. You can also build this kind of information dynamically by binding methods to objects to represent the data as in-memory tables.

The Cart-PrepareView pipeline in the SiteGenesis application uses object binding, as follows:

Decision Node: The system checks to see if the basket is empty.
Pipelet: UpdateFormwithObject: This pipelet iterates over the shipments section (shown here) of the cart form metadata (cart form), to bind that metada to an object.
< !-- shipments -->

< list formid="shipments">



<list formid="items" binding="productLineItems">

<field formid="quantity" type="number" binding="quantityValue" format="0.#"/>

<action formid="editLineItem" valid-form="false"/>

<action formid="deleteProduct" valid-form="false"/>

<action formid="addToWishList" valid-form="false"/>

<action formid="addToGiftRegistry" valid-form="false"/>

For each productLineItem, it:
1. Gets the contents of the productLineItem business object (< list formid="items" binding="productLineItem">) using the getproductLineItem method.
2. Gets the contents of the quantityValue business object (<field formid="quantity" type="number" binding="quantityValue" format="0.#"/>) using the getquantityValue method.
3. Provides for the four actions.
Pipelet: UpdateFormWithObject: This pipelet refreshes the coupon information.
Script: Cart.ValidateCartForCheckout: This script implements a typical shopping cart checkout validation.
Script: Assign. This script assigns the coupon status.