For developers: Persist the values of the fields in the CartOrder instance

To persist the get the values of the custom fields, you have to use the EcommerceCheckoutPageChanging event. It occurs every time the user navigates between the steps of the Checkout widget. In the handler for this event you can get instances of the UI controls for the fields and their values. You subscribe to this event in the Global.asax file. For more information about how to subscribe to this event and its event arguments, see the For development: IEcommerceCheckoutPageChanging event article.

The code for getting and persisting the values of the custom fields, is going to be placed in the handler for the EcommerceCheckoutPageChanging event.To get the values of the fields and persist them in the CartOrder instance, perform the following:

1. Check if the shopping cart is empty.
   The EcommerceCheckoutPageChanging event could be raised after the shopping cart was destroyed. Because of this, you have to make sure that the shopping cart exists. To do this simply check whether the ShoppingCartId value of the arguments is different form null or Guid.Empty.
2. Check the index of the current step.
   To check the index, use the CurrentStepIndex value of the arguments. In this example you need the steps “Shipping Information” and “Preview”. Their indexes are respectively 0 and 3.

   NOTE:  Ensure to look for the respective field control only in the corresponding checkout step. It is important to perform this check because of the way the checkout pages are constructed. In some cases you may be able to find the control in a step even when it is actually in another step. In this case you may end up retrieving the wrong value from the control and thus persisting wrong data. Therefore, it is safest to verify the step whenever you save data from a control.

3. Persist the value of the newsletter subscription field.
   This is done in the Sipping Information step. To persist the value of the field, you must perform the following:
   1. Get an instance of UI control for the field.
      To get an instance of the UI control for the field, you must use the GenericContainer instance stored in the Container property of the event arguments. Call its GetControl method and pass the id of the control. As generic argument pass the class of the UI control, in this case System.Web.UI.WebControls.CheckBox.

      NOTE: The second argument accepted by the GetControl method is of type boolean and indicates whether the control should be treated as required or not. If the control is required and cannot be found, the method will throw an exception. If the control is not required and it does not exist, the method will return null.

   2. Get the value of the field.
      Get the value stored in the UI control. In this case you need the value of the Checked property of the CheckBox control.
   3. Get the orders manager.
      Get an instance of the OrdersManager object.
   4. Get the current cart order.
      To get an instance of the current cart order, call the GetCartOrder method of the orders manager. The ID of the current cart order is stored in the CartOrderId property of the event arguments.
   5. Get the properties for the cart order instance.
      To get all properties and their values for the cart order instance, call the GetProperties static method of the TypeDescriptor class. As an argument pass the instance of the cart order.
   6. Get the Newsletter field.
      From all the properties, get the one you need. In this case it is the one named Newsletter. To get it, use its name as a key. When getting the field, use the same name that you used during its creation.

      NOTE: Information about creating this property can be found in the For developers: Create the custom fields for the CartOrder and Order classes article.

   7. Cast the object to MetafieldPropertyDescriptor.
      Cast the instance of the PropertyDescriptor class that represents the field, to MetafieldPropertyDescriptor.
   8. Set the value of the Newsletter field.
      To set the value of the field, call the SetValue method of the MetafieldPropertyDescriptor instance. As arguments pass the instance of the cart order and the new value.
   9. Save the changes.
      Save the changes to the orders manager.
4. Persist the value of the gift message field.
   This is done in the Preview step. Repeat the same sub-steps as in step 3, but for the gift message field.

Use the following code sample:

NOTE: The code snippet above also contains the code form the previous article – For developers: Create the custom fields for the CartOrder and Order classes.