Object Binding with Forms

Object binding lets you associate one or more business objects with a Salesforce B2C Commerce form instance and associate form elements with specific business object properties. By using object binding, you can easily transfer business object values into ISML pages for rendering in a user's browser; and you can also easily update business objects with values submitted by a customer. To use object binding, you:

  1. Create a form definition where form elements identify business object properties using the binding attribute.
  2. Use the UpdateFormWithObject pipelet to associate a business object with an in-memory instance of the form definition.
  3. Use tags in your ISML page to access the in-memory form instance and corresponding business object properties.
  4. Use the UpdateObjectWithForm pipelet to update the business object with values submitted by a customer from their browser.

Example: Profile Form Definition

For example, the profile form definition in the SiteGenesis application contains a group definition called customer. This group contains field definitions that represent properties in the Profile business object. The following field definition from the customer group indicates that the firstname field is bound to the firstName property in a business object:

<group formid="customer">
	<field formid="firstname" label="forms.profile.001" type="string" mandatory="true" binding="firstName" max-length="50"/>
</group>

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:

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]
the first coupon
CurrentForms.cart.coupons[1]
the second coupon
CurrentForms.cart.coupons[2]
the third coupon

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]
The first shipment
CurrentForms.cart.shipments[0].items[0]
The first ProductLineItem in the first shipment
CurrentForms.cart.shipments[0].items[0].quantity
The field containing the value of the quantityValue property in the first ProductLineItem field
CurrentForms.cart.shipments[1]
The second Shipment
CurrentForms.cart.shipments[1].items[0]
The first ProductLineItem in the second shipment
CurrentForms.cart.shipments[1].items[0].quantity
The field containing the value of the quantityValue property in the first ProductLineItem field

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]
the first coupon
CurrentForms.cart.coupons[0].deleteCoupon
the action associated with the first coupon
CurrentForms.cart.coupons[1]
the second coupon
CurrentForms.cart.coupons[1].deleteCoupon
the action associated with the second coupon
CurrentForms.cart.coupons[2]
the third coupon
CurrentForms.cart.coupons[2].deleteCoupon
the action associated with the first coupon

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