This page is an example of Hazel's "HZML" (HTML with some extra stuff understood only by Hazel). How it appears in your browser, after being interpreted by Hazel, is not how it appears on your web server's disk drive. The "raw" source for the file is located on your server at the following location:
%HZM_DOC_DIR/%HZM_START_PAGEIf the text above displays as %HZM_DOC_DIR/%HZM_START_PAGE, this page was not served by Hazel. Instead of accessing this page directly, use the URL for your Hazel CGI.
Linking to your Hazel catalog is simple. Just add an HREF on your website's homepage pointing to your Hazel CGI. For example:
<a href="%HZU_MAIN">Enter our catalog!</a>Given a basic link such as the above, Hazel will create a user file for the new shopper (to hold items selected and personal information entered) and serve the start page to them. It's important to know the difference between accessing a page directly and accessing it served through (or "rendered by") Hazel. This sample catalog uses Hazel's "HZML". That's why your catalog's URL is shown above, without your ever having to place it in the HTML. Hazel recognized the %HZ tokens and replaced them with information from your hazel.config file.
Click this serve action to see what this page would look like if you hadn't served it through Hazel. Use your back button to get back to this page.
No existing web browser understands HZML. Hazel interprets the special tokens and tags, translating the page into standard HTML which a browser can understand.
The rest of this document contains some examples of HZML. The code used to "render" each example is printed in red and blue font above the example itself. The blue indicates something you'll probably want to change when using the example in your own catalog.
%HZU_ACTION is a shorthand version of the URL to your Hazel CGI. It's used liberally in the examples. Here's an introductory URL which would bring up the view template. Remember that HZML code is in red font.
%HZU_ACTION=VIEW %HZU_ACTION=VIEWAs you can see, %HZU_ACTION is replaced with the URL of your Hazel CGI, plus a field indicating the current shopper's client ID, plus the name of the next field -- "action" -- which tells Hazel what it is you want her to do. You need only supply the '=' sign plus the action, and any fields required by Hazel to complete the action.
You should never include a client-id in a URL to Hazel. Doing so will force everyone following that link to use the same "shopping cart". That's bad. Leave it to Hazel to include the client-id.
HZML, besides being cool, makes it easier to maintain a happy catalog. Using %HZU_ACTION to serve your catalog pages means never losing track of the client, whether or not they use cookies. In the business, we call that "preserving state".
Besides preserving state, HZML allows for easy maintenance. If all of your URL are represented as HZML tokens (such as %HZU_ACTION, %HZU_DOC_BASE), then moving your catalog to a new server is as simple as copying the files and changing your config file to reflect the new location.
HZML allows you to publish a "dynamic" catalog. Your HZML pages are merely skeeltons upon which Hazel drapes the viscera of product content. Don't change your web pages every time you change your product information. Change the price or description in the products file and let Hazel read it through one of her loops.
If HZML is viewed without first going through your Hazel CGI, your browser will not understand it. Images will be broken, chunks of your page will be displayed incorrectly (or not at all), and links will go nowhere. This can be bad when someone happens to stumble across your "raw" "naked" page from a search engine. The simplest solution is to include a line at the top of all your heavily "HZMLified" pages which directs the browser to the proper catalog URL. For example:
<A HREF="%HZU_MAIN"> Click here if you reached this page through a search engine and are having trouble with broken links and/or images.</A>Note that you must use the full URL above -- you can't use %HZU_MAIN, since the message is intended for people who reached the page outside of Hazel.
This example demonstrates how to serve any page within Hazel's document directory using the %HZU_ACTION HZML token.
<a href="%HZU_ACTION=serve&item=%HZM_START_PAGE">Click here to serve %HZM_START_PAGE.</a>
Click here to serve %HZM_START_PAGE.Here's how to do it without using HZML.
<a href="%HZU_MAIN?action=serve&item=%HZM_START_PAGE"> Click here to serve %HZM_START_PAGE. </a>
Click here to serve %HZM_START_PAGE.And that's the syntax for asking Hazel to do anything. Tell her what to do (the "action") and give her something to do it to, or with (the optional "item"). Hazel's just a CGI program. Tell her what to do, and she does it.
Note the difference between the two URL above. With %HZU_ACTION, the client id is inserted into the URL, ensuring that Hazel will recognize you as the same shopper when the page is served. (Regardless of whether or not you're accepting cookies.)
Of course, the whole point of a shopping cart is to keep track of the merchandise to be ordered. Therefore, the most important function is "adding an item". Here's how to do that using HZML.
<A HREF="%HZU_ACTION=ADD&ITEM=SAMP003">Click here to add a Foo.</A>
Click here to add a Foo.The example above uses the SAMP003 product from the sample catalog, which you may now know as "Foo". Thus, you add a product by sending Hazel an "add" action with an "item" of the desired addition's SKUID.
Hazel utilizes a little-used featuree of the HTTP protocol to allow you to add items "quietly". That is, without the browser loading a new page. This definitely works with Netscape, but may not work for all browsers -- particularly older versions of Microsoft's Internet Explorer. It isn't a "new" or "non-standard" feature; it's been around for nearly as long as the web itself. Some browsers just don't support it.
<a href="%HZU_ACTION=ADD_QUIET&item=SAMP003">Click here to quietly add a Foo...</a>
Click here to quietly add a Foo...
<A HREF="%HZU_ACTION=view">...and here to view it in your shopping cart.</a>
...and here to view it in your shopping cart.If a browser doesn't support quiet add (an HTTP response 204, AKA "No Content"), Hazel will instead display a page to the effect of "your item was added."
Adding items via HTML links (as in the examples above) is a simple way of getting them into the shopping cart. If the shopper wants to add more than one, they can click the link multiple times, or just enter a number into the forms on your checkout pages.
However, if you'd like to allow the shopper to enter a desired quantity right from the product page, you can use a full-fledged HTML form. The example below demonstrates how to do this.
Regardless of whether you use a form or a link to communicate with Hazel, you're just sending her information. A link includes all the information in the URL without giving the user a chance to edit it. A form sends the information through other means, and gives the user some control over what is sent.
Before wasting any frustration wondering why clicking one of the above buttons gave you a "Still Looking?" screen, remember to enter a quantity in the input box.
Well, there you have it -- your introduction to Hazel. With this sample page and our online documentation (don't forget the walkthrough!), you should be able to create a unique and attractive storefront. When your work is done, display your "Powered By Hazel" badge with pride -- you've earned it!