ATG Commerce Programming Guide

As mentioned above, CatalogSearchFormHandler provides four different types of searching:

This section describes how to configure a SearchFormHandler component for each of these types of searching.

Keyword Searches

To enable keyword searches in the form handler, set the property doKeywordSearch to true. You can specify the target values to search for by setting the keywords property of the search form handler to an array of strings, or by setting the searchInput property to a string containing one or more words separated by spaces. These values are typically specified by the customer through a form input field. (You can change the separator character used to parse searchInput by setting the form handler’s keywordInputSeparator property.)

You can force the search form handler to convert all keyword inputs to uppercase before searching by setting the toUpperCaseKeywords property to true. Similarly, you can force the form handler to convert keyword inputs to lowercase by setting toLowerCaseKeywords to true instead.

By default, keyword searches look at the keywords property of each catalog item. You can override the default behavior by setting the keywordsPropertyNames property of the form handler in its properties file. You can specify one or more properties to consider in keyword searches, and each of these properties can be either single-valued or multi-valued.

Keyword searches treat single-valued and multi-valued properties differently. If a property specified in keywordsPropertyNames is single-valued (e.g., the property is of type String), the keyword search algorithm uses the QueryBuilder.CONTAINS query to examine each target value and see if it appears anywhere within the property’s current value. For example, if you have a keywordString property whose type is String, and you search for the values red, green, and blue using keyword search, the resulting query is:

keywordString CONTAINS "red"
OR keywordString CONTAINS "green"
OR keywordString CONTAINS "blue"

Since CONTAINS performs a substring match, this query returns true for an item whose keywordString has the value reduced calorie, because reduced contains the string red within it.

However, if a property specified in keywordsPropertyNames is multi-valued (for example., the property is of type String[]), the keyword search algorithm uses the QueryBuilder.INCLUDESANY query to perform a single search for an exact match between any value in the property and any value in the set of search criteria. For example, if you have a keywords property whose type is String[], and you search for the values red, green, and blue using keyword search, the resulting query is:

keywords INCLUDES ANY ["red","green","blue"]

Since INCLUDES ANY searches for an exact match, this query returns false for an item whose keywords are diet and reduced calorie, because red is not an exact match for reduced calorie.

If you specify multiple properties in keywordsPropertyNames, the keyword search generates a query for each property, then combines these queries using the OR operator. This means that if any one of the queries returns true, the item is returned by the search operation.

Text Searches

To enable text searches in the form handler, set the property doTextSearch to true. The target search string is specified by setting the form handler’s searchInput property, typically by the customer entering the value in a form input field. You specify which properties to examine by setting the textSearchPropertyNames property of the form handler. If this property is not set, text searches use a default set of properties that is defined by the repository.

The implementation of text searching is RDBMS-specific and uses the database’s text searching facility, if there is one. If your database supports a full-text search engine, you must configure the search engine properly, and set the repository component’s simulateTextSearchQueries property to false. If a full-text search engine is not available (either because your RDBMS does not support one, or because you do not have a license for the one your RDBMS supports), the SQL repository can simulate full-text searching by using the LIKE operator to determine whether the target value is a substring of any of the text properties being examined. To enable this feature, set the repository component’s simulateTextSearchQueries property to true. Note that although simulated full-text searching is useful for development purposes, performance is unlikely to be adequate for a production server.

By default, the product catalog’s simulateTextSearchQueries is set to true to support full-text searching on the SOLID database that is included with Dynamo. For more information about configuring your database for full-text searching, see the discussion on databases and database access in the ATG Installation and Configuration Guide.

Hierarchical Searches

To enable hierarchical searches in the form handler, set the property doHierarchicalSearch to true. You specify the category to start the search from by setting the form handler’s hierarchicalCategoryId property to the repository id of the category whose descendants you want to find. This property is typically set through a hidden input tag, or specified by the customer through a form input field.

