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.
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 SKU would beFOOSHIRT-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 theFOOSHIRTentry in your products file, but derive its name from those descriptions. IfFOOSHIRThad a name of "Foo Shirt",FOOSHIRT-SZL-CBLwould be "Foo Shirt (large, blue)". The name is built from the name of its "parent SKU", plus the options separated by commas within parentheses.
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...
The value of each
OPTIONED_FOOSHIRTfield submitted adds to the base SKUID ofFOOSHIRT. If the shopper chooses "small" and "green", aFOOSHIRT-SZS-CGRis added to his order. The order of the options does not matter.FOOSHIRT-SZS-CGRis the same asFOOSHIRT-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 namedOPTIONED_QUANTITY_FOOSHIRT.
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:
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!
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.
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.
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_SKUID The base SKUID of this optioned product. %HZI_UNOPTIONED_NAME The name of the base SKUID. %HZI_UNOPTIONED_PRICE The unoptioned price of the base SKUID. %HZI_UNOPTIONED_WEIGHT The unoptioned weight of the base SKUID. %HZI_OPTIONED_SUFFIX The delimited option codes added to the base
SKUID of this product to form the optioned SKUID.%HZI_OPTIONED_NOTES The 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:
This optioned weight and VIRGIN_OPTIONED_NAMES feature is available in Hazel version 3.2 or later.
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.
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...
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.
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.
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.