corner black line corner
black line
the Hazel Logo Hazel Enterprise: The Internet Merchandising System The Netsville Logo
start red bar Home News Info Features Examples Purchase Support Contact Us end red bar
Documentation: 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. Special characters used by scripts are automatically converted into html entities before they can be accessed. This is to prevent the possibility of cross-site scripting attacks. In order to get the raw data as the customer entered it use the corresponding %HZR value.

%HZR

(R)aw Shopper Entered Data Dynamic (H4)
Introduced as of Hazel version 4.148

For each %HZE variable set there is a corresponding %HZR variable set that contains the raw shoppered entered data. %HZR values should never be used in html forms but can be useful for writing to text documents or if you need to access the text exactly as the customer entered it.

%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.)

TokenTypeDescription

%HZT_SKUID

NumberThe number of unique SKUID included in the order.

%HZT_QUANTITY

NumberThe total quantity of items ordered.

%HZT_WEIGHT

DecimalThe total of all WEIGHT values for products ordered, multiplied by the quanity selected.

%HZT_DISCOUNT

CurrencyThe total discount applied to the order.

%HZT_UNDISCOUNTED

CurrencyThe total price of all products before discounts are applied.

%HZT_MERCH

CurrencyThe total price of all products ordered after discounts are applied.

%HZT_SUBTOTAL

CurrencyA synonym for %HZT_MERCH.

%HZT_TAXABLE

CurrencyThe total post-discount price of all products ordered which are considered taxable (ie. do not have a false TAX field value.) If TAX_SUBTOTAL is set in hazel.config, the subtotal is used rather than this amount.

%HZT_TAX

CurrencyThe final line-item tax for the order.

%HZT_SHIPPING

CurrencyThe final line-item shipping charge.

%HZT_SURCHARGE

CurrencyThe final line-item surcharge.

%HZT_CREDIT

CurrencyThe final line-item credit to the order.

%HZT_ORDER

CurrencyThe final total of the order.

%HZT_UNCREDITED

CurrencyThe pre-CREDIT total for the order.

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.

TokenTypeDescription

%HZT_DISCOUNTABLE_SKUID

NumberThe number of unique SKUID eligible for a whole-order discount.

%HZT_DISCOUNTABLE_QUANTITY

NumberThe total quantity of items eligible for a whole-order discount.

%HZT_DISCOUNTABLE_WEIGHT

DecimalThe total weight of items eligible for a whole-order discount.

%HZT_DISCOUNTABLE_PRICE

CurrencyThe total price of items eligible for a whole-order discount.

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.

TokenTypeDescription

%HZT_UHS_SKUID

NumberThe number of unique SKUID which should be handled by a shipping rules file.

%HZT_UHS_QUANTITY

NumberThe total quantity of items which should be handled by a shipping rules file.

%HZT_UHS_WEIGHT

DecimalThe total weight of items which should be handled by a shipping rules file.

%HZT_UHS_PRICE

CurrencyThe total price of items which should be handled by a shipping rules file.

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:

Character(s)Replacement
&&amp;
"&quot;
'&apos;
<&lt;
>&gt;
newline (\n)space
return (\r)space
tab (\t)space

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.


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

black line
corner black line corner