Each product to be sold by Hazel has an entry in her products file. This is a simple text file named products located in your catalog root. Each line of the products file consists of a FIELD:VALUE pair. Blank lines and everything after and including a pound sign ('#'; Hazel's "comment" character) will be ignored.
Field names may consist of up to 64 letters, numbers, or underscores, but must begin with a letter. Field values may consist of any 4,096 characters, but remember that anything after and including the comment character will be ignored (*).
(* As of Hazel 3.2, you can "escape" a pound sign with a backslash. Just include a backslash immediately before the pound sign and Hazel will disregard it as a comment character and add it to your field value.)
Each product entry should start with an SKUID field identifying the product described by all fields up to the next SKUID field.
Any field value FOO can be accessed with HZML token %HZI_FOO in Hazel's various product loops, so you can use the information in your products file for "shopping cart" displays, item details, match results, and more.
Here's a minimal, one-product products file.
# products
# A simple one-product product file. This is a comment.
SKUID:HZ101HB
NAME:Hazel for Dummies (hardback)
PRICE:9.95
WEIGHT:8
DESC:A beginner's guide to using Hazel.
|
Basic Fields
You may add any number of fields to your products file and access them with tags and tokens in your Hazel-served pages and templates. Here we'll describe some of the basic fields which have special significance to Hazel. You should use these only for their stated purpose below.
SKUID
SKUID is the product's (S)tock (K)eeping (U)nit identifier. All products are indexed by this value. SKUID are special values which adhere to the same restrictions as product file field names: they may consist of up to 64 letters, numbers, or underscores and must begin with a letter.
To avoid any case-sensitivity issues when accessing an SKUID, alphabetic characters within an SKUID value are converted to uppercase when read by Hazel.
Note that you may not use a hyphen ('-') in an SKUID. Hyphens are interpreted specially by Hazel; using them in your SKUID will result in problems. Don't do it.
NAME
NAME is the product's title. It should identify the product briefly, but completely enough to avoid confusion with like products. For example: "Shroud of Turin", "Elmo Watch (Plastic)", "Barney Shirt (Red; XL)".
PRICE
PRICE is the price of the product. Its format presumes a decimal point (ie. "4.95", "6.00"). Its value is "currency-neutral", and must not contain a dollar sign ($) or any other currency glyphs! Use only numbers and a single decimal point for price values.
WEIGHT
The value of the optional WEIGHT field indicates the weight of the product, in whatever units you prefer. The weight needn't map to "pounds" or "kilograms"; you can use it internally as generic "units" in your shipping rules.
DESC
An optional DESC is a brief description of the product. This is useful primarily in the detail and search result templates.
Special Fields
The following fields are not required, but they will also be specially interpreted by Hazel. Again: you should use these only for their stated purpose below.
MAXQ
MAXQ is the maximum quantity of this product which can be ordered. If the shopper selects more than this number, a message will be displayed at checkout and the quantity will be adjusted down to the maximum.
MINQ
MINQ specifies the minimum quantity of this item which must be ordered. As with MAXQ, if the shopper selects less than this amount, a message is displayed at checkout and the quantity is adjusted up to the minimum.
DISCOUNT
A DISCOUNT field can have many values, the explanation of which is best left to the discount rules documentation.
SHIPPING
A SHIPPING field's value indicates a fixed shipping charge for this product.
Additionally, any field SHIPPING_FOO describes a shipping rate to a particular SHIP_REGION FOO.
If all products ordered by the shopper have SHIPPING fields, Hazel will not normally parse her shipping rules files. This can be bad if you want to add a surcharge or designate a shipping method as being taxable. In that case, add a plus sign (+) before the shipping value to force Hazel to parse her shipping rules when the item is ordered.
TAX
A TAX field's value indicates a fixed (decimal) tax rate for this product. For example, 0.08 would indicate at 8% tax on a product. Use 0 for tax-free items.
Additionally, any field TAX_FOO describes the tax rate for a particular TAX_REGION FOO.
MTEMPLATE
If all products of a particular search engine query have the same MTEMPLATE value, that template (in the hazel-cat/templates/custom directory) is used as the matches template. As of version 3.359.
DTEMPLATE
When a product is detailed with the DETAIL action and it defines a DTEMPLATE field, use that (in the hazel-cat/templates/custom directory) instead of the default details template. As of version 3.359.
Softgoods Fields
The following fields are used by Hazel's softgoods feature.
PICKUP_FN
PICKUP_FN points to the downloadable file (located in hazel-cat/softgoods described by this product record. This field is required for any product you wish to be downloadable. Its value may contain HZML.
PICKUP_EXPIRES
PICKUP_EXPIRES overrides for this product the config file field DEFAULT_PICKUP_EXPIRES as the number of seconds after the order is finished for which the softgood is downloadable.
PICKUP_INLINE
If PICKUP_INLINE is true for a product, then the shopper's browser is instructed to display the softgoods content in the browser window rather than prompt the user to save it as a file. This is useful primarily when your softgood is an HTML page.
Additionally, all field names beginning with PICKUP_ are reserved for future use by Hazel. Some are generated by Hazel during the softgoods process.
Options Fields
The following fields are used by Hazel's optioned products feature.
OPTIONS
The OPTIONS field value should be a single group name in your options file whose codes can be used with this base SKUID to form optioned products. It is required only if you have multiple option codes with the same name in different groups within your options file.
OPTIONED_NOTES
The OPTIONED_NOTES field is set to a comma-delimited list of option descriptions for the optioned product.
UNOPTIONED_*
The UNOPTIONED_SKUID, UNOPTIONED_NAME, UNOPTIONED_PRICE, and UNOPTIONED_WEIGHT fields are also written by Hazel, with values corresponding to those of the base SKUID in your products file, before optioned product mutation.
Additionally, all field names beginning with UNOPTIONED_ are reserved for future use by Hazel.
Other Reserved Fields
The following fields are used internally and should not be assigned to any of your products. Any value you assign will be overwritten by Hazel.
QUANTITY
QUANTITY is the quantity of this product selected by the shopper.
TOTAL_* Fields
None of your field names should begin with TOTAL, as Hazel writes several fields (eg. TOTAL_PRICE and TOTAL_WEIGHT) for each product when tallying up order totals.
|
