custom.rules

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

The 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...

Names

Before 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 %HZE_TAX_REGION_NAME token.

Messages

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.

Message NameDefault TemplateDefault ValueAvailable Substitutions
CLOSEDmessageSorry, but our store is currently closed. Contact us at <a href="mailto:%HZM_STORE_EMAIL">%HZM_STORE_EMAIL</a> if you have any questions.HZML
CART_EMPTIEDmessageYour cart has been emptied.HZML
CLIENT_FORGOTTENmessageYou have been forgotten.HZML
MINQ_ELEMENTn/a%HZI_NAME (min. %HZI_MINQ)HZML; %HZI tokens operate on each product with less than the MINQ selected
MINQ_MESSAGEerrorA minimum quantity (indicated in parentheses) is required for the following items: %f. Quantities for those items have been increased to meet the required minimum.%f: all of the items with less than MINQ selected, built from above
MAXQ_ELEMENTn/a%HZI_NAME (max. %HZI_MAXQ)HZML; %HZI tokens operate on each product with less than the MAXQ selected
MAXQ_MESSAGEerrorYou may order no more than the parenthetical quantity for the following items: %f. Quantities for those items have been decreased to fall within the allowed range.%f: all of the items with more than MAXQ selected, built from above
MINORDERerrorSorry, but we require a minimum order of $%HZM_MINIMUM_ORDER.HZML
MAXORDERerrorSorry, but we don't allow online orders over $%HZM_MAXIMUM_ORDER. Please remove some items from your cart, or call us at %HZM_STORE_PHONE to complete your order.HZML
FIELDS_MISSINGn/aYou didn't enter value(s) for %f.%f: a list of input fields with missing values
FIELDS_INVALIDn/aYou entered invalid value(s) for %f.%f: a list of input fields with missing values
CCN_INVALIDn/aYou entered a credit card number which does not appear to be valid.none
CCD_EXPIREDn/aYou entered a credit card expiration month and year in the past.none
FIELDS_TRY_AGAINn/aPlease go back and try again.none
INPUT_ERRORerrorNot a message per se, but the templates/custom/input_error.html file displays the result of the input errors above.
SEARCH_SPEC_MISSINGerrorNo search specification was given. Please go back and try again.HZML

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!


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