Adding a Custom Token to the Ubercart (version 2.3 or newer) Email Templates

This tutorial is for Ubercart versions later than version 2.3. If you’re using an older version of Ubercart, you’ll want to see this example. This example is very similar, but accommodates the changes made to the template system in Ubercart.

In this post I’ll show how to set up an extra token for use in an Ubercart template. This will require creating a custom module (because we don’t really want to modify others’ modules). We’ll use a few different hooks to create the token, and then modify the template (or create a new template) to include this token. This setup requires the token module (which is required by Ubercart), so make sure this is enabled!

Please understand that Ubercart now uses the Drupal theme system like most other modules. This means that it is even easier to make variables available to your templates. Read last paragraph here to learn more. In the example below we’re still going to create tokens, because then we can use them in various places throughout the store administration forms. The tokens you create will appear anywhere where ORDER REPLACEMENT PATTERNS are available as replacement patterns.

Before diving into this, please make sure you have a Ubercart system that sends emails successfully when orders are placed. You should also have a test account with which you can place orders and receive emails.

1) Create a new module

2) Create the Ubercart Template

If you already have an Ubercart email template in your theme, you can skip this section. There are at least two templates (admin and customer; you can define more) by default. We’ll be working with the “customer” template for this example.

You can find the default template files in the ubercart/uc_orders/templates directory. You must make a copy of the customer template and put it into your theme directory (preferably alongside your other .tpl.php ​files). We’re going to be working with the uc_order-customer.tpl.php file, so copy that file to your theme directory. Also, due to the way Drupal’s theme layer works, you must also copy the file uc_order.tpl.php to the same directory. We’ll leave these new files alone for now and come back to them momentarily.

Lastly, check your Conditional Actions that email customer invoices (in the Store Administration area of your site); make sure they’re setup to use the “customer” invoice template.

3) Add a hook_token_values() to your custom module

This code creates a token containing the last 4 digits of the credit card number used for an Ubercart order. I’ll leave it up to you to research any of the code used. This is simply an example. You could add variables from any number of sources, including anything available in the $order object. Anything you can print to the screen you should be able to add as a token. Note: you should probably make sure the string is email-ready.

4) Add a hook_token_list() to show token in list of tokens

You can now see your new token in the list of available ubercart tokens (admin/store/help/tokens)

5) Add the token to your template

Here is a snippet that will show the new token:

 

6) Clear the Drupal cache and make sure your custom module is enabled.

7) Create an order using an email account you can check. Then, verify that it is working as expected (check the email that is sent, as well as the online invoice).

Please check out the Token and Ubercart APIs for more information! If you have problems, make sure your module doesn’t have any errors, and make sure it’s being used. Also, verify that your Ubercart system is using the new template!