HZML Tokens

Pages served by Hazel may contain special words ("tokens") which are replaced with order information. The basic token starts with %HZ followed by a single letter (indicating the "namespace" from which to grab the data), then an underscore, and finally the field name of the data we want to retrieve.

We all learn best by example, right? Well, let's hope so because I'm going to throw an example at you right now. The simplest HZML token namespace to deal with in examples is %HZM. %HZM tokens correspond directly to values in your hazel.config file.

Here's some sample text using %HZM tokens.

<p>Our store name is %HZM_STORE_NAME.  You can reach us by phone at
%HZM_STORE_PHONE, or by email at %HZM_STORE_EMAIL.</p>

In my sample store, that text (after being processed by Hazel) would yield this result:

<p>Our store name is Swank Products Limited.  You can reach us by phone at
585/232-5670, or by email at quinn@netsville.com.</p>

See what happened? The %HZM bits were replaced with information from my hazel.config file. All HZML tokens work basically the same way, except the M might be a one-letter code indicating some other namespace of special token function, and the STORE_NAME and other indentifiers indicate other data to retrieve.

Here's a full list of each type of %HZ token, along with a description of each.

HZML Prefix		Also Known As	Notes	Description
%HZD		(D)ate	Dynamic	%HZD is a special token class used to display the current date and time. See its section below for details.
%HZE		Shopper (E)ntered Data	Vsettable (H4)	%HZE tokens correspond to data entered by the shopper. They're found in abundance in the checkout templates, used to insert previously entered values into textfields for billing and shipping information.
%HZG		(G)roup Totals	Dynamic	Similiar to %HZQ, an %HZG token is replaced with a quantity selected by the shopper. However, in the case of %HZG, we want the quantity of all items with a certain value in their GROUP field in the products file. For example, %HZG_BOOKS would be replaced by Hazel with the cumulative quantity of all items selected by the current shopper which have a GROUP:BOOKS line in their products file record.
%HZH		(H)azel Messages/Data	Vsettable (H4)	%HZH tokens allow access to various bits of data during a Hazel session. Most common is %HZH_MESSAGE, used in error and message templates to display the point of order Hazel is trying to communicate. %HZH tokens are also used to represent looped data in many of Hazel's word loops.
%HZI		Product (I)nformation	Only meaningful within some product context	In the beginning, there was a need to display a list of the products selected by the shopper. To fulfill this basic requirement of the "shopping cart" paradigm, Hazel's creators constructed a products loop within which the catalog designer could insert data to be repeated for each item in the cart. Product file fields could be referenced by %HZI tokens. For more information, see the documentation on Hazel's products loops.
%HZM		(M)isc. Config Data	Vsettable (H4)	Originally, %HZM tokens did double-duty as hazel.config information and anything else Hazel wanted to expose to you during a session. Somewhere around Hazel 3.4xx, all "miscellaneous" info was moved to %HZH tokens, and %HZM tokens now refer only to hazel.config file field values.
%HZQ		(Q)uantity Selected	Dynamic, Vsettable (H4)	%HZQ tokens provide an easy way to grab the quantity selected of a certain SKUID. For example, %HZQ_FOO would be replaced by Hazel with the quantity of SKUID FOO selected by the current shopper.
%HZS		(S)elected (S)ums	Dynamic	%HZS tokens provide a powerful method of querying items selected by the shopper for various conditions. They're described in their own section below.
%HZT		Selected Order (T)otals	Dynamic	Calculated totals for the current order are displayed using %HZT tokens.
%HZU		(U)RL	Derived From Hazel.config Values	%HZU tokens output URL (Uniform Resource Locators, web addresses) associated with your store. For example, %HZU_MAIN would be replaced with the full URL to Hazel. When a store switches to secure mode, its %HZU tokens automagically switch with it. To access a particular secure or nonsecure URL, merely append _SECURE or _NONSECURE to the usual token. For example, %HZU_MAIN_NONSECURE will return the nonsecure URL (based on the HTTP_CGI_BIN in your hazel.config file) regardless of whether or not the current page was served securely.
%HZV		(V)ariables	Vsettable	The "V" in %HZV stands for "variables." %HZV tokens contain variable information for a particular session. They can be set using the Hazel-Vset HZML tag, and many other tags allow you to store the result of their machinations into a particular %HZV token.

Many tokens simply fetch data keyed by a certain name from a certain place in Hazel's innards. Others compute their data on the fly, and any token can use slightly twisted syntax to have its data massaged before output. Following is a closer look at some of these features.

Total Tokens

Here are the standard "total" tokens in Hazel's %HZT namespace. The "type" is either a number (eg. 4), decimal (a floating point number, eg. 4.14), or currency (eg. 4.14 is four dollars and fourteen cents.)

These "discountable" tokens enumerate items selected by the shopper which are to be included in a whole-order discount. They may be subject to other discounts (eg. per-item discounts), but should not be included in the standard total headers for a discount.rules file.

These "UHS" tokens enumerate items which, when Hazel begins to process a shipping rules file, have not handled their own shipping. Generally this means that a product does not have a SHIPPING field defined.

Date Tokens

