Object Binding with Forms

Using Pipelets to Bind Objects

In practice, the firstname form field is used to interact with the firstName property of the Profile object. For the actual field-to-object binding to occur, you use the UpdateFormWithObject pipelet. This pipelet attaches the business object to the customer group element and binds the field elements to specific form properties. When using the UpdateFormWithObject pipelet in a pipeline, you must specify the business object to use and the form you want to update. In the SiteGenesis application, the Account-EditProfile pipeline populates the customer group with the Profile business object using these expressions:

• CurrentForms.profile.customer - identifies the form element to update.
• CurrentCustomer.profile - identifies the business object to use.

Both CurrentForms and CurrentCustomer are stored in the Pipeline Dictionary.

Templates

In the ISML page, the firstname field is used to access the value of the Profile.firstName property:

<isinputfield formfield="${pdict.CurrentForms.profile.customer.firstname}" type="input">

When the ISML page appears in the browser, the firstName property is rendered as an HTML input field. After the user changes the input field value and submits the page to the server, the Forms Framework uses the UpdateObjectWithForm pipelet to copy the values in the form instance to the corresponding business object using the same binding attribute.

Binding Collections

The firstname form field definition is a simple example of how a single field can be bound to specific business object property. You can also use object binding to bind a collection of objects to a collection of form instances via the < list> form element.

For example, the following < list> element definition is from the cart form definition:

<list formid="coupons"></list>

As you can see, the coupons list doesn't use the binding attribute. But when you use the UpdateFormWithObject pipelet with a collection and a list, the pipelet creates a list element instance for every business object in the collection and binds a business object to each list element instance. From an expression perspective, the individual list item instances are represented as a numbered array. For example, if there are three Coupon business objects there would be an array of coupons list element instances, as follows:

CurrentForms.cart.coupons[0]

CurrentForms.cart.coupons[1]

CurrentForms.cart.coupons[2]

As with all object-to-form bindings, the object can be accessed in the form using the .object identifier. To access the Coupon business object bound to the second coupons list instance, use the following expression:

CurrentForms.cart[1].object

Binding Within Nested Lists

Like the firstname form field definition, the coupons list definition illustrates simple object binding. However, the Forms Framework lets you create nested form element definitions and use object binding to access business objects and their values. For example, the following list element definition is from the cart form definition:

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

The shipments list contains a child list called items, which has a binding to the property productLineItems. The child list items contains a field definition with a binding to quantityValue. To populate the items list, pass a collection of objects to the shipments list, where the business objects in the collection have a productLineItems property.

For example, the Cart-PrepareView pipeline in the SiteGenesis application uses the UpdateFormWithObject pipelet to populate the shipments list with the expression Basket.shipments, which returns a collection of Shipment objects. Because the Shipment.productLineItems property returns a collection of ProductLineItem business objects, B2C Commerce can bind a ProductLineItem business object to each instance in the items list. Furthermore, because the ProductLineItem business object has a quantityValue property, the pipelet is able to populate the quantity field in each list item instance. If we had a basket that represented two shipments, and each shipment had a one product line item, the in-memory form list would resemble the following:

CurrentForms.cart.shipments[0]

CurrentForms.cart.shipments[0].items[0]

CurrentForms.cart.shipments[0].items[0].quantity

CurrentForms.cart.shipments[1]

CurrentForms.cart.shipments[1].items[0]

CurrentForms.cart.shipments[1].items[0].quantity

Triggered Actions

So far, all of these examples have shown how B2C Commerce and pipelets bind objects to forms and fields to object properties. In addition, you can use action elements to easily identify which object is associated with the triggered action. In B2C Commerce, the triggered action represents the HTML action that caused an HTML form to be posted to the server.

For example, in the SiteGenesis application, the coupons list in the cart form contains an action element:

<list formid="coupons">
	<action formid="deleteCoupon" valid-form="false"/>
</list>

When B2C Commerce populates the list with a collection of coupons, the corresponding in-memory array would resemble the following:

CurrentForms.cart.coupons[0]

CurrentForms.cart.coupons[0].deleteCoupon

CurrentForms.cart.coupons[1]

CurrentForms.cart.coupons[1].deleteCoupon

CurrentForms.cart.coupons[2]

CurrentForms.cart.coupons[2].deleteCoupon

When an action is actually triggered in the browser, you can easily access the object associated with the action using the following expression:

TriggeredAction.object