Add items to the cart with custom forms

The request for more robust Ubercart add to cart forms comes up fairly regularly. People generally have in mind the sort of form that allows customers to specify quantities for a set of products and add them to the cart all at once. The request came up so often that I put a short explanation on how to accomplish this through a custom form into an FAQ post on Ubercart.org.

This article will walk through a very basic example of how you can use the Ubercart function uc_cart_add_item() in a custom form submit handler to add multiple items to the cart at once. This article assumes a basic knowledge of Drupal's Forms API. Code examples are from Drupal 6, but they are mostly applicable to Drupal 5 as well.

The Ubercart Shopping Cart

Before digging into the code to actually add items to the cart, it's a good idea for developers to have a basic idea of how the shopping cart works in Ubercart.

In Ubercart 1.x and 2.x, the shopping cart is represented in the database as a set of rows in the uc_cart_products table all related to the same user through a cart_id. Other fields in the database table include:

• nid - the node ID of the product node
• qty - the number of this product currently in the cart
• changed - the timestamp tracking the last update to the item
• data - an array that modules can use to store information about the product in the cart

When a cart is loaded through the function uc_cart_get_contents(), it is represented as an array of cart item objects. Each cart item will have the above fields as class properties along with others from the corresponding product nodes holding data like price and SKU.

Adding Items to the Cart

When adding items to the cart, you simply have to call uc_cart_add_item() with a fairly limited set of parameters. At its very basic, you can add an item just by passing the nid of the product node. If you created a product as node 2, you can add one of this product to the current user's cart just by using the code:

You can easily specify how many of the product to add to the cart using the function's second parameter:

In either of these cases, Ubercart will look in the current user's cart for any instances of product 2. If a match is found based on the nid and data array in the database, the qty for that product is simply incremented the appropriate amount. Otherwise, Ubercart will add a new row to the uc_cart_products table representing the product with the appropriate qty.

A full list of parameters for uc_cart_add_item() includes:

1. $nid - the nid of the product
2. $qty - the quantity of the product to add to the cart
3. $data - an array of data related to the product
4. $cid - the ID of the cart to add the product to; if left NULL, the current user's cart will be used
5. $message - whether or not to display a message to the user indicating that the product as added to the cart
6. $check_redirect - whether or not to check for and return the add to cart redirect based on the site's cart settings

Building a Form for Adding Multiple Products

So, knowing the basics of how the Ubercart shopping cart works, it's time to look at how to use this knowledge in a simple form. Let's imagine for a moment that you want to add a form to your site allowing users to add any number of several products from your store to the cart at once. You know the product node IDs, so you throw together a simple form like the following:

Handling User Input in the Submit Handler

Now it's time to do something with user input once this form is submitted. We'll actually want to turn the data into parameters for us with uc_cart_add_item(), so let's have a quick look in a submit handler for this form at the structure of the data. You can use the following submit handler to see what Drupal passes in as form values:

The output for a submission of the above form for someone ordering 3 beanies and 1 Uberclub membership would include:

Since we set the products array in the form array to be a tree, the Forms API passes to our submit handler an array of form values with a similar hierarchy to the elements in the form array. This means we can easily poll through the products on the form and call uc_cart_add_item() to add the correct quantity of each item to the cart like so:

Conclusion

There's certainly more you can do with a form like this. You might change the way the form elements are added to the form array and themed for display, add a validate handler to the form to check for valid quantity values, or use the actual return value of uc_cart_add_item() for the redirect.

However, this simple example should at least help you get started using the Ubercart API to build custom add to cart forms to better serve your customers.