As mentioned above, CatalogSearchFormHandler
provides four different types of searching:
keyword searches
text searches
hierarchical searches
advanced searches
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 Using the 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:
RepositoryValues
determines possible values for only a single item type at a time, while thepropertyValuesByType
property works with multiple item types at the same time.RepositoryValues
can look up values for any property of a repository item, whilepropertyValuesByType
works with only the properties specified in the form handler’sadvancedSearchPropertyNames
property.RepositoryValues
works anywhere in a JSP, while thepropertyValuesByType
property is only available within search forms you construct using theSearchFormHandler
class.