TableHandling

The TableHandling component, which appears in the Handling stage of an order processing pipeline, sets the value of _handling_total on the order form by using values retrieved from the database.

Note  This component is used for compatibility with Commerce Server 2.0 sites, in which the database connection is provided by the Content object in the Pipe Context. Commerce Server 3.0 sites should use the TableHandlingADO component.

• Key. (Read-only) The name of a property on the order form used to specify handling method. The value of this property is compared to the string specified in the Method field to determine whether to apply the handling charge to the order.
• Apply when. Specifies when to apply the handling charge.
  • Equal to Method. Specifies that the handling charge should be applied if the value of the field specified for Key is the same as the string specified in the Method field.
  • Has Any Value. Specifies that the handling charge should be applied when the value of the field specified for Key has any value on the order form. If you select this option, the Method field should be left blank.
  • Always. Specifies that the handling charge is always applied to the order.
• Method. If Equal to Method is selected, specifies a string that the component compares with the value of shipping_method on the order form to determine whether to apply the handling charge to the order. The handling charge will be applied only if there is an exact match.
• Basis Item Key. Specifies the property of the item that is used to compute the handling charge. The component computes the charge by multiplying the value retrieved by the database query by the sum of the property specified for Basis Item Key. For example, you might base the handling charge on the quantity of the items, and the Basis Item Key might be sum.quantity. If the order contains two items, one item with a quantity of four and the other item with a quantity of two, then the basis sum is six. The component multiplies the handling charge by six. See Specifying the Basis Item Key.
• Query. Specifies either the full SQL text of the query that is executed by this component or the name of a query whose full SQL text is stored in the Content object.
• Order Key. Specifies the property of the order as a whole that is used to compute the handling charge. This key is the name of a column in a database table that specifies a per-order handling charge. This parameter is optional; if none is specified, it defaults to ship_to_zip.
• Item Key. Specifies the property of each item that is used to compute the handling charge. This key is the name of a column in a database table that specifies a per-item handling charge. This parameter is optional; if none is specified, it defaults to cost.

Remarks

The combination of the Key, Apply when, and Method fields determine whether the handling should be applied to the order.

The TableHandling component first checks the Apply when value. If it is set to Always, the handling charge is always applied to the order. If Apply when is set to Has any value, the handling charge is applied to the order whenever the order form contains any value for shipping_method. If Apply when is set to Equal to Method, the component does a comparison between the value of shipping_method on the order form and the text string in the Method field on this property page. If there is a match, the handling charge is applied.

If the component determines that the handling charge should be applied, it then executes the query specified in Query. This query retrieves the per-item and per-order handling charges from the database, and then uses the value of the Basis Item Key to compute the handling charge.

The Method name, the aggregated basis, and the value of the location are given as arguments to the query, which must return a single number as a result. With some databases, the query must refer to all three variables, even if it does not need them (see the following example):

select cost, :2, :3 from shipping_costs
where min_weight <= :1 and max_weight > :1

The :2 and :3 refer to the location and method, respectively. These are the database column number references. The component ignores the return fields after the first, but some databases will issue an error if you do not refer to them at all. The :1 refers to the product weight.

Related Topics

• Component Coordination