Home » Documentation » Ubercart API

hook_line_item
Function hook_line_item() in uc_order.module:
<?php
  hook_line_item()
?>

Description:
hook_line_item is used to define line items to be attached to orders. A line item is a representation of charges, fees, and totals for an order. Default line items include the subtotal and total line items, the tax line item, and the shipping line item. There is also a generic line item that store admins can use to add extra fees and discounts to manually created orders. Module developers will use this hook to define new types of line items for their stores. An example use would be for a module that allows customers to use coupons and wants to represent an entered coupon as a line item. Once a line item has been defined in hook_line_item, Ãœbercart will begin interacting with it in various parts of the code. One of the primary ways this is done is through the callback function you specify for the line item. The function ought to be constructed like so:
<?php
function callback_name($op, $arg1) {
  switch ($op) {
    case '...':  // Actual case values described in table below.
      break;
  }
}
?>
When this function is called, the value of $op will specify what sort of information Ãœbercart is expecting to receive in return. The following possibilities are currently in place:
$op Use/Return Value
load When line items are being loaded, items that aren't stored in the database are loaded using this function. $arg1 is the order object. The expected return value is an array of associative arrays with the following keys:
Key Type Value
id string A unique ID for the line item when it is displayed.
title string The title of the line item when displayed on the order. Use t().
amount float The value of the line item as displayed on the order.
Example:
<?php
  case 'load':
    $lines[] = array(
      'id' => 'subtotal',
      'title' => t('Subtotal'),
      'amount' => uc_order_get_total($arg1, TRUE),
    );
    return $lines;
?>
display For line items that are set to display only, their callbacks are called with this $op when the order is being displayed. $arg1 is the order object. The expected return value is exactly the same as that for load described above.
cart-preview During customer checkout, the payment pane will display a preview of the line items and order total. For the initial page load, every line item's callback gets called with this $op so they have a chance to set a default value. Default values should be set using drupal_add_js() to call the Javascript function set_line_item(key, title, value, weight) described below. $arg1 is an array of of product objects for the items in the cart. Note: This is not necessary. This is only for the default display. Other panes on the checkout screen may dynamically add items to this list using set_line_item() in their own Javascript files. The arguments for that function are as follows:
Argument Type Value
key string The unique internal ID of the line item for display.
title string The display title of the line item. You should use t() to establish this value, even if it means adding this as a global variable to the page using drupal_add_js() when your pane is loaded.
value float The value of the line item. (Used for display and calculating the total.)
weight int The display order of the line item.
Example:
<?php
  case 'cart-preview':
    $subtotal = 0;
    foreach ($arg1 as $item) {
      $total = ($item->qty) ? $item->qty * $item->price : $item->price;
      $subtotal += $total;
    }
    drupal_add_js("\$(document).ready( function() { set_line_item('subtotal', '". t('Subtotal') ."', ". $subtotal .", -10); } );", 'inline');
    break;
?>
Return value:
Your hook should return an array of associative arrays like the example above. Each item in the array represents a single line item and should use the following keys:
Key Type Value
id string The internal ID of the line item.
title string The title of the line item shown to the user in various interfaces. Use t().
callback string Name of the line item's callback function, called for various operations.
weight int Display order of the line item in lists; "lighter" items are displayed first.
stored bool Whether or not the line item will be stored in the database. Should be TRUE for any line item that is modifiable from the order edit screen.
add_list bool Whether or not a line item should be included in the "Add a Line Item" select box on the order edit screen.
calculated bool Whether or not the value of this line item should be added to the order total. (Ex: would be TRUE for a shipping charge line item but FALSE for the subtotal line item since the product prices are already taken into account.)
display_only bool Whether or not this line item is simply a display of information but not calculated anywhere. (Ex: the total line item uses display to simply show the total of the order at the bottom of the list of line items.)

Example:
<?php
function uc_order_line_item() {
  $items[] = array(
    'id' => 'generic',
    'title' => t('Empty Line'),
    'weight' => 2,
    'default' => FALSE,
    'stored' => TRUE,
    'add_list' => TRUE,
    'calculated' => TRUE,
    'callback' => 'uc_line_item_generic',
  );

  return

$items;
}
?>

Notice that line items are defined with an array similar to menu items in Drupal's hook_menu.