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

The core of Hazel's memory is in a simple little text file called hazel.config. Her identity, where she lives, where she works, who's her daddy--all of it is in this file which sits beside her in the cgi-bin directory on your web server. Its format is simple, and with your brilliant mind being the knowledge-hungry sponge that it is, you will undoubtedly grok it straight off.

Hazel ignores a hash mark (`#', AKA "pound sign", "number sign", or the exotic "octothorpe") and everything after it. Hazel also ignores blank lines. In fact, the only thing she cares about are lines which consist of a key name and a value, separated by a colon.

For example, "NAME: Hazel" defines a config file field named "NAME" with a value "Hazel".


Keys

The first bit of information Hazel needs is your serial number and activation keys. All keys are unique to your serial number and will not work with any other. A proper combination unlocks various features of your Hazel catalog.

Hazel's keys are strings of characters which beg you to make typographical errors, especially when 0 (zero) and O (oh) or 1 (one) and l (el) are virtually indistinguishable in many fonts. Save yourself a lot of trouble and use your copy and paste functions to install the keys.

HAZEL_SERNO

This is a unique 10-digit number which identifies your catalog. The keys you enter are tied to this number.

HARDGOODS_KEY

You'll need either this or the softgoods key to activate the basic features of Hazel. Whether you choose hardgoods, softgoods, or both depends on what kind of products you plan to sell. The distinct feature a hardgoods key activates is Hazel's ability to charge for shipping your products.

SOFTGOODS_KEY

One of the two basic Hazel keys, the softgoods key activates Hazel's ability to deliver digital products (such as software, forms, documentation, literature, or pornographic images) to your customers automatically.

SEARCH_KEY

The search key activates Hazel's search engine, and other features (such as the query loop) which use it. The search engine allows Hazel to search her products file for any information you've entered about the items you sell.

The search engine will not search your HTML pages. Its primary use is as a tool for dynamically creating your site from arbitrary shopper search queries or your own custom templates.

OPTIONS_KEY

The options key activates Hazel's optioned products feature. With optioned products, you can offer your base products for sale with various options attached. For example, instead of entering eight shirts into your products file which vary only in color, you could use a single shirt product with eight color options.

Using optioned products also expands the ways you can offer products to your customers. Instead of a list of 32 links to a single shirt in eight colors and four sizes, you can compact the form to two drop-downs for color and size. You can't do this without the options key.

File Locations

The DIR (short for "directories", AKA "folders" or "paths") fields specify the locations of the three groups of files Hazel accesses when serving your catalog. Each of them has a `prettier' nickname by which they'll be referred in the descriptions.

The values of these fields are directory names, not URL. On a Unix-based system they'd have values such as /web/foo.com/htdocs. On a Windows server, it might be c:/inetpub/foo.com. You may have to ask your ISP's help in determining the exact format of these values.

For Earthlink customers: a directory such as /netapp/benny/s2/s2/00442/www.foo.com/ should be entered instead as /www/htdocs/domains/s2/00442/www.foo.com. The /netapp paths represent a current server farm address which may change.

CAT_DIR aka hazel-cat

All catalog setup information (except the hazel.config file resides in the hazel-cat directory: Hazel's products file, the templates which define the look and feel of her checkout process, and the rules which determine tax and shipping costs.

In addition to storing read-only configuration data, the hazel-cat directory structure is written to by Hazel. She records temporary shopper data (such as what you have in your shopping cart) here, as well as a master log of all orders she's received.

It is important that this directory not be accessible from the web. If you can see it from the web, anyone can. That means anyone can casually browse possibly sensitive information placed here.

DOC_DIR aka hazel-doc

When Hazel is asked to `serve' a file, she looks for it in her hazel-doc directory. All files she serves must be located here or in a subdirectory.

CGI_DIR aka hazel-cgi

The hazel-cgi directory is where Hazel looks for any custom scripts, and where custom scripts look for Hazel. This directory should contain at least your hazel.cgi (or hazel.exe on a Windows server) and hazel.config files.

URL

While Hazel doesn't do any web surfing herself, she does place hints into the pages she serves which tell browsers where to find her various bits. These fields define those web addresses, and correspond to the two web-accessible file paths above.

HTTP_DOC_ROOT

This URL tells Hazel where to find your catalog HTML and images from the web. It corresponds to hazel-doc: the directory in which you placed those files. While she won't ever need to access them over the web herself, she will use this URL to guide browsers to the proper location.

If this field is set incorrectly, you'll see no background images on your sample catalog templates, and possibly see broken images on the final payment pages which bullet order notes.

HTTP_CGI_BIN

This URL tells Hazel where to find herself from the web. It corresponds to hazel-cgi: the directory in which you installed Hazel.

If this field is set incorrectly, none of the links to Hazel in your sample catalog will work, and form submission in her checkout templates will fail.

Secure URL

A secure server is an essential part of any online catalog. Regardless of the real threat of unencrypted data transfer, many shoppers will not shop a site unless they see that re-assuring blue bar, clamped and glowing padlock, or unbroken key icon on their browser.

Hazel works with your existing secure server setup, which usually involves two steps: registering for and purchasing a secure certificate and obtaining access to a secure server. Your ISP can help you with these steps.

If you don't have a secure server setup right now, you can safely skip this section. When you're ready, simply enter the appropriate values into the fields described below.

HTTPS_ENABLED

Set this true if you have access to a secure (SSL) server you'd like Hazel to use. This field doesn't do anything in itself, but must be true in order for Hazel to use the various informative fields below.

HTTPS_DOC_ROOT

These first two HTTPS URL are counterparts for the HTTP URL above. They are required if you wish to use a secure server with Hazel. Both should point to the web address of the same hazel-doc directory. In order to use a secure server with Hazel, both the secure and nonsecure servers must access the same Hazel files on disk!

HTTPS_CGI_BIN

This URL points to the secure web location of Hazel's CGI directory. It is required if you wish to use a secure server with Hazel. Again, both the secure and nonsecure URL should point to the web address of the same hazel-cgi directory.

HTTPS_AUTO

If set true, Hazel will automagically redirect to your secure server when the shopper enters the checkout stage of the order to enter personal information, moving back to your nonsecure server when they're simply browsing the catalog.

HTTPS_ALWAYS

By setting this field true, you're telling Hazel that you always want your catalog served securely--even when the shopper isn't entering any personal information. Be sure to set both HTTP and HTTPS URL field values to the URL of your secure server.

Your Store

These fields contain basic RL info about your store. Nothing brain-bending in these answers. Just relax, take a deep breath, and search yourself.

STORE_NAME

The name of your store. This is used as part of your default e-mail subjects and checkout page titles.

STORE_PHONE

A real-life phone number reachable for information about an order, generally to be used by those too impatient to wait for a response sent to STORE_EMAIL.

This number is used in the default checkout and e-mail templates as a contact point for questions or problems which require human contact.

STORE_HOMEPAGE

The URL for your Internet homepage. This should be the frontdoor to your web presence, and not necessarily a direct link to Hazel.

E-mail

These fields affect the e-mail which is sent by Hazel. If you're not receiving confirmation e-mails after submitting orders through your catalog, your first trouble-shooting step is to double-check and tweak these values.

STORE_EMAIL

An e-mail address for sales-related questions, from which all e-mail sent by Hazel will appear to have originated. This is the primary Internet contact point for your catalog, where questions about an order are sure to be directed.

Contrast this with the addresses specified by the ORDER_RECIPIENTS config field value, which are the addresses to which your orders will be sent.

Be sure this is a valid e-mail address, preferably an account on the same domain as your website. If your shoppers aren't receiving order confirmations, this address might be wrong.

ORDER_RECIPIENTS

This is a space-delimited list of e-mail addresses to which Hazel will send rendered copies of your store invoice template when an order is received.

ORDER_SUBJECT

This will appear as the subject of all e-mail sent by Hazel.

MAIL_SHOPPER

If set true, Hazel will send a confirmation e-mail (customizable through the shopper invoice template) to the shopper when an order is received.

MAIL_PATH

This is the full pathname to your Unix web server's sendmail program. It's usually something like /usr/sbin/sendmail or /usr/lib/sendmail.

You don't need this if your web server runs Windows NT.

MAIL_HOST

This is the hostname of a SMTP (mail) server through which your domain is authorized to send e-mail. Ask your ISP which SMTP server you should use.

You don't need this if your web server is Unix-based.

Misc

Here are a few miscellaneous required fields. Discerning their correct values doesn't require a lot of brainpower.

HAZEL_NAME

This is the name of your Hazel CGI program. It should remain hazel.cgi on a Unix-based server, and hazel.exe on a Windows server.

START_PAGE

This is the name of a file in your hazel-doc root. Hazel will serve it when she doesn't have anything else to do (ie. she's called without any form data), or when the HOME action is submitted.


What else?

There are many more config file fields which can be used to tweak the way Hazel behaves. You may peruse the bleeding-edge alphabetical index for all of them, but the above are all fields which are required for a running catalog. You should now return to the walkthrough and explore your sample catalog!

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