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: Optioned Products

To use Hazel's optioned products feature, you must purchase an optioned products key. Visit the Hazel store for more information. Additionally, you should be sure to have the latest Hazel for your platform! See our supported platforms page for more information.

Often one wishes to sell a number of products which are essentially the same but for a color, size, or other option. Hazel allows you to create a single SKUID in your products file and associate it with options in your options file. These "optioned SKU" consist of the base SKU in your products file followed by option codes (assumed to be in your options file) separated by dashes.

Your options file should be placed in the same directory as your products file. Like the products file, it is a simple text file. No fancy doodads required to edit it. Just open a new document in your favorite text editor, type in the description of your options (see the sample below), and save the file as "options" in the same directory as your products file.

Each line of the options file describes an option. Comments may be specified with the '#' comment character, and a description of the option is specified with the '@' character.

Here's a simple sample options file.


# My Options

[SIZES]
SZS:@small
SZM:@medium
SZL:@large
[/SIZES]

[COLORS]
CRD:@red
CBL:@blue
CGR:@green
[/COLORS]

Option codes must consist of "word" characters only: letters, numbers, and underscores. Descriptions may contain any characters except the comment character.

The square brackets surround groups of options. This allows you to refer to options as groups rather than listing them separately, which can come in handy when using some option-specific loops.

It is advisable to make all option codes unique. If you want to use the same option code for several different options(ie. SZS for shirts and shoes, which may alter prices differently), then you'll have to put each in its own group, and assign that group's name to a particular product by setting its OPTIONS field.

Defined are three size options and three color options. Let's say you have an SKU FOOSHIRT. You want to sell a large, blue fooshirt. The optioned SKUID would be FOOSHIRT-SZL-CBL. See the descriptions (text after the '@' sign) in the example above? When Hazel receives a request to add the optioned product, she will grab the base information for the product from the FOOSHIRT entry in your products file, but derive its name from those descriptions. If FOOSHIRT had a name of "Foo Shirt", FOOSHIRT-SZL-CBL would be "Foo Shirt (large, blue)". The name is built from the name of its "parent SKU", plus the options separated by commas within parentheses.

Selecting an Optioned Product

Hazel's optioned products do more than save you the trouble of typing in new SKUID for each possible combination of size or color. By using a special form field name, you can construct optioned SKUID by using HTML drop-down boxes. Here's an example...

<form method=post action="%HZU_MAIN">

<p>
Buy one of our beautiful fooshirts. Choose a size and color below, 
then press the button to add it to your shopping cart.
</p>

<p>
Size: <Select name="OPTIONED_FOOSHIRT">
<option value="SZS">small
<option value="SZM">medium
<option value="SZL">large
</select>

<p>
Color: <select name="OPTIONED_FOOSHIRT">
<option value="CRD">red
<option value="CBL">blue
<option value="CGR">green
</select>

<p>
<input type="submit" name=SUBMIT_ACTION_ADD value="Add">

</form>

The value of each OPTIONED_FOOSHIRT field submitted adds to the base SKUID of FOOSHIRT. If the shopper chooses "small" and "green", a FOOSHIRT-SZS-CGR is added to his order. The order of the options does not matter. FOOSHIRT-SZS-CGR is the same as FOOSHIRT-CGR-SZS.

Using this method to add an optioned product will always result in the addition of a single new optioned product to the shopper's cart. The shopper can modify the quantity later in the checkout stage.

As of version 3.334, you can send an OPTIONED_QUANTITY_* field corresponding to the base SKUID of the optioned product being built, if you'd like to allow the shopper to immediately enter a quantity. In the example above, it would be named OPTIONED_QUANTITY_FOOSHIRT.

Option Prices

Some options may require alternate pricing. For example, you may be selling items with optional copper, silver, or gold plating. Include the added price in your options file:

# Plating
PLC:+1.5  @copper-plating
PLS:x2.0  @silver-plating
PLG:x3.0  @gold-plating

Copper plating will add an extra $1.50 to the price of the item. Silver plating doubles the price. Gold plating triples it.

The format is simple: "+N.N" to add a flat charge, and "xN.N" to multiply the base price of the item. To derive the final optioned price, all multipliers are added together and applied to the base price, then flat charges are added.

The final optioned price obtained from multiple price multipliers (using 'x') may not always be intuitive. They are added together, not multiplied. For example, while you might think a "x0.50" and "x2.0" would mean "half off twice the price" resulting in the original base price, Hazel adds them all together and interprets it as "two and a half times the price."

If you want to save the multiplication until after all flat additions are applied, use '*' (asterisk, star) instead of 'x' as the multiplier token.

With any optioned pricing, make sure the calculated optioned price is what you intended!

Option Weights

In addition to custom pricing, some options may add weight to a product. Weight modifiers are separated from the price modifier by a semicolon, as shown below.

# Plating
PLD:+0;x2.0  @lead-plating
PUR:+0;x5.0  @depleted uranium-plating

