The Hazel Perl API

The Hazel API allows you to influence Hazel's process by writing scripts which she will consult at certain points during her execution.

This document is oriented towards those programming in Perl, but the "talking back to Hazel" section can be consulted for the syntax of communication back to Hazel from scripts she calls as hooks.

The Hazel API is available only on Unix-based versions of Hazel. None of the MY_* scripts will work on Windows NT.

MY Scripts

For a complete list of "MY" scripts, see the config file appendix. It's in alphabetical order, so just scroll down to the M's. The points at which each script is called are described. The script name indicates an executable file in the same directory as your hazel.cgi. (To be exact, in the directory specified by your CGI_DIR.)

If you want your script to be called by Hazel, you have to enter its name as the value of one of the recognized MY_* fields.

Hazel.pm

MY scripts can be written in any language, but the only interface library we supply is Hazel.pm, written in Perl. The latest Hazel.pm is available in our perl web updates directory.

For a usage synopsis and brief "man page", type `perldoc Hazel' from your Unix command line after downloading Hazel.pm above.

Talking Back to Hazel

You should never get sassy with Hazel, but she's delighted to take your advice and execute your polite commands. In the context of an API script, you communicate with Hazel simply by printing lines of a particular syntax. Lines which don't match that syntax are ignored.

Here is an example of output from a Hazel API script, and how Hazel would interpret each line.

## Use %HZE to set shopper information.  In this case,
## mess with the shopper's head by resetting his name.
%HZE_FNAME: Herman

## Use %HZH_NOTE to add a note to the order, accessed
## by Hazel's "notes" loop.
%HZH_NOTE: You've got note.

## Use it again to add another note.
%HZH_NOTE: You've got more note.

## Use %HZI to set product information in a MY_PRODUCTS
## or MY_PRODUCTS_TWEAK script.  To begin describing a
## product, send an %HZI_SKUID line, followed by lines
## assigning field values for that product.
%HZI_SKUID: FOO
%HZI_NAME: New Foo Name
%HZI_DESC: A new description for FOO.
%HZI_PRICE: 10.00

## For MY_DISCOUNT scripts, use %HZT_DISCOUNT to set
## a static discount amount...
%HZT_DISCOUNT: 10.00

## ...or %HZT_DISCOUNT_RATE to set a percentage discount
## for the entire order:
%HZT_DISCOUNT_RATE: 0.42

## For a MY_TAX script, use %HZT_TAX to set the sales
## tax amount for the order...
%HZT_TAX: 8.00

## ...or %HZT_TAX_RATE to set the rate:
%HZT_TAX_RATE: 0.085

## For a MY_SHIPPING script, use %HZT_SHIPPING to set
## the total shipping charge:
%HZT_SHIPPING: 19.71

## For a MY_CREDIT script, use %HZT_CREDIT to add a
## credit to the order:
%HZT_CREDIT: 8.88

## Use %HZQ to set the selected quantity of a particular
## item within a MY_FILTER_CART script.  Using %HZQ in
## other scripts could result in incorrect order totals.
%HZQ_FOO: 42

## The `!LOG' directive forces Hazel to log its value
## to an existing hazel.log file.  If a hazel.log file
## does not exist, it does nothing.
!LOG: Hi, mom!
## If you set the API_LOG hazel.config file field, all
## output from an API script will be appended to a
## hazel.bug (note different name) file if it exists.

## The other `!' commands force Hazel to stop dead and
## print a message.  In order for any of the following
## to work, the current Hazel action must be contained
## in a semicolon-delimited list in the API_DIE_ACTIONS
## hazel.config file field value.

## A !DIE command causes Hazel to stop execution immediately
## and display its value as %HZH_MESSAGE in her `error'
## template.  The shopper's user file is not written, thus
## any new or changed data is discarded.
!DIE:You killed me!

## A !MSG command causes Hazel to stop execution immediately
## and display its value as %HZH_MESSAGE in her `message'
## template.  The shopper's user file is written as normal.
!MSG:False alarm.

## A !CROAK command causes Hazel to stop execution immediately
## and display the custom.rules message keyed by its value
## as %HZH_MESSAGE in her `error'	template.  OR, if a
## hazel-cat/templates/custom/code.html template exists,
## display that template.  Otherwise, same as !DIE command.
!CROAK:stylish_croak
## Serve hazel-cat/templates/custom/stylish_croak.html or
## error.html with %HZH_MESSAGE as the STYLISH_CROAK
## message defined in hazel-cat/rules/custom.rules.

## The !WHINE command is to !MSG as !CROAK is to !DIE.
!WHINE:stylish_whine
## Serve hazel-cat/templates/custom/stylish_whine.html or
## error.html with %HZH_MESSAGE as the STYLISH_WHINE
## message defined in hazel-cat/rules/custom.rules.
      

When printing the %HZ fields in Perl, be sure to escape the percent sign with a backslash. Otherwise, Perl may interpret it as a hash value to be interpolated into the string.

Examples

Here's a Perl example which sets the tax rate for an order if the billing postal code begins with "146".

## my-tax.pl
##    Set MY_TAX:my-tax.pl in hazel.config to activate.

use Hazel;
$session = new Hazel(@ARGV);

$zipcode = $session->get_query_value('BILL_POSTAL_CODE');
if ($zipcode =~ m/^146/) {
	print "\%HZT_TAX_RATE: 0.08\n";
	print "\%HZH_NOTE: 8% sales tax for Rochester, NY.\n";
}

exit;
	

Of course, it would have been simpler just to use the sales tax rules.

Fin

That's all for now. If you have further questions about how Hazel's API works, or would like to share your own crazy manipulations, please e-mail us at hazel@netsville.com.


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


Last modified: Wednesday, 16-Jul-2003 13:40:02 EDT