Introduced as of Hazel version 3.394, the %HZD class of tokens allow you to insert a date into your document.

The syntax of the token is %HZD_wXu, where w is either a "P" or an "F" (for past or future relative to the current date), X is a number, and u is a one-letter code representing a unit of time: (S)econds, (M)inutes, (H)ours, (D)ays, (L)unar months, and (Y)ears. Lunar months are named that way because the "M" was taken by minutes. They average 30.5 days.

The format is a big hairy, so we'll just provide some examples here with the output they'd produce.

<!-- All examples assume time is 1:43PM on Monday, May 14 2001. -->
%HZD_P0D is 0 days in the past, or right now, which is 20010514.
%HZD_F1Y is 1 year in the future, or 20020514.
%HZD_P1H is 1 hour in the past, or 20010515124300.

The output format is YYYYLLDDHHMMSS if a unit less than days is given, and YYYYLLDD if a unit of a day or greater is used.

For more control over output format, you can use the Hazel-Date HZML tag instead.

Fixed-Width Tokens

Some text-based templates (such as the invoice e-mail templates) require special formatting to appear attractive when viewed by yourself or the customer without the aid of HTML markup. HZML tokens can be formatted to a fixed width by prefixing their token names with a special sequence of three characters. xxL will format a token xx characters to the left. xxR will format it xx characters to the right.

You must always use two characters for the width, even if it is less than 10. Prefix with zero if necessary. For example, use '08' for an 8 character width.

For example, if you wanted your order totals to line up, you could use %HZT_12R_TAX, %HZT_12R_SHIPPING, and %HZT_12R_ORDER to fix them all at 12 characters, flushed to the right.

Unlike many other HZML elements, the case of the "R" or "L" in a fixed width token does matter. If uppercase, the text is snipped off at the given length at all times. If lowercase and the text is longer than the given length, Hazel allows the full width. There were some bugs in this behaviour prior to Hazel 3.348. As always, if it doesn't work as it should, try downloading a newer Hazel.

Complex Tokens

What if you want to reference a token with a name dependent on another token's value? What if your token name contains characters Hazel normally doesn't regard as valid within an HZML token?

SOL? Nope! In these cases, you can use Hazel's complex tokens. A complex token's format is very simple. Here are a few examples.

%HZ{M_STORE_NAME}
%HZ{E_INITIALS_ %HZI_SKUID}
%HZ{S_PRICE ~ NAME : SPOON}

The first example is simplest. A complex token holds its "meat" within the curly brackets. Spaces are ignored. %HZ{M_STORE_NAME} is replaced with the same value as %HZM_STORE_NAME.

Well, almost the same. The primary side-effect of using complex tokens is that all newlines are replaced with spaces. If you're including an HZML token in, for example, a form input tag's value attribute, it's a good idea to use a curly-braced complex token.

As of Hazel 3.476/3.9AT, the following substitutions are made by default in a complex token:

As of Hazel 4.024 (H4+ only), using %HZ{'...'} disables quoting any characters within a complex token, and %HZ{"..."} forces quoting. Specifying RAW_COMPLEX_TOKENS:1 in hazel.config turns off the default behaviour of quoting complex tokens.

One more caveat: complex tokens cannot span multiple lines in a file. The closing bracket must be on the same line as the opening bracket, or it won't be rendered by Hazel.

The second example better illustrates what can be done with complex tokens. If it were used within a selected loop, it would be replaced with the value of a custom field offered to the customer. For this example, it's custom initials for some clothing item. The actual would be stored according to the SKUID of each ordered item. For example, INITIALS_FOOCAP would be the field name describing initials for someone's FOOCAP.

The third example leads us to another token type: the "sum" token.

Sum Tokens

Sum tokens can be used to tally up field values of products selected by the shopper. Here are a few examples.

%HZ{ S_ FOO  }
%HZ{ S_ FOO? }
        Returns sum of all FOO product field values for all selected items.
        The question mark is optional.  In the first case, you could skip
        the complex token and just use %HZS_FOO.

%HZ{ S_ FOO ~ BAR }
%HZ{ S_ FOO ~ BAR = BAZ }
        Returns sum of all FOO product field values for all selected items,
        iff (if and only if) field BAR has a true value (in the first case)
        or field BAR has a value equal to BAZ (in the second).  (`=' could
        be any search comparison character.)

%HZ{ S_ * ~ BAR }
        By using an asterisk instead of a fieldname, the sum token will
        simply return the quantity of items ordered with a true BAR value.

%HZ{ S_ FOO ! BAR }
%HZ{ S_ FOO ! BAR = BAZ }
        As above, but reversed logic.  Sum if BAR does not exist or
        does not satisfy the comparison expression.

Many of the %HZS examples above are available only in Hazel 3.201 or higher. Yes, that's the first version after our last stable 3.2 release. See the updates section for information on getting a later build of Hazel.

As with any complex token, you can use as much whitespace as you like within a sum token. Readability rules.

By default, sums are returned as floating point numbers such as 1.22. If you'd rather they be round numbers, use the RoundSums Hazel-Tweak as detailed in the HZML tags documentation.