Converting Modules from Ubercart 1.x to 2.x

Converting modules from Ubercart 1.x to 2.x requires first of all that you update your modules from Drupal 5 to Drupal 6 using the conversion guide and related pages. Use of the coder module is highly recommended. Ubercart 2.x strives to remove as many dependencies as possible, so the uBrowser, TAPIr, and Workflow-ng dependencies have been removed. The UI will be changed where necessary to accommodate the lack of uBrowser. TAPIr will be rolled into core as a layer over the Forms API. Conditional Actions will replace the functionality of Workflow-ng for now.

Index of changes:

  1. New form summaries extension to FAPI
  2. TAPIr trimmed down, enhanced, and added to core
  3. Use of uc_add_js() have been reverted to drupal_add_js()
  4. uc_taxes_get_rates() replaced by uc_taxes_rate_load()
  5. hook_calculate_tax() returns an array of objects, not an array of arrays
  6. uc_price() and custom price handlers
  7. Arguments to theme_uc_product_price() changed
  8. hook_cart_item_description() changed to hook_product_description()
  9. hook_uc_form_alter() added to the add to cart forms
  10. Storage format of attributes on ordered products has changed
  11. API function uc_cart_get_total_qty() added to UC Cart

New form summaries extension to FAPI

Settings overviews are now generated based on form arrays, so modules can add their own summaries to existing overview pages without having to patch core modules. Summaries can also be altered to your liking using the handy hook_form_alter(). For more information, please refer to the Form Summaries documentation.

TAPIr trimmed down, enhanced, and added to core

In line with one of our Ubercart 2.x goals to remove external dependencies, the TAPIr code has been folded into the Ubercart core. The system has been updated to be used through the Forms API and will require updates to any modules using TAPIr or interacting with core TAPIr tables. For more information, please refer to the TAPIr documentation.

Use of uc_add_js() have been reverted to drupal_add_js()

Drupal 6 introduced some core features to help flush browser cached CSS and JS. Our function interfered with this and so was deprecated in favor of the core drupal_add_js().

uc_taxes_get_rates() replaced by uc_taxes_rate_load()

The taxes module in Ubercart 1.x did not have a well-defined API. This has been solved, and as a result, modules need to update their use of uc_taxes_get_rates() to the new uc_taxes_rate_load() function. When no arguments are passed to the new function, it returns the same array as the old function.

hook_calculate_tax() returns an array of objects, not an array of arrays

Previously, hook_calculate_tax() returned an array of tax arrays. This isn't consistent with the way line items are usually handled, so it's been changed to return an array of objects. A simple cast to (object) should be sufficient in most cases.

uc_price() and custom price handlers

As a way to allow modules to affect the way prices are presented to customers (particularly as it applies to prices including VAT), uc_price() must be used whenever a price may need to be altered or formatted for display. It calls the price handler hooks which determine how the price must be adjusted and formatted based on the context in which it is displayed.

Arguments to theme_uc_product_price() changed

With uc_price() able to add its own themeing and styles to prices, the arguments passed to theme_uc_product_price() have changed to accommodate it. It now takes the $price, $context, and $options and passes them directly to uc_price(). It still wraps the price in a <div> element that has classes based on the $context, so it is still useful as a theme function.

hook_cart_item_description() changed to hook_product_description()

The name of the hook was changed to reflect the fact that it is used on the order view as well as the cart and checkout pages. In addition, the return value of the hook has changed from an HTML string to a drupal_render()-able array. While drupal_render() will concatenate the results by default, modules may change the entire product description array with hook_product_description_alter().

hook_uc_form_alter() added to the add to cart forms

Since uc_attribute, and possibly other modules, have to alter the add to cart form, it is rather difficult to alter the changes it makes. This hook makes that easier by giving modules the chance to alter the add to cart form before hook_form_alter() is run. Any modules that implement hook_form_alter() on the add to cart form will see those changes as if they were part of the original form. Because of the position of hook_uc_form_alter() in the Form API workflow, none of the default values and keys have been set in the $form array as they are in hook_form_alter() (e.g.: #parameters, #validate, #submit). Support for hook_uc_form_alter() can, in theory, be added to any form, but only the add to cart form and the add product to order forms have it.

Storage format of attributes on ordered products has changed

Attribute options can now be chosen with checkboxes, which allows multiple options to be chosen at once for an attribute. In the cart item data, attribute options were stored as an array with attribute ids mapping to option ids. Ordered product data mapped attribute names to option names. Now attributes are mapped to an array of options, either ids or names. Modules that inspect and display the attribute data should take this new data structure into account by casting the option values to an array. Older orders will still be in the singular option format, so the cast will turn it into an array of one value, allowing array functions and syntax to be used.

API function uc_cart_get_total_qty() added to UC Cart

There is now an API function in the cart module that other modules and themes can use to easily return the number of items in the shopping cart. This function is based on loading the cart and tallying up the quantity of all the items in the cart.