Hierarchical searching requires that each category and product item have a multi-valued property whose value is a complete list of all of its ancestor categories. Hierarchical searching restricts the search results to items whose ancestor categories include the category specified through hierarchicalCategoryId.

Specify the name of the ancestor category property by setting the ancestorCategoriesPropertyName property of the form handler. If you are using the standard catalog schema, each category and product item has an ancestorCategories property whose value is a Set of that item’s ancestor categories The values of these properties can be generated automatically using the component /atg/commerce/catalog/custom/AncestorGeneratorService. If your catalog does not use the default schema, you may be able to configure this component to generate ancestor categories for your catalog items, or you can specify ancestor categories by setting properties manually. See Running the Custom Catalog Maintenance System for more information.

Advanced Searches

To enable advanced searches, set the form handler’s doAdvancedSearch property to true. You then specify the set of properties to search by setting the advancedSearchPropertyNames property. Advanced searches are limited to the set of properties you name here.

Target values are specified for one or more of these properties by adding values to the propertyValues property of the form handler, typically through form input fields. This property is a Dictionary to which you add one key/value pair for each property you want to search. The key is the property name, and the value to search for. For example, to look for items whose color property is set to red, set CatalogSearchFormHandler.propertyValues.color to red. Setting a value to an empty string omits it from the search, and therefore specifies that the property matches any value.

For each property specified in propertyValues, a query is generated based on whether the property is single-valued or multi-valued. For single-valued properties a simple equality test is used. For multi-valued properties an INCLUDES test is generated, so that the query succeeds if any of the property’s values match the target value. If you specify multiple properties, the queries are combined using the AND operator, so all properties must match for the catalog item to be selected.

For example, searching color for a value of red and availableSizes for a value of medium, where color is a single String and availableSizes is an array of Strings, results in the following query:

(color = red) AND (availableSizes INCLUDES medium)

CatalogSearchFormHandler has a property called propertyValuesByType, which is a Dictionary containing one key/value pair for each property named in advancedSearchPropertyValues whose type is either enumerated or RepositoryItem. The key is the name of the property and the value is a Collection of the possible values. The propertyValuesByType property is useful for building forms that allow customers to select, for example, the size of an item, where size is an enumerated property with a set of predefined values like small, medium, and large. The following example illustrates this:

<!-- Create a select field to choose size and a default option -->
Size: <dsp:select bean="SearchHandler.propertyValues.size">

<!-- Create a default choice -->
<dsp:option value="" selected="true"/>Any size

<!-- Now create an option for each defined value for size -->
<dsp:droplet name="ForEach">
 <dsp:param value="SearchHandler.propertyValuesByType.size" name="array"/>
 <dsp:oparam name="output">
 <dsp:getvalueof id="option11" param="element" idtype="java.lang.String">
<dsp:option value="<%=option11%>"/>
  <dsp:setvalue bean="" value="/>
</dsp:getvalueof><dsp:valueof param="element">Unknown size</dsp:valueof>
 </dsp:oparam>
</dsp:droplet>

</dsp:select>

For more examples, see the Sample Catalog that is provided with ATG Commerce. For information on the Sample Catalog and how to run it, see the Reference Applications section of the Introduction in the ATG Commerce Guide to Setting Up a Store.

Another approach to determining the possible values of properties whose type is enumerated or RepositoryItem is to use the servlet bean located at /atg/commerce/catalog/RepositoryValues. This component is an instance of the atg.repository.servlet.PossibleValues class. See the entry for PossibleValues in Appendix B: ATG Servlet Beans in the ATG Page Developer's Guide for a detailed description of this servlet bean.

Note: When running development mode, the /atg/commerce/catalog/RepositoryValues component becomes an instance of atg.commerce.catalog.FilteringCatalogPossibleValues. For more information, see Searching Custom Catalogs in Development Mode.

The RepositoryValues servlet bean returns essentially the same information as the propertyValuesByType property of the CatalogSeachFormHandler class. However, there are some important differences: