Price API

The price API is a central mechanism for modules to affect the way prices are displayed in Ubercart. Notable applications of the API are in handling European VAT tax, as well as other contributed modules such as uc_discount, uc_upsell, etc.

Terms

  • Price info consists of a numeric price and a numeric quantity. It's set up in code like this:
    array('price' => $price, 'qty' => $quantity)

    For simple prices (e.g. quantity 1), you can instead pass a numeric price directly in, in place of the price info array.

  • Context consists of a revision, a price type, a set of classes, a subject, and a field. It's set up in code like this:
    array(
      'revision' => 'themed',
      'type' => 'product',
      'class' => array(
        'product',
      ),
      'subject' => array(
        'node' => $node,
      ),
      'field' => 'sell_price',
    )
    • Revision determines what version of the price is returned by the uc_price() function. The possible values are
      • original: The numeric, unaltered price value. This also allows the other revisions to be calculated and cached for later use.
      • altered: Changes the value by passing it through the price alterer callbacks. Returns a numeric value.
      • formatted: Adds currency formatting to the altered value. Returns a string.
      • formatted-original: Adds currency formatting to the original value.
      • themed: Wraps the formatted, altered value in a theme function, theme_uc_price(). This theme function may be overridden like any other. Returns HTML.
      • themed-original: As themed, with the original value.
    • Class are CSS (Cascading Style Sheet) classes that are applied to the span that holds the themed price. Price alterers may add their own classes as well.
    • Type indicates which kinds of objects are expected in the subject. The allowed values are:
      • amount
      • product
      • attribute_option
      • cart_item
      • order_product
      • payment
      • line_item
    • Subject is the object that the price comes from, plus any other related objects that price alterers may find useful. For example, a discount price alterer may only give a 10% discount on a product if an order has another kind of product on it as well. The available subjects are determined by the type:
      amount:
      No subject information.
      product:
      Subject
      node
      Field (choose one)
      • list_price
      • cost
      • sell_price (default)
      attribute_option:
      Subject
      • attribute
      • option*
      cart_item:
      Subject
      • node
      • cart_item*
      • cart (maybe optional?)
      Field
      price
      order_product:
      Subject
      • order
      • node
      • product*
      payment:
      Subject
      payment
      line_item:
      Subject
      • order
      • line_item*

      * This object should contain the price value in its field as it is the type of object whose price is being altered.

    • Field identifies the location of the price on the type's subject. Some objects contain several price values, so the field determines which one is being used.
  • Options consists of any number of options that can be handled by the default handlers, or your own custom ones. Price alterers may also add to the options for formatters to use. It's set up in code like this:
    array(
      'sign' => variable_get('uc_currency_sign', '$'),
      'sign_after' => variable_get('uc_sign_after_amount', FALSE),
      'prec' => variable_get('uc_currency_prec', 2),
      'dec' => variable_get('uc_currency_dec', '.'),
      'thou' => variable_get('uc_currency_thou', ','),
      'label' => TRUE,
    )

Hook functions and theming

The price API provides a hook that a client module may implement. The hook allows a module to define a price alteration function, a price formatting function,
and a list of options specific for this module (or overriding other options). The options specified here are the same as the options mentioned above.

A price alteration function takes 3 arguments. A price info, a context and options. This function
is used to do mathematical transformations on the price, for instance due to tax rules that will be applied to a price. You can also set options here to be applied in the
formatting function, which will be described next. You may enable as many price alteration functions as you wish.

A price formatting function takes 2 arguments. A price info and options. This function is meant to be the view or theme
step of the price pipeline. Only one formatter may be selected, as the purpose of the function is to translate price info and options to a string for rendering.

After the formatting function returns, the output is passed along to theme('uc_price'), which takes the output of the formatter, a context and options.

The admin page at admin/store/settings/price-handlers allows you to enable alteration and formatting functions, and to specify in which order alterations occur.