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

An action is simply the value of an HTML form field named "ACTION". Hazel interprets the value of an "ACTION" as a request to do something. Actions are sent like any HTML field. You can use a form, like so:


<form method="post" action="http://www.hazel.net/cgi-bin/hazel.cgi">
<input type="submit" name="SUBMIT_ACTION_SERVE_foo.html" value="Serve Foo">
</form>

Or you can include the information that would usually be sent by a form in the URL of a link:


<a href="http://www.hazel.net/cgi-bin/hazel.cgi?action=serve&item=foo.html">
Serve Foo</a>

Both of the examples above send the "serve" action to Hazel, and each (in its own special way) tell her which page to serve. It's important to remember that, at its simplest, interaction with Hazel is just a matter of specifying an HTML link, just as you would link from one page to another. It isn't magic.

Below are descriptions for each of Hazel's actions, along with some HTML examples of their usage.

Add skuid

If you wrap your brain around only one action, it should be the ADD action. By using this action alone with an installed Hazel catalog, your work is mostly done. The ADD action (as its name implies) adds a single SKUID to the shopper's cart.


<a href="/cgi-bin/hazel.cgi?action=add&item=FOO">
Add a FOO!</a>

Grasp the wonderful simplicity of this: merely adjust the "href" URL to your Hazel if necessary, substitute FOO with any SKUID desired, slap the anchor around any text or image in your catalog, and you've enabled adding an item.

As of Hazel 3.375, adding ENABLE_ADD_REDIRECT:1 to your hazel.config will cause Hazel to immediately redirect to the view action when an item is added with the ADD action. This can squelch shopper complaints of "more items than I ordered" resulting from backing up over an add action and reloading.

You can also add an item inside of an html form like so:


<form method="POST" action="%HZU_FORM|%HZU_MAIN"> 
<input type="submit" name="SUBMIT_ACTION_ADD_%HZI_SKUID" value="Add to cart"> 
</form>

This will add 1 item of the given SKUID to the shopping cart. If you wish to specify the number of items in the cart, add the following:


<form method="POST" action="%HZU_FORM|%HZU_MAIN"> 
<input type="text" name="PRODUCT_%HZI_SKUID" value="1"> 
<input type="submit" name="SUBMIT_ACTION_ADD" value="Add to cart"> 
</form>

Where value="1" is the the default quantity to add to the cart.

Detail skuid

The DETAIL action is a handy way to show product information for a particular SKUID in your catalog. It sets the context of Hazel's %HZI tokens so that you can display the value of any product field merely by using %HZI_ following by the field name.

See your hazel-cat/templates/detail.html template for the default data displayed.


<a href="/cgi-bin/hazel.cgi?action=detail&item=FOO">
Show detailed information on FOO.</a>

Prior to Hazel 3.428, the DETAIL action had a slight bug in that it would temporarily add the detailed item to the cart while it was being detailed. This only affected those who displayed a list of selected items in their detail template, but I thought I'd mention it so you don't freak out.

Serve filename

When Hazel is told to "serve" a page, she reads the given filename off the web server disk, processes it for any special HZML codes, then spits it back out to the shopper's browser. Serving a page through Hazel is the only way to have those special HZML codes processed, so if you plan to use Hazel to dynamically generate catalog pages, you'll have to use the serve action.


<a href="/cgi-bin/hazel.cgi?action=serve&item=foo.html">
Click here for a page devoted to the wonders of FOO.</a>

<a href="/cgi-bin/hazel.cgi?action=serve&item=aisle.html&cat=books">
Click here for our book aisle.</a>

The second link above alludes to a trick available when serving pages: anything you "pass" in the serve link can be accessed by Hazel as an %HZE token in that page. So, you can send a certain variable through the serve action which can be used to build, for example, a list of products. Above we have a cat=books. Below is some possible code for the aisle.html page which would generate a list of books in the catalog.


<!-- %HZE_CAT is used to retrieve the CAT field value passed to us. -->
<!-- Here we use it for a cosmetic page header display. -->
<h1>%HZE_CAT</h1>

<p>Here are some of our fine products in the "%HZE_CAT" category.</p>

<!-- Some advanced Hazel hackery to build a list of all our products -->
<!-- with a GROUP field equal to "BOOKS" (whatever passed as CAT.) -->

