Note: To use Hazel's search engine feature, you must purchase a search key. Visit the Hazel store for more information.

Hazel's search engine scours her products file for records matching a given search specification. Because the search is focused on the products file itself, the shopper receives matches which reflect real product information rather than incidental HTML code and copy.

The Hazel search engine does not search your HTML files. It will only find information you have stored in your products file.

Building a Query

A fully qualified search specification ("search spec") consists of a search logic character, a product field name, a search comparison character ("search comp"), and a subject field. Here's a representation of a search spec, with the optional elements surrounded by square brackets.

[logic_character][product_field][comparison_character]subject

Now we'll throw your baby bottom into an icy swimming pool of examples. Don't be afraid if these make no sense--it will all be explained later!

+SKUID=FOO
+PRICE<5.00
-PRICE>1000.00

+DESC%Art +DESC%Modern
+PRICE>5.00 +PRICE<100.00

The product_field is any field in your products file. The subject is any word or number. The search logic and search "comp" characters are listed below. All but the "subject" are optional; if a given field is absent, it defaults to the relevant DEFAULT_SEARCH_* field in your hazel.config file, or SEARCH_* values passed to Hazel with the search spec.

Search Logic

The search logic character, if present, should be the first element of the search specification. It defines the importance of this particular bit of the overall search specification.

The URL-encoding column is important only if you are forming a search query based on an HTML link rather than a form, and wish to use the character in that link. Use the URL-encoding instead to prevent your browser and Hazel from misinterpreting special characters. The encodings in a red font must be used in place of the raw character, as the character has special meaning on its own.

Character	URL-Encoding	Full Name	Description
?	%3F	OR	If this key matches, the product matches.
+	%2B	AND	This key must match in order for the product to match.
-	%2D	NOT	If this key matches, the product does not.

Product Field

Hazel can search on any product field. If the field is present and its value is described by the total search specification, the product matches. The field isn't required to be defined on all products. In fact, it doesn't have to be defined on any!

The same URL-encoding note applies here as in the search logic table.

Search Comparison

The search comparison operator is the guts of a search spec. It defines how the field value is to be compared to the search subject.

Character	URL-Encoding	Full Name	Description
=	%3D	EQUALS	Value equals subject.
>	%3E	GT	Value is greater than subject.
<	%3C	LT	Value is less than subject.
:	%3A	CONTAINS	Value contains subject.
%	%25	WORD	Value contains subject as a distinct word. (Ie. "art", not "fart")
[	%5B	WORDBEG	Value contains subject at the beginning of a word.
]	%5C	WORDEND	Value contains subject at the end of a word.
^	%5E	STRBEG	Value begins with subject.
$	%24	STREND	Value ends with subject.

Subject

This is the subject of your comparison, the text on which this particular part of the search should be based.

Search Settings

The search action is often used via an HTML form, presenting the user with an opportunity to narrow their search of your products file. Below are the various Hazel actions associated with the search engine, and the names of form fields and hazel.config defaults which affect the search.

Actions

Here are the Hazel actions associated with the search engine. As with all Hazel actions, they can be sent either as an action field value or as the name of a submit button, when prefixed with SUBMIT_ACTION_.

Action	Description
SEARCH	The basic search action. Starts at the beginning of your products file.
SEARCH_NEXT	Show the next page of matches for the current search.
SEARCH_AGAIN	Repeat the last page of matches for the current search.
SEARCH_PREV	Show the previous page of matches for the current search.
SEARCH_GOTO	H4 only Jump to a specific numeric search page, specified as the value of an item hidden field.
SEARCH_MAX	H4 only Show all matching results on the first results page.

Form Fields

Here are the form fields you can send along with a search action, with brief descriptions. Where noted, the field derives its default from a corresponding field prefixed with DEFAULT_ in hazel.config.

