field.rules

The field.rules file specifies how Hazel handles incoming data: defaults, required fields, fields which should not be saved, and so forth. Its format is fairly straightforward: square-bracketed headers introduce a series of lines which describe fields to be checked upon a certain Hazel action.

For example, the [CONFIRM] section requires the billing address and other essential information submitted during checkout. A special [ALL] section is consulted for every action.

Here's a very short field.rules which demonstrates each action.

[CONFIRM]
BILLID:+your billing identification code
SHIPID:~BILLID

[FINISH]
PAYCODE:!your payment code

[ALL]
PAYCODE:-
COMMENT:=No comment.

[MIVS]
ITEMS:;

We'll go from top to bottom, and save the special case of MIVS for last. It's not an action, but a special field handler.

Our first header applies to the Hazel "confirm" action, which generally falls right after the checkout action. As with other rules files, each field.rules line follows the simple format of key and action separated by a colon.

Hazel looks at the first character of an action to determine what she's supposed to do when she encounters a field. By default, Hazel saves every field sent to her, but requires none.

The first line here is BILLID and its action is +your billing identification code. A "+" means Hazel is to require the field, described by the following text. If a customer submits a confirm action, but hasn't filled in the BILLID field, he will receive a message such as "You didn't enter values for your billing identification code."

The next line is SHIPID. Its action is ~BILLID. Hazel takes this to mean that if no SHIPID is entered, it should use the value of BILLID.

For security reasons, not all fields passed to Hazel should be remembered by her between sessions. For example, it's not a good idea to keep credit card numbers lying around in temporary files on your web server. Here, for the finish action, we want to require a PAYCODE field, but we don't want Hazel to save it to disk. The "!" action is exactly like the "+" action, except that it prevents the field value from being saved.

The [ALL] section is checked by Hazel for every action. In our example, we have two lines. The first makes sure that PAYCODE is never saved. We require it above, but we want to make doubly sure that if it is entered at some other stage in the ordering process, we don't save it. The "-" action communicates this to Hazel.

Next we have an line which gives a default value for the COMMENT field. The "=" action introduces that default value. There aren't many cases where this makes sense. You can better provide default values using Hazel truth elements in your code.

MIVS

MIVS stands for "Multiple Input Values." Normally, when Hazel encounters more than one CGI input value with the same field name, she simply overwrites the existing value. This section allows you to gather multiple values with the same name delimited by an ASCII character.

Using the MIVS header from our working field rules example, here's a form which reproduces existing items in a hidden field, then offers more text input fields for additional items.

<form action="%HZU_FORM">
Previously chosen items:
<input type="hidden" name="ITEMS" value="%HZE_ITEMS" />
Add more items (one per field):
<input type="hidden" name="ITEMS" value="" />
<input type="hidden" name="ITEMS" value="" />
<input type="hidden" name="ITEMS" value="" />
</form>

Each entry is separated with a semicolon, as defined in the field rules. So, if someone entered FOO, BAR, and BAZ in the above text fields, after submitting, %HZE_ITEMS would have the value FOO;BAR;BAZ.

To separate values with a non-printable character, use the decimal integer representing its ASCII code. For example, "9" for a horizontal tab. To use a number as a delimiter, use ASCII codes 48-57 for digits 0-9.

All the Pickles

Here's a quick reference list of what each action character does.

+foo Requires the field (described by foo.)
~BAR If the field value is empty, use the value for field bar.
!foo Requires the field (described by foo), but does not save it to the userfile.
- Prevents the field from being saved to the userfile. Best used in an [ALL] section.
=foo If the field value is empty, set its value to text foo.

That's all, folks!


Getting Started HZML Rules Extras Advanced Reference
Walkthrough
Configuration
Products File
Order Reporting
Platforms
Upgrading
Known Problems
Actions
HZML Tokens
HZML Tags
HZML Loops
HZML & HAM
Overview
Shipping
Sales Tax
Discounts
Surcharges
Tweaking
Customization
Input Fields
Softgoods
Search Engine
Optioned Products
Plugins
Design Tips
Themes
Currency
Payment Methods
Coupons
Regular Expressions
Perl API
hazel.config
Templates
HTML Basics
CGI and You
ChangeLog

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