The custom.rules rules file allows you to modify the wording of error messages and certain other values. For example, you could create themes for different written languages with a custom.rules file in each containing messages translated for that audience.
The custom rules bare a passing resemblance to the other rules files. The hash mark (#) still denotes a comment, and words enclosed in square brackets ([FOO]) act as headers to mark off sections. In most sections, lines consist of a key and a value separated by a colon, where the key identifies some text to be replaced with the value on the right side of the colon.
We'll go through each section and explain its use in a Hazel catalog.
LOOPNAMES section allows you to specify pretty, easily comprehended names for certain Hazel identifiers. It is so named because it takes these names directly from the contents of your hazel-cat/loops files.
Let's use payment_methods.txt as an example. Say it contains the following list of payment methods supported by the catalog.
credit_card;Credit Card printout;Printed Order Form cod;COD Order phone;Telephone Order
In Hazel's standard checkout templates, she reads the loop file and builds a drop-down selection of payment methods from its contents. Because computers traditionally require a different style of identifiers than humans, we have the standard names on the left and the "human" names on the right.
If a shopper chooses the method labeled as "Credit Card" from the drop-down and submits the form, Hazel's
%HZE_PAYMENT_METHOD is given the "credit_card" value, which Hazel uses to pick a template to display from her hazel-cat/templates/payment directory.
In this case, Hazel reads credit_card.html. So, when the shopper submits the checkout page with his chosen payment method, Hazel checks to make sure all his input is proper, then presents him with that credit card payment template, which the shopper then fills out, and submits his order.
Within the shopper's email receipt automatically sent by Hazel, it would be useful to remind the shopper what payment method he has chosen. However, Hazel has only remembered the rigid "credit_card" value, which isn't very pretty.
Finally, we come to the point of this section-- loopnames!
Instead of using
%HZE_PAYMENT_METHOD in your shopper_invoice.txt template, you can use
%HZE_PAYMENT_METHOD_NAME. Hazel sees this token, first checks to make sure there is no
PAYMENT_METHOD_NAME value already defined, and if not, she recognizes it ends in
_NAME and searches for the initial
PAYMENT_METHOD portion of the token name in the loopnames section of your hazel-cat/rules/custom.rules, recreated below.
[LOOPNAMES] SHIP_METHOD:ship_methods.txt PAYMENT_METHOD:payment_methods.txt BILL_COUNTRY:countries.txt BILL_STATE:states.txt SHIP_COUNTRY:countries.txt SHIP_STATE:states.txt CREDIT_TYPE:credit_types.txt [/LOOPNAMES]
She sees that it is associated with the payment_methods.txt file. Next, she fetches the value known for
%HZE_PAYMENT_METHOD, which is
credit_card, and looks that up in the payment_methods.txt file (with which we started this example), and sees that the value
credit_card is associated with the word "Credit Card", so she replaces
%HZE_PAYMENT_METHOD_NAME with the word "Credit Card", and the customer is presented with a pretty payment method name.
It all seems horribly complicated, but in reality it happens in a few milliseconds on files Hazel caches to avoid re-reading later, and it's very simple and elegant. Trust me, it is. Really. In fact, to reinforce my assertion, we'll quickly go over the way it used to be done, with the Names section...
LOOPNAMES, the way to present "pretty" names for standard identifiers was to list each permutation under a
NAMES header in the field.rules file. When custom.rules came about, it became their preferred home (and where you should place the header now.)
Name entries describe the values of particular fields. Here's an example.
[NAMES] TAX_REGION_NY:New York State TAX_REGION_PA:Pennsylvania SHIP_REGION_NORAM:USA, Canada or Mexico SHIP_REGION_OTHER:Other
We'll skimp on the backstory, as the process of determining the "pretty" name of a value is covered in the previous section. In a nutshell, if Hazel runs across an undefined
%HZE HZML token ending in
_NAME, she grabs the value of the pre-name portion, looks it up under the
NAMES header, and uses that key's value as the token value.
For example, if someone chose a
TAX_REGION of "NY", the full "New York State" name shown above could be accessed via the
MESSAGES section is the simplest and most powerful of the custom rules sections. Each line within this section is comprised of a key identifying a Hazel output message, a colon, and then a template for that message. If a line does not exist for a particular message, Hazel uses an internal default. Here's a short excerpt from the message section of a custom rules file:
[MESSAGES] ## Message shown (via the message template) when the cart is emptied. CART_EMPTIED: Your cart has been emptied. ## Shown when MINIMUM_ORDER is not reached by checkout. MINORDER:Sorry, but we require a minimum order of $%HZM_MINIMUM_ORDER. [/MESSAGES]
The following table lists some of the messages one is likely to use in a Hazel store. "Message Name" would be the left-side key above. "Default Template" is the default Hazel template used to frame the message, available within via the
%HZH_MESSAGE token. If you create a templates/custom/message_name.html file (eg. cart_emptied.html), it will be used instead, allowing you to further customize the message output.
There are more, but they would probably blow your mind. If you have a specific message you'd like to change, contact the hazel-talk list. The authors should be able to help you!
That's all, folks!
HZML & HAM
CGI and You