<Hazel-Loop Type="Products" Group="%HZE_CAT">

<h2>%HZI_NAME</h2>
<p>%HZI_DESC</p>
<p><em><a href="/cgi-bin/hazel.cgi?action=add&item=%HZI_SKUID">
Click here to purchase one for %HZI_PRICE!
</a></em></p>

</Hazel-Loop>

That's a lot of example to digest. The relevant bit of new info is the passing of the CAT field and the retrieval of its value with the %HZE_CAT HZML token. The product loop which will actually output all the "book" products can be read about in the HZML loops documentation.

Home

The HOME action is basically just the SERVE action with an item of the START_PAGE field value in your hazel.config.


<a href="/cgi-bin/hazel.cgi?action=home">
Go home.</a>

<a href="/cgi-bin/hazel.cgi?action=serve&item=%HZM_START_PAGE">
Also go home.</a>

Return

The RETURN action is basically just the SERVE action with an item of the last page Hazel served. That sentence can be a little misleading. If Hazel serves a page, the last page she served is that same page. So, when serving Hazel pages, the RETURN action will usually just reload the same page. As such, it's usually included in the Hazel checkout templates, as an option for the shopper to return to wherever they were browsing.


<a href="/cgi-bin/hazel.cgi?action=return">
Reload this page.  Whee.</a>

<!-- Used as a form submit button name -->
<form action="/cgi-bin/hazel">
<input type="submit" name="Submit_Action_Return" value="Continue Shopping">
</form>

If you add a RETURN_BACK:1 line in your hazel.config file, the RETURN action will behave as a BACK action. The BACK action is a more generally useful way to send shoppers back from whence they came, particularly in a catalog environment where many of your pages are not served by Hazel.

Back

The BACK action is similiar to the RETURN action, with some special handling for cases where the shopper did not arrive at the current page through a Hazel-served page. In that case, Hazel attempts to redirect the shopper back to the referring page.

If you add a RETURN_BACK:1 line in your hazel.config file, the RETURN action will behave this way, as well.

This is useful in cases where, for example, someone from another site is adding an item to your catalog. Also useful if you have "add" links sprinkled over your site, or other of sites under your purview, not all served by Hazel.

View

Checkout

The VIEW and CHECKOUT actions cause Hazel to serve her view and checkout templates. The view template is a simple list of products thus far selected, while the checkout template provides additional form input fields for the shopper's billing and shipping information.

Links issuing either of these actions can be sprinkled throughout your catalog to allow the shopper a way to skip right to the checkout stand.


<a href="/cgi-bin/hazel.cgi?action=view">
View your cart.</a>

<a href="/cgi-bin/hazel.cgi?action=view">
<img src="pretty_shopping_cart.gif" alt="View Cart">
</a>

<!-- Used in conjunction with a form allowing product quantity input -->

<form action="/cgi-bin/hazel">

<p>Enter how many FOO you would like in the box below, then click the
checkout button to finish your order!</p>

<input type="text" name="Product_FOO">
<input type="submit" name="Submit_Action_Checkout" value="Checkout">

</form>

The final example above illustrates a basic way to add an item to your catalog's shopping cart. It includes the relevant example of form usage of the CHECKOUT action, but the actual product-adding bit is with the text input field. Its name is Product_FOO. Any field beginning with Product_ is interpreted by Hazel as an addition of an SKUID (specified by the rest of the name) to the shopping cart, with a quantity of the value of the field.

So, in the example above, the shopper enters a number into the Product_FOO textfield, clicks the checkout button, and Hazel adds that many of the SKUID FOO into his or her cart.

Confirm

Finish

You won't normally need to use the CONFIRM and FINISH actions anywhere other than where they appear by default-- on the checkout and payment templates. They initiate the final two stages of Hazel's checkout process: confirmation of data entered during checkout, and final submission of the shopper's order.

You can modify what fields are required when they are performed by editing your hazel-cat/rules/field.rules file. It's a simple text file separated into blocks for each of the major Hazel checkout actions.

When a CONFIRM action is successfully initiated, Hazel then serves up a template in the hazel-cat/templates/payment directory corresponding to the value of the PAYMENT_METHOD field submitted by the shopper.