Field Name	Description
SEARCH_SPEC	Contains the search specification discussed above.
SEARCH_KEY_FOO	Use the product field "FOO" as a default product field for the search spec given as the value of this field.
SEARCH_FIELD	A semicolon-delimited list of default search fields for this search. DEFAULT_* value in hazel.config.
SEARCH_LOGIC	Specifies a default search logic character for this search. DEFAULT_* value in hazel.config.
SEARCH_COMP	Specifies a default search comp character for this search. DEFAULT_* value in hazel.config.
SEARCH_MAXHITS	The maximum number of products to match per result page. DEFAULT_* value in hazel.config.
SEARCH_SORT	H4 only; available as of 4.061 Given a value of "-FIELDNAME" or "+FIELDNAME", sort the entire matching results set in descending or ascending order according to the value of fieldname in the product records. The sort is performed after the initial search, in lieu of sorting by search score. A re-sort of the matches requires another search action. Note that while the value syntax is the same, this is different from the sort attribute of product loops, which only sorts the loop's current iterators. DEFAULT_* value in hazel.config.

Config Fields

In addition to the defaults noted above, the following config file fields are used to specify other behaviour related to the search engine.

Field Name	Description
DISABLE_SEARCH_RANKING	H4 only; as of 4.037 If true, search results will not be ranked in descending order according to each match's score.

HZML

You can't have a Hazel search result without HZML. She presents her results through her templates, located in the templates/search subdirectory within your hazel-cat folder.

Successful pages of matches are shown in the "matches.html" template, and the tragedy of a failed match is played out in the "failed.html" template.

Tokens

Here are the HZML tokens available for use in the match result templates.

Token Name	Possible Values
%HZM_SEARCH_MORE	True if more pages of matches are possible, false otherwise.
%HZM_SEARCH_PREV	How many pages of matches before this one, if any.
%HZM_SEARCH_MORE_PAGES	Either "no more" or "more" depending on whether or not more matches are possible in the current search query.
%HZM_SEARCH_PREV_PAGES	Either "zero" or "N pages" depending on whether or not there are any match pages before this one.

Tags

Within the matches.html template, matches are presented in the context of a matches loop. It's like every other Hazel products loop, except that it iterates over a fixed set of products--the current page of search query results.

Hazel's search engine is useful outside of search actions, as well. The HZML query loop is like a products loop, but the products over which it iterates are defined by a search specification. This allows you to loop over products matching any criteria available in the products file!

Similiar to the query loop is the group loop. It loops through all products with a GROUP field matching a given string. While the group loop does not require a search engine key, it does use the search engine to find the matching products. It's useful for cheapskates who don't want to fork over the clams for a search engine key.

Search Examples

This HTML shows how to set up a basic user-defined search. As with all search requests, you must specify the action as SEARCH (or SEARCH_NEXT or SEARCH_PREV, though those are usually used only in the matches template).

The user is expected to enter a search spec into the input box, then optionally choose one of the values for maximum hits per result page.

<form action="%HZU_MAIN"> <pre> General Search: <input type="text" size=30 name="SEARCH_SPEC"> Matches/Page: <select name="SEARCH_MAXHITS"> <option value=5>5 <option value=10>10 <option value=25>25 <option value=50>50 <option value=100>100 </select> <input type="submit" name="SUBMIT_ACTION_SEARCH" value="Search!"> </pre> </form>

Here we see the search made simpler for the user by providing input boxes for searches based on particular product file fields-- SEARCH_KEY_SKUID for the product SKUID, SEARCH_KEY_NAME for the product name, and so on.

<form action="%HZU_MAIN"> <pre> SKUID: <input type="text" size=30 name="SEARCH_KEY_SKUID"> Name: <input type="text" size=30 name="SEARCH_KEY_NAME"> Description: <input type="text" size=30 name="SEARCH_KEY_DESC"> <input type="submit" name="SUBMIT_ACTION_SEARCH" value="Search!"> </pre> </form>

Here's an example of reducing the search query to a simple matter of choosing a drop-down box. The search spec is used as the value of each option, so all the user has to do is choose which price range he's interested in and submit the form.

<form action="%HZU_MAIN"> <pre> Price Range: <select name="SEARCH_KEY_PRICE"> <option value="">Any Price <option value="+<6">$5 or less <option value="+<11">$10 or less <option value="+<21">$20 or less <option value="+<51">$50 or less <option value="+>49">More than $50 </select> <input type="submit" name="SUBMIT_ACTION_SEARCH" value="Search!"> </pre> </form>

