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
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.
[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 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.
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
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.
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
|=foo||If the field value is empty, set its value to text foo.|
That's all, folks!
HZML & HAM
CGI and You