Using Hazel's themes feature, a merchant can provide multiple presentations of their Hazel store without installing multiple catalogs. Alternative loops/ rules/ and templates/ directories and products and options files are stored for each catalog theme.

Themes have been used by merchants to present catalogs in several different languages, and is used by the Hazel development team to separate test catalog files from those distributed in Hazel releases. You can use themes for just about anything which would have required setting up multiple catalogs.

Except a mall setup. You can't do that. A single hazel.config is used for all themes, thus the order recipients, store name and e-mail, and other global information is the same through all themes.

Setting Up a Theme

Setting up a Hazel theme basically involves copying many of your existing hazel-cat files into new directories under a hazel-cat/themes directory. Here's a sample shell session outlining what you'd do to create two new themes: one named "en" (for english) and one "jp" (for Japanese).

1$ #echo "dear god help me themes shred my noodle" | mail
2$ cd ~/hazel-cat
3$ mkdir themes
4$ mkdir themes/en
5$ cp -r loops/ rules/ templates/ products options themes/en
6$ cp -r themes/en themes/jp

Here's a translation for those who don't speak shell:

  1. Don't mail yet. You're doing fine.
  2. Go into your hazel-cat directory.
  3. Create a "themes" directory inside of it.
  4. Create an "en" directory inside of the new themes directory. It will hold the data for the english version of your catalog. In our example, this will be your default theme.
  5. Copy your existing loops/, rules/ and templates/ directories and your options and products files into the new themes/en directory.
  6. Repeat the process for a themes/jp directory.

Now you've got yourself two themes. The next step is to add a DEFAULT_THEME field to your hazel.config file, with a value of the theme you wish to be your default. In our case, that's the "en" theme, so we'd add a line like this:


We're pretty much done now. At this point, you can safely delete the old loops/, rules/, templates/, products and options in your hazel-cat directory. They will no longer be accessed by Hazel. Instead, she'll use those in your default theme directory in hazel-cat/themes/en, unless you tell her to use another theme...

Choosing a Theme

Choosing which theme to use is easy. Simply pass a theme field to Hazel with a value of the theme you wish to become active. Here's some sample HZML enabling shoppers to choose their theme:

<a href="%HZU_ACTION=serve&item=en/start.html&theme=en">English Catalog</a> - 
<a href="%HZU_ACTION=serve&item=jp/start.html&theme=jp">Japanese Catalog</a>

Henceforth, Hazel will use the appropriate theme directory whenever that shopper accesses the catalog. As with all Hazel fields, the theme value is stored throughout the shopping session.

Note that in the sample links above we're serving up HTML files in "en" and "jp" directories. Hazel's themes only modify your CAT_DIR. The DOC_DIR remains unchanged. If you want themes to crawl into subdirectories of your DOC_DIR, set DOC_DIR_FOLLOWS_THEME in hazel.config.


There is no limit to the number of themes your catalog may utilize. They can be useful not only in providing options for your international shoppers, but for special promotions, seasonal mood swings (April Fools!), and especially the practical application of testing new rules and templates without going live. Just copy your hazel-cat files into a "test" theme and pass it as a theme value when you enter your catalog.

Themes are an easy way to enhance your catalog and expand your customer base. We'll leave you with a link to Peruvian Connection -- an excellent use of Hazel and themes!

Getting Started HZML Rules Extras Advanced Reference
Products File
Order Reporting
Known Problems
HZML Tokens
HZML Loops
Sales Tax
Input Fields
Search Engine
Optioned Products
Design Tips
Payment Methods
Regular Expressions
Perl API
HTML Basics
CGI and You

Hazel Home - Help Contents - Searchable Knowledge Base - Live Technical Support

Last modified: Monday, 07-Apr-2003 14:47:59 EDT