corner black line corner
black line
the Hazel Logo Hazel Enterprise: The Internet Merchandising System The Netsville Logo
start red bar Home News Info Features Examples Purchase Support Contact Us end red bar
Documentation: Walkthrough

Welcome to the Hazel walk-through. Before we prim and preen your Hazel into a full and beautiful catalog you'll have to grab yourself a copy. Hazel is available for Linux, FreeBSD, and Mac OS X operating systems. Chances are she's available for your web server, but if you know what operating system your web server runs you may want to check our list of supported platforms first. If you don't know what operating system your web server runs, don't bother. During installation, Hazel will help you find out.

Next you should choose how you want to install Hazel.

The newest method of installing Hazel uses the Hazel Admin Module or the "HAM" for short. The HAM will step you through registering for a trial (if necessary), entering required configuration fields, and actually downloading all of the necessary files from Netsville's servers. It's incredibly easy and we suggest you try the HAM install method first.

If the HAM install method isn't an option for you, the traditional Hazel install methods use FTP, or a UNIX shell account through your web server. After Hazel's on your system, you'll need to configure her by editing her hazel.config file. Our configuration guide explains all of the basic fields.

After installing and configuring, you should know the URL corresponding to your Hazel CGI. Hit it from your web browser to view the sample catalog.

The sample catalog is fully functional from front door to checkout counter. Its pages demonstrate the use of Hazel's actions to communicate with the Hazel CGI, and Hazel's tokens to insert information about your catalog and the current order into your pages. When you're ready to start hacking on these sample pages, try enrolling in our crash course in Hazel catalog design.

Buy a FOO. Once you add something or view your order, you've entered Hazel's "checkout process". The pages you see during this stage are based on pre-defined templates which you may edit to personalize your storefront.

The basic layout of the templates is designed for simplicity which won't interfere with your current design, but you'll probably want to edit them to fit the overall look and feel of your catalog by changing backgrounds and adding graphics. A well-designed catalog is a successful catalog! The more professional your catalog appears, the more trust your shoppers will have in you!

There are a few things you'll be required to change before opening your virtual storefront for business. Most of these are located in the checkout template as four drop-down boxes-- (1) the payment method, (2) the tax region, (3) the shipping region, and (4) the shipping method.

If you view the actual checkout.html template, you'll see that the option values for each of these selections are not actually in the HTML. They're read in with Hazel's HAZEL_LOOP tag. The values themselves are stored within the loops directory of your catalog root, each as a text file, with each line describing an option.

The most straight-forward of these options is the payment method. Load the payment_methods.txt file into your favorite text editor (Netsville suggests using TextPad for Windows and TextMate for the Macintosh). Each line describes a method of payment supported by Hazel. The stuff to the left of the semicolon is the prefix to that payment method's template in the hazel-cat/templates/payment folder. The stuff to the right is what will be printed in the drop-down box.

Delete the lines describing methods you don't plan to use. Save the file, reload the checkout screen on your browser, and Voila! They've changed! Now your customers can choose only those payment methods you plan to support. If you look into the payment subdirectory of your templates directory, you'll see HTML files corresponding to the different payment methods supported by Hazel. You may edit these templates to change the appearance of the various confirmation screens for each payment method.

Notice next the drop-down for TAX_REGION. The tax region is used to simplify calculating sales tax for the order. In the rules directory under your catalog root you'll find a sales_tax.rules file. Hazel reads in this file and interprets it, using information entered through the TAX_REGION and other billing fields. This is how she determines what sales tax is to be applied to the order. This is one of Hazel's rules files. Through your rules files, you communicate to Hazel how you'd like certain charges applied (or deducted) from your orders.

Chances are the tax regions listed aren't applicable to your catalog. No problem! Just edit the tax_regions.txt loops file to reflect the regions for which you charge sales tax, then edit your sales_tax.rules file to apply tax respective to those new regions.

Aren't charging any sales tax? Good for you! Fight the power! Replace the drop-down box with a single "hidden field" like so...


The hidden field will not be visible to the shopper, but will be passed to Hazel. (Now she won't gripe about it being missing.)

The SHIP_REGION field serves the same purpose as the TAX_REGION, but for shipping calculations. With sales tax, the shopper doesn't really have a choice what tax he pays -- that's determined by the government. With shipping, Hazel looks for a "*.rules" file in your rules/shipping directory with a name matching the value of the SHIP_METHOD field, and uses that file to determine how the order is to be shipped.

If you only have one shipping method, use a hidden field for SHIP_METHOD to tell Hazel which rules file to use. (As with the TAX_REGION above.)

The regions are a simple (and less prone to user-error) way to calculate charges; you can also use postal codes, state codes, country codes, and other information entered at the billing and shipping stage. Use the rules documentation and the sample rules files to build your own rules.

Assuming all you want to sell is foos and whatnot, you're all set. You probably want to sell something else. Products are saved in Hazel's products file. Load the products file (located in your catalog root) into your text editor and use the existing sample products as a guide for creating your own. Don't be afraid! Add an SKUID, NAME and PRICE line to the end of the file, save it, then tell Hazel to add the new item.

That's just about it. Build from the sample catalog and templates. If you have any comments, questions, or suggestions regarding the documentation or ways we can make Hazel easier to install and configure, please contact us at

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

black line
corner black line corner