Lead plating will double the item's weight, and depleted uranium plating will quintuple it. We use the `+0.0' syntax above for unmodified prices, but you could have included standard price modifications as explained in the previous seciton.

This optioned weight feature is available in Hazel version 3.2 or later.

Unoptioned Data

Hazel sets several special %HZI tokens on optioned products which contain information describing the base product. You can use these to customize the display of optioned products.

%HZI_UNOPTIONED_SKUIDThe base SKUID of this optioned product.
%HZI_UNOPTIONED_NAMEThe name of the base SKUID.
%HZI_UNOPTIONED_PRICEThe unoptioned price of the base SKUID.
%HZI_UNOPTIONED_WEIGHTThe unoptioned weight of the base SKUID.
%HZI_OPTIONED_SUFFIXThe delimited option codes added to the base
SKUID of this product to form the optioned SKUID.
%HZI_OPTIONED_NOTESThe description of the options selected.
Identical to the parenthetical text usually
added to the optioned product's name.

Don't like Hazel's parenthetical description of options being slapped onto your product names? Set VIRGIN_OPTIONED_NAMES:1 in your hazel.config file, and she'll leave them alone. You can duplicate the effect yourself by using the unoptioned tokens like so:

%HZI_NAME (%HZI_OPTIONED_NOTES)

This optioned weight and VIRGIN_OPTIONED_NAMES feature is available in Hazel version 3.2 or later.

The OPTIONED Loop

There is a special HZML products loop type which iterates over all the optioned variations of a base SKU. Below, along with the description of this "optioned loop", is some HZML based on the sample options file above. It will loop through every color of FOOSHIRT: FOOSHIRT-CRD, FOOSHIRT-CBL, FOOSHIRT-CGR.

HAZEL_LOOP TYPE=OPTIONED
base=skuid A product code.
group=group A blocked group of options in your options file.

An "optioned" loop iterates over a group of products created using the given base and options group. For each option in the group, Hazel constructs a new optioned SKUID representing the base SKUID with that option.


<!-- Show all color combinations of product FOOSHIRT. -->

<ul>
<Hazel-Loop Type="OPTIONED" Base="FOOSHIRT" Group="COLORS">
<li>%HZI_SKUID: %HZI_NAME, %HZI_PRICE</li>
</Hazel-Loop>
</ul>

  • FOOSHIRT: Foo Shirt (red), $9.95
  • FOOSHIRT: Foo Shirt (blue), $9.95
  • FOOSHIRT: Foo Shirt (green), $9.95

What if you wanted to include also all the various sizes in your loop, resulting in a loop of every possible type of FOOSHIRT? Can do! Just nest another optioned loop inside the outer one like so...


<select name="PRODUCT">
<Hazel_Loop Type="OPTIONED" Base="FOOSHIRT" Group="COLORS">
<Hazel_Loop Type="OPTIONED" Base="%HZI_SKUID" Group="SIZES">
<option value="%HZI_SKUID">%HZI_NAME, %HZI_PRICE
</Hazel_Loop>
</Hazel_Loop>
</select>

Note that the inner loop uses %HZI_SKUID for the BASE attribute. That means the color option will be added to each of the SKUID derived in the first example. Assuming a FOOSHIRT costs $9.95 and is named "Foo Shirt", Hazel would render the HZML source above as shown below.

The above rendering assumes it's enclosed within a FORM pointing to your Hazel CGI. When Hazel sees a field name "PRODUCT", she adds the SKUID indicated in its value to the shopper's cart. Thus, after adding a submit button, you have a drop-down list of all optioned permutations of the given base product.

As with any Hazel loop, you may use other HZML tags and tokens within its body, including buttons or links to add each optioned variation.

Each optioned variation becomes a real product with the same set of attributes as its base SKUID. Only the name (parenthetical option descriptions added) and perhaps the price and weight (for priced or weighted options) are changed.

The OPTIONS Loop

While the optioned loop iterates over constructed optioned products, the options loop does so with individual option codes. This allows you to automate optioned drop-down boxes.

HAZEL_LOOP TYPE=OPTIONS
GROUP=group A blocked group of options in your options file.

An "options" loop iterates over a group of options from your options file. Within the loop body, %HZM_WORD1 is replaced with the option code and %HZM_WORD2 the option description.


<!-- Show an HTML form drop-down box for all options. -->
<!-- in the COLORS group in your options file.        -->

<select name="OPTIONED_FOOSHIRT">
<Hazel_Loop Type="OPTIONS" Group="COLORS">
<option value="%HZM_WORD1">%HZM_WORD2
</Hazel_Loop>
</select>

Assuming the same FOOSHIRT and COLORS options as in our previous examples, Hazel would render the sample HZML source above as shown below.

The above rendering should, of course, include a submit button and be enclosed within a form pointing to your Hazel CGI for it to do anything useful. When Hazel sees a field name OPTIONED_SKUID, she adds the value chosen as an option for the base SKUID (FOOSHIRT in the example above.)

The options loop is available in Hazel version 3.1 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