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: Design

Creating a Hazel catalog can seem like a daunting task if you're not the kind of person whose mind is aroused by the prospect of twiddling with HTML. It doesn't have to be difficult, and you too can be one of those pre-verted twiddlers with a little patience and a short read. Start reading!

The First Link

Ready to link your catalog to your homepage? All communication to Hazel goes through the URL to her CGI on your system. For demonstrative purposes, we'll use the URL below. You'll use the actual web address of your installed Hazel CGI.

By default, without any specific directions, she'll serve up your start page. That is, she'll read in the file corresponding to the START_PAGE field value in your hazel.config, located in the directory specified by the DOC_DIR field value.

The start page included with the distribution can be modified by you to create a simple working catalog--all products listed nice and neat and links to click to buy them. It can be further modified (and other pages added, served through Hazel) to construct an impressive showcase for your store. HZML is a wonderful thing, but not everybody wants to bother with it. Others might already have all their catalog pages built and don't want to switch them all to be dynamically generated by Hazel just yet.

That's OK! For those who want a quick start, there's really only two Hazel actions you need to know. Actions are instructions to Hazel. They sometimes include an item which further describes what you'd like her to do. (Sort of the direct object to the action's verb.)

Unless your interest in Hazel is purely academic, you'll probably want to add items to the cart. Using our sample URL above (which you'll replace with your own), and a sample SKUID (product code in your products file) of "FOO", we'll add a FOO to our cart:

By clicking such a link, you're asking Hazel to remember that you want to buy a FOO. She adds it to the data in your user file, then displays her view template to review what you've ordered so far.

There. That's easy, isn't it?

The second link you'll want to know is a checkout action. This should be interspersed throughout your site to allow people to "view their cart" at any time:

You say, "Yumpin' Yiminy, that's damn simple!" Yes, Dorothy, it is. You can replace "checkout" with "view" for a simpler view of the cart (same one you get when you add an item), but jumping directly to "checkout" shows the same data plus input for billing and shipping info, which is arguably more efficient.

Remember that your interaction with Hazel is, at the core, just a bunch of links (or forms). You can wrap the links above in a simple <a href="http://blahblahblah">Checkout</a>, or you can go hog wild with images and Javascript mouseovers and lions and tigers and bears--oh my!

Just don't freak out on me, OK?

Dissecting a Link and Imaging Forms

The beginner examples above use only links, but they're not ordinary links referencing a file--they're actually form submissions! You've been submitting forms and you didn't even know it. Normally there's a lot of user input involved with a form, and it is "posted" to the server. Once submitted, all you see in the web address window of your browser is a nice clean URL pointing to the script which handled the request. With the links above, we've included all the form data into the URL after the question mark, since we already know everything about the request. You know what you're adding, and if the shopper knows what's good for them, they'll click your link and add it!

Using full-fledged forms with user-input allows you to provide the shopper more options, such as choosing a particular product from a drop-down list of related ones, choosing a color or size, specifying a quantity right at the point of purchase, and much more.

Sending the info entered into a form to a CGI program for processing is done by clicking its submit button, so let's meet that little bugger right now:

Ugly guy, isn't he? You have no control over how a standard submit button is going to look. There's no easy way to make sure all your submits are the same size so they line up nice and pretty, and that can be important to anal site designers (like me!)

A little-known trick of HTML is to use something called an "image submit". It's the same as a normal submit INPUT tag, but the type is IMAGE rather than SUBMIT, and you can add any attributes valid for a standard IMG tag...

<form action="#" method="POST">
<input type="image" name="FOO" src="images/donclick.gif" border=0>

And now we have...

Isn't that just darling? So grunge chic? For Hazel, you'd give the form a valid action and add a name like SUBMIT_ACTION_VIEW to make the button actually do something useful, unlike the pointless slacker above.

Specifying Quantities With Forms

Hazel interprets certain form fields as special instructions. For example, any field beginning with PRODUCT_ is taken to be a request to add a product to the shopper's cart. For example, a field named PRODUCT_FOO with a value of "2" would tell Hazel that the shopper wants two FOO. You could provide an input box for this purpose...

<input type="text" size=3 name="Product_FOO">

That would work fine. Usually. The problem is that the input box is going to be blank by default. So, if the shopper has previously chosen a FOO, revisits this page, and submits the form without changing the input box, he's just inadvertently cleared his FOO. He has no FOO. He is now FOO-less.

If you're serving your catalog pages through Hazel or are interested in doing so, read on. Otherwise, you can skip ahead to the next session. The HZML code below requires Hazel to read the file and interpret it.

We could fix this with the %HZQ token...

<input type="text" size=3 name="Product_FOO" value="%HZQ_FOO">

%HZQ_FOO will be replaced with the previously selected quantity entered by the user. His FOO is safe!

Choosing Multiple Products (drop-downs and radios)

You learned above how a field PRODUCT_FOO tells Hazel to add its value to the shopper's cart. There's one limitation to this method-- the SKUID is embedded in the field name. If you wanted to use this syntax with form tags such as SELECT lists and RADIO buttons, you could only modify the quantity. The SKUID is embedded in the field name, and the value is always a quantity.

There's another special field Hazel recognizes-- PRODUCT. That's right, just "PRODUCT". No underscore, and no SKUID at the end. The value of this field is the SKUID of a product. Let's go straight to the example...

<select name="Product">
<option value="">-- Pick a color, jive turkey! --
<option value="FOO_RED">Add a Red Foo
<option value="FOO_WHITE">Add a White Foo
<option value="FOO_BLUE">Add a Blue Foo

If the PRODUCT field is empty, nothing is added. So, with an initial default choice of "", nothing is added. If the shopper chooses any of the others, however, those respective products will be added to his shopping cart with a quantity of 1.

The only drawback with using the PRODUCT field is that a quantity of 1 is always added, regardless of any previous quantity. So, if your shopper went to the trouble of indicating a quantity a "4" FOO_BLOO earlier, selecting it above is going to set the quantity back to a "1".

Product Squares

The following section requires HZML, which requires the page in which it is contained to be served by Hazel.

Want to lay out your products into (for example) three rows of three each? Not a problem with Hazel. Use any products loop (we'll use query below to slurp in all products), then use Hazel-Choice and the Mod attribute to close a table row and re-open a new one every X products.


<Hazel-Loop Type="Query" Spec="+PRICE>0">

<!-- Thus begin the guts of the loop. -->

<Hazel-Choice token="%HZH_PRODUCT_LOOP_COUNT" Mod=3 False="</tr><tr>">

<!-- Thus end the guts of the loop. -->



Of course, you can insert any %HZI or other HZML tokens into that loop, including references to images, prices, and links to add products.

If the above trick doesn't work, try upgrading your Hazel. Older versions of Hazel used %HZM_PRODUCT_LOOP_COUNT.

You can, of course, place the guts of that loop into any other loop, including a matches loop in your search matches template. Use your sweet and sassy noodle, grasshopper.

This Is the End?

This is the end for now, beautiful friend, but more design tips are sure to be added as you, the Hazel owner, call to us with wailing and gnashing of teeth, wrothful over missing documentation. Drop us a line at with suggestions, or climb into one of our virtual nooks through our Netsville contact page.

Getting Started HZML Rules Extras Advanced Reference
Products File
Order Reporting
Known Problems
HZML Tokens
HZML Loops
Sales Tax
Input Fields
Search Engine
Optioned Products
Design Tips
Payment Methods
Regular Expressions
Perl API
HTML Basics
CGI and You

Hazel Home - Help Contents - Searchable Knowledge Base - Live Technical Support

black line
corner black line corner