FINISH is special in that Hazel interprets any action merely beginning with the word "finish" as a request to finish up the order. This allows you to specify multiple FINISH_* blocks within field.rules to require different fields be input for different payment methods.

More can be learned about payment methods and finishing up orders by reading the documentation on payment methods.

For more on what exactly Hazel does when she finishes an order, see the documentation on order reporting.

Search

The SEARCH action initiates a Hazel search. It requires the purchase of a Hazel Search Engine key for operation, and is fully documented in the Hazel Search Engine documentation.

The simple example below shows you how to present a minimal search form for a shopper, allowing them to initiate a search on the default product fields of NAME and DESC.


<form action="/cgi-bin/hazel">

<p>Enter keywords and click the search button to search our
 products database!</p>

<input type="text" name="Search_Spec">
<input type="submit" name="Submit_Action_Search" value="Search">

</form>

Secure

The SECURE action is a holdover from the early days of web commerce when not everyone had an SSL-enabled browser capable of "secure" transactions. (Yes, there really was a time when the primary function of the Internet was information sharing and not e-commerce!)

The preferred protocol nowadays is to specify HTTPS_AUTO:1 in your hazel.config file. Hazel will then automatically redirect to your secure server when the shopper reaches the checkout stage at which sensitive personal information is entered. (And redirect back to nonsecure pages if they want to continue shopping.)

Empty

The EMPTY action removes all selected items from the shopper's cart and displays a page notifying them of such.

Individual items can be removed from the cart by specifying a quantity of 0 (zero) in the quantity box then submitting the form.

As there isn't much to say about the EMPTY action here, I'll include a little trick to use a link to remove a particular product. We'll assume it's being used in your view or checkout template, within a products loop, so the %HZI_SKUID in question is the SKUID of a particular selected item.


<a href="/cgi-bin/hazel.cgi?action=view&product_%HZI_SKUID=0">
Remove this item from your cart.</a>

As elucidated in the CHECKOUT action example, any field beginning with Product_ is interpreted by Hazel as specifying the exact quantity desired for an item. Above, we just set the quantity of a particular item to 0, thus removing it from the cart. We use the VIEW action just to give Hazel something to do -- in this case, load the view template. Otherwise, she'd perform her default action and serve the store homepage.

Pickup pickup-id

The PICKUP action is used only by the Hazel Softgoods feature. A pickup action is issued with an item of a special "pickup-id" assigned by Hazel, which initiates the download of an electronic softgood attached to a particular item.

For more details, see the softgoods documentation.

ForgetMe

The FORGETME action is solely for debugging purposes. It's the equivalent of inducing amnesia in Hazel. After issuing the action, she forgets who you are and removes all the information she's saved about you. This is useful if you want to re-enter a catalog you're testing as a "new" shopper.

Unlike the bulk of Hazel's actions, you'd rarely have a need to use this as a link in a catalog. Instead, you'd just enter the full URL to your Hazel followed by an action specification like so:

http://example.com/cgi-bin/hazel.cgi?action=forgetme

Hazel will recognize who you are and summarily forget you.

ShowReg

The ShowReg action displays registration and configuration information about your catalog. Mainly for debugging, or for figuring out just how many days are left on your trial, or (with H4) what plugins you have installed.

SHOWREG is another action you don't want to embed into your catalog's HTML. Just enter the full URL to your Hazel followed by an action specification like so:

http://example.com/cgi-bin/hazel.cgi?action=showreg

Your catalog info should pop right up.

Basic hazel.config information and some diagnostics are visible in the source code of this page. This information is very useful for debugging, but if you'd like to disable it, set SHOWREG_CONFIG:0 in your hazel.config.

Source filename

The SOURCE action is similiar to the SERVE action. However, instead of rendering the HZML in the page, Hazel just serves the page as it exists on the disk. It's akin to the "view source" option on a web browser.

Just enter the full URL to your Hazel followed by an action specification like so:

http://example.com/cgi-bin/hazel.cgi?action=source&item=foo.html

Test

Another debugging action, TEST sends you to the checkout page with one item from your catalog selected, and junk filled in for all the required fields. It's an easy way to test an order.

Just enter the full URL to your Hazel followed by an action specification like so:

http://example.com/cgi-bin/hazel.cgi?action=test

Requires Hazel version 3.407 or later.


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