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: Rules

Certain items such as sales tax and shipping costs cannot be "hard-coded" into an ordering system. The methods used to arrive at these totals are peculiar to each merchant. Hazel realizes this, and consults "rules" files to determine how your policies work.

Rules files are text files consisting of headers followed by lines of "rules". A rule consists of some requirement, and an action to be performed if the requirement is satisfied. Optionally, a rule might have a note attached, which will be added to the order notes if its rule passes.

Let us learn by example, grasshopper. Below is a simple sample discount rules file.

# discount.rules
#  These are the discount rules.  This is a comment.

100.00-200.00:x0.10  @ 10% off orders between $100 and $200!

# "[PRICE]" is the header.  The requirements will be
#  compared against the total price of selected merchandise.

# "100.00-200.00" is the requirement.  The rule
#  passes if the price mentioned above falls between 100 and 200.

# "x0.10" is the action.  Since these are discount
#  rules, it is interpreted as meaning "take 10% off the price of the
#  merchandise".

# "@ 10% off orders between $100 and $200!" is the
#  note.  If the rule passes (the order price is somewhere within 100 and
#  200), then "10% off orders between $100 and $200!" will be added as an
#  order note.

As in the config file, anything after and including a pound sign ("#") is ignored by Hazel. They're included only to improve readability for humans.


Headers define the value which must meet a rule's requirement. Each rules file has its own set of basic headers, detailed in their individual sections.

Advanced users can specify any header using Hazel's HZML tokens and a rule comparison type (separated by a semi-colon). The table below demonstrates this, showing all three of the rule comparison types.

[%HZT_QUANTITY;NUM]          # Use the total NUMber of items ordered.
[%HZE_BILL_CITY;STR]         # Use the STRing representing the shopper's city.
[%HZE_SHIP_POSTAL_CODE;ZIP]  # Use the ZIP code of the shipping address.


Requirements have two basic forms: a "range" and a "set". A range consists of one number ("1"), a number and a plus sign ("1+") or two numbers separated by a dash ("1-2"). A set is one or more words separated by pipes ("Foo|Bar|Baz").

6            # Matches only the number 6.
1-6          # Matches a number between 1 and 6 (inclusive, 1 and 6 match).
6-           # Matches a number greater than or equal to 6.
6+           # Also matches a number >= 6.

FOO          # Matches the word "FOO" (or "foo", or "fOo"; case doesn't matter.)
FOO|BAR      # Matches the word "FOO" or "BAR".


Actions are basically numbers with some "bookend" characters which tell Hazel how to behave when a rule passes. You know what a number is. Now let me introduce the "bookends", and how Hazel interprets them.

If an action begins with an underscore ("_"), then the relevant total (shipping in shipping rules, surcharge in surcharge rules, etc.) computed up to that point is reset to zero.

The initial underscore is optional. It can be followed by three other characters.

A plus sign ("+") tells Hazel to add the given number to the running total. An "x" tells her to multiply the running total by that number. (Note you can use "x" to divide by using a decimal in your number.)

If an action ends with an underscore ("_"), Hazel stops reading the rules file.

x2           # Multiply by 2.
+2.00        # Add 2. (Probably dollars.)
x2_          # Multiply by 2 and quit parsing rules.
_2.50_       # Reset the total to 2.50 and quit.

Quirks of Individual Rules Files

Each type of rules file has its own idiosyncrasies which make its editing slightly different than the others. All follow the same general format (headers, requirements and actions), but each element may have a somewhat different behaviour.


  • Field rules are defined in the field.rules file under the rules directory in your catalog root.

  • Field rules are only cosmetically related to the other rules files. They provide a way to change how the Hazel CGI processes data submitted via HTML forms. Most users won't have to edit them. If you're interested, see the comments within the field.rules file for more information.

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