Finally, here's how to use the query loop to show all the spoons in your catalog (product records which have a NAME field value containing the string "spoon") which cost more than a hundred dollars (product records which have a PRICE field value that is greater than 100).

<h1>Our Swank Spoon List</h1> <ul> <Hazel_Loop Type="QUERY" Spec="+PRICE>100.00 +NAME:SPOON"> <li><a href="%HZU_ACTION=add&item=%HZI_SKUID">Add %HZI_NAME for only $%HZI_PRICE!</a> </Hazel_Loop> </ul>

Note the SPEC attribute of the query loop. You can use multiple search specs by separating them with spaces. This is true of the query loop as well as with free-text entry by users.

Links

There are some cases where you know all of the parameters of your search already. For example, you might want to dynamically generate a page of all products with "shirt" in their names.

This is as easy as embedding all of the search field names and your values into a link, and sending it off to Hazel. There can be some difficulties when sending certain characters such as `+', `=' and `&', because all of those are interpreted specially by a CGI program. We'll avoid those in this example, but they're all listed above in the search comp and logic tables.

Spaces in any of your search-related field values must be replaced with the `+' sign, which is interpreted by a CGI as a space.

Let's take the example above, searching all items with "shirt" in their name. First, here's the form version, activated by clicking a submit button.

<form method="GET" action="%HZU_MAIN"> <input type="hidden" name="SEARCH_COMP" value="CONTAINS"> <input type="hidden" name="SEARCH_KEY_NAME" value="shirt"> <input type="submit" name="SUBMIT_ACTION_SEARCH" value="Find Shirts"> </form>

By using a form method of GET as shown above and submitting the form, you'll actually have the link you want in your browser location window. You generally don't want to use a GET form method except for instructive or debugging purposes as in this case, for the very reason that the form field names and values are visible in the URL as opposed to being passed behind the scenes and "out of band" by your browser.

Next, here's the same thing as a link.

<a href="%HZU_ACTION=search&SEARCH_COMP=CONTAINS&SEARCH_KEY_NAME=shirt"> Find Shirts</a>

It's just that easy! At its simplest, a form which requires no user input can be transformed into a link simply by taking all of the input fields and pasting their name=value pairs after your CGI URL, separated by an ampersand.

Anatomy of a Search

So, what actually happens when you submit a search action? Hazel reads the products file line-by-line and finds the products matching the given query. When she has them all, she writes out a history of where to find each "page" of matches, according to the SEARCH_MAXHITS specified.

If there were no matches, Hazel serves the hazel-cat/templates/search/failed.html template. If there were matches, she serves the hazel-cat/templates/search/matches.html template.

You can specify an alternate template to display by sending a TEMPLATE field along with your search. It should specify a filename off your hazel-cat/templates/custom directory. Before version 3.397, Hazel always used that template, even if the match failed to produce any results. As of 3.397, she'll ignore the template if matches fail (using the standard failed template instead), unless you've specified CUSTOM_SEARCH_FAILED:1 in hazel.config.

As of version 3.359, another way to customize matches output is to give an MTEMPLATE field to all products you'd like to use a certain template. If a page of matches consists of products with the same MTEMPLATE field value, Hazel will use that value as the custom template, assumed to be based off your hazel-cat/templates/custom directory.

Limitations

Here are a few things Hazel's search engine won't do.

You can't use "grouping" in your search logic. For example, you can't search for anything with a name containing "spoon" AND a description containing "silver" OR "gold". You could use "+NAME:SPOON ?DESC:SILVER ?DESC:GOLD", which would match anything with "spoon" in the name, regardless of the other two specs, since they're optional. You could use "+NAME:SPOON +DESC:SILVER", which would match only those with "spoon" in the name and "silver" in the description. However, you can't use something like "+NAME:SPOON +(?DESC:SILVER ?DESC:GOLD)", since Hazel doesn't recognize parenthetical matches.

You can't use wildcards, regular expressions or other types of pattern-matching in a search spec.

We'll add more as they're pointed out to us, and remove them as we integrate them into the search engine.