Checkout

The checkout form for Ãœbercart is a compilation of enabled checkout panes and some default controls. Checkout panes can be used to display order information, collect data from the customer, or interact with other panes. Panes are defined in enabled modules with hook_checkout_pane() and displayed and processed through specified callback functions. Some of the settings for each pane are configurable from the checkout settings page with defaults being specified in the hooks.

The default panes are defined in uc_cart.module in the function uc_cart_checkout_pane(). These include panes to display the contents of the shopping cart and to collect essential site user information, a shipping address, a payment address, and order comments. Other included modules offer panes for shipping and payment purposes as well.

Checkout Pane Builder Functions

The meat of a checkout pane is its builder function. These can use any naming convention so long as the function is referenced properly in the hook_checkout_pane(), but Ubercart uses uc_checkout_pane_pane ID. The function will be called at various times during checkout to build and process the pane and should accept the arguments $op, $arg1, and $arg2. An example function definition from uc_cart.module is:

<?php
function uc_checkout_pane_delivery($op, &$arg1, $arg2)
?>

The builder function should consist of a switch statement on $op to detect what information is being requested by Ubercart. This function may be called with the following strings in $op:

  • view - Called to display the pane on the checkout screen. Expected to return an array with the following keys:
    • description - string The default description text displayed in the pane's fieldset. Defaults to NULL.
    • contents - array An array of form elements added as children to the pane's fieldset. Defaults to NULL.
    • theme - string The name of a themable function used to render the fieldset on the form. This is not the actual function name, but rather a title of sorts (like address_pane). The function name in your module should be the themable name preceded by theme_ (like theme_address_pane() in uc_cart_checkout_pane.inc). Defaults to NULL.
    • next-button - boolean Set the value to FALSE if you this is a pane that cannot be collapsed and should not receive a Next button if the store owner is using collapsible panes. Defaults to TRUE.

    $arg1 is the current order object if it exists.

  • review - Called to display a review of the pane's information the order review screen when checking out. This can return a string containing HTML output to be dropped into a div, an array of HTML strings to be displayed in separate rows, or an array of arrays (with 'title' and 'data' keys) for display in the aligned 'Title: data' format. $arg1 is the current order object.
  • process - Called when the temporary order is created during checkout after the customer continues from the checkout screen and before the review screen is displayed. No return is expected. $arg1 is a reference to the current order object. (So, by modifying $arg1 in the process block, you are modifying the actual order.) $arg2 is the contents of the array of the submitted form information for that pane.

For an example implementation of hook_checkout_pane() and the whole saving/loading process of data collected on the pane, check out the Lead Tracker contribution. Notice that you may need to implement hook_order() to save/load information collected in a pane, which would also require you to implement hook_order_pane() to display the information on the order screens.

The alternative is to store your pane's information in the $order->data array. This should be done if you won't ever need to query the data by itself. The data array is loaded every time the order is loaded, so you have automatic storage and retrieval of any variables your module needs to access along with the order.

TODO:
Add documentation for undocumented $op = 'customer' as used in, e.g. uc_shipping.module