Search cartridges

The Discover Electronics application includes reference implementations of several commonly-used search features. The configuration models for these features are described in the following section.

The Search Box cartridge enables the site visitor to enter search terms and view record results. If dimension search is enabled, dimension search results may also be displayed. A content administrator can configure Search Box behavior such as whether to apply search adjustments or display auto-suggest search results.

The response model for this cartridge is SearchBox.

The Search Box cartridge does not make use of a configuration model or a cartridge handler; properties specified in the cartridge template and in the end user's search request are passed through to the renderer.

Because the Search Box enables keyword search for records and dimension values, most search configuration affects the behavior of this cartridge. This section focuses on record search configuration.

The main aspects of search-related configuration that can be updated without re-indexing are the search interfaces for an application. Search interfaces specify a collection of properties and dimensions against which text searches are performed, and may also specify a default relevance ranking strategy.

The properties and dimensions within a search interface must be enabled for record search as part of the data ingest process.

Search results are also affected by thesaurus configuration that a content administrator can specify in Workbench.

For information about creating search interfaces, and enabling properties and dimensions for search, refer to the Oracle Commerce Workbench User's Guide.

Aspects of search behavior that must be specified at index time include stop words, stemming, and search characters.

For information about configuring these features, refer to the Oracle Commerce MDEX Engine Developer's Guide.

The Search Box cartridge does not include a configuration model or a cartridge handler; instead, template configuration is passed through to the cartridge renderer.

The Search Box cartridge template calls the typeahead service, which is configured separately.

The Search Box cartridge template includes the following configurable pass-through property:

Property name

Description

minAutoSuggestInputLength

This property specifies how many characters a user must type before the typeahead service is started.

Note

If you do not want to provide the option of enabling auto-suggest search results in Experience Manager, remove the properties and editors from the template, and remove the JavaScript module from the component.

Related links

Auto-suggest search results display as the site visitor types in the search box, rather than displaying after the visitor has completed the search. In the Discover Electronics reference application, the Search Box cartridge calls the typeahead service to display auto-suggest search results. The typeahead service must be configured by a content administrator.

A cartridge configuration class "ApplicationFilterStateConfig" represents a dynamic application filter state. This dynamic application filter state should be specified in the service or page definition as a property named "@appFilterState".

Name

Description

languageId

The language id to be used by the request while querying MDEX

autoPhraseEnabled

Auto phrase flag used to tell MDEX whether alternate phrasing should be applied.

typeAhead

Specifies whether typeahead should be turned on in the engine for record and dimension searches. If true, dgraph will treat this query as a typeahead use case, and rewrites the query based on the language id of the query.

rollupKey

The key to be used by MDEX for aggregate records

securityFilter

Sets a security filter, which is specified using an MDEX record filter string.

recordFilters

The List of record filters to be applied by MDEX

geoFilter

The geo filter to be applied by MDEX

eqlFilter

The EQL expression to be passed to MDEX.


Sample content.xml 

<ContentItem type="Page" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns="http://endeca.com/schema/content/2008"
             xmlns:xavia="http://endeca.com/schema/xavia/2010">
    <TemplateId>TypeaheadService</TemplateId>
    <Name>Typeahead Service</Name>
    <Property name="@appFilterState">
        <ContentItem type="ApplicationFilterStateConfig">
            <Property name="typeAhead">
                <Boolean>true</Boolean>
            </Property>
            <Property name="recordFilters">
                <xavia:List>
                    <String>product.active:1</String>
                </xavia:List>
            </Property>
        </ContentItem>
    </Property>
    <Property name="resultsList">
        <ContentItem type="ResultsList">
            <TemplateId>ResultsList</TemplateId>
            <Property name="recordsPerPage">
                <String>3</String>
            </Property>
        </ContentItem>
    </Property>
</ContentItem>

The Dimension Search Results cartridge displays refinement links based on the names of dimension values that match the search keywords entered by the site visitor.

The dimension search results display in a panel after the site visitor performs the search. These results provide suggestions for additional navigation refinements based on the search terms.

The response model for this cartridge is DimensionSearchResults. It contains a list of DimensionSearchGroup objects that in turn contain dimensionSearchValues that provide refinement links.

The Dimension Search Results cartridge configuration model controls the number, ranking, and display of returned results.

The configuration model for this cartridge is DimensionSearchResultsConfig. It includes the following properties:

Property name

Description

enabled

Enables or disables the display of returned dimension refinements. By default, this property is false. It is enabled via URL request by setting the Dy URL parameter to 1.

maxResults

Specifies the maximum number of dimension value results across all dimensions to display.

maxResultsPerDimension

Specifies the maximum number of dimension values to display per dimension.

dimensionList

Specifies the dimensions on which to perform dimension search. The results display based on the order in which the dimensions are specified, up to the maximum number of suggestions.

showCountsEnabled

Specifies whether to display refinement counts in dimension search results.

relRank

Optional. Specifies a relevance ranking string to use for dimension search, such as "first,static(nbins,desc)". If you do not set this property, dimension value relevance ranking is set to the default (alpha, numeric, or manual) defined in the application's evaluator.properties file.

Different aspects of dimension search can be configured on a global or per-dimension basis.

You can specify global dimension search behavior in the Dimension Search Configuration editor in the Oracle Commerce Workbench. Oracle recommends enabling wildcard search for dimensions, especially if you are using the Auto-Suggest Dimension Search cartridge or the Dimension Value Boost-Bury editor. Wildcard search enables partial matches to be returned for searches in addition to full word matches (for example, a search for "pink" would also return "gray/pink") which is useful for displaying suggestions while the user is typing search terms.

Additional options include whether to return only the highest ancestor dimension value, and whether to return inert dimension values in dimension search results. For more information about global dimension configuration, refer to the Oracle Commerce Workbench User's Guide.

You can configure dimension-specific search behavior in the Dimension editor in Oracle Commerce Workbench. This includes whether to search across the entire dimension hierarchy rather than only individual dimension values and also enables you to specify dimension value synonyms to be used for search. For more information about per-dimension configuration, refer to the Oracle Commerce Workbench User's Guide.

The Dimension Search Results cartridge handler extends the NavigationCartridgeHandler.

The cartridge handler uses the DimensionSearchResultsConfigInitializer to merge the layered configuration. The included requestParamMarshaller bean enables URL request-based configuration for the cartridge, which is required for dynamically enabling the feature.

The Dimension Search Results cartridge template allows a content administrator to configure how many results should be displayed to the end user, and how they should display. The cartridge template also includes two pass-through properties that are passed directly to the cartridge renderer.

The Dimension Search Results cartridge template allows a content administrator to configure the following properties on the configuration model:

In addition, the cartridge template includes the following pass-through properties:

Property name

Description

title

Optional. A header that displays above the dimension search results.

displayImage

If set to true, a thumbnail image displays next to each dimension value. The URL of the image must be the value of a dimension value property named img_thumbnail_url.

Note

If there is no such property on dimension values in the data set, remove this option and its associated editor from the template to disable this feature.

The display of the Dimension Search Results cartridge on a page is controlled by setting the value of the enabled property on the cartridge configuration model at runtime via the Dy URL parameter.

The cartridge renderer in the reference implementation sets the Dy parameter to 1 in all cases. While this is equivalent to setting the property to true in the cartridge handler configuration, or as a non-editable property in the cartridge template, the intent is to demonstrate where the logic belongs in the application.

Property name

URL Parameter

Description

enabled

Dy

Enables or disables the display of returned dimension refinements. Setting Dy=1 sets the property to true.

Search adjustments include automatic spelling correction, automatic phrasing, and Did You Mean functionality.

The response model for this cartridge is SearchAdjustments.

The behavior of the spelling correction and Did You Mean features are configured at the MDEX Engine level. The Search Adjustments cartridge enables content administrators to specify whether or not search adjustments messaging displays on a page; it does not have any configuration options in Experience Manager.

The Search Adjustments cartridge configuration model enables you to enable or disable automatic phrasing and automatic spelling correction. If query debugging features are enabled in your application, you can also enable or disable debugging information about Word Interpretation.

The configuration model for this cartridge is SearchAdjustemntsConfig. It includes the following properties:

Property name

Description

phraseSuggestionEnabled

Specifies whether to enable automatic phrasing. Defaults to true. Set via URL request by setting the Ntp URL parameter to 1.

spellSuggestionEnabled

Specifies whether to enable automatic spelling correction. Defaults to false. Set via URL request by setting the Nty URL parameter to 1.

showWordInterp

If query debugging features are enabled, this property enables debugging information about word or phrase subsitutions as a map that can be accessed via SearchAdjustments.getInterpretedTerms(). For additional information, see "About query debugging results in the reference application."

Search adjustments features are configured at indexing and at Dgraph startup.

You can specify a list of phrases to be automatically applied to text search queries in the Oracle Commerce Workbench. For more information about configuring automatic phrasing, refer to the MDEX Engine Development Guide.

You can configure the constraints on the spelling dictionaries for record search and dimension search in the Spelling editor in Oracle Commerce Workbench. These settings determine the size of the spelling dictionary that is generated at indexing time. Larger spelling dictionaries lead to slower performance of spelling correction at query time; setting more restrictive constraints on the contents of the spelling dictionary can lead to improved query performance. For more information about tuning the size of the spelling dictionary, refer to the Performance Tuning Guide.

You specify the spelling mode as a flag to Dgidx. Generally, applications that only need to correct normal English words can enable just the default Aspell module. Applications that need to correct international words, or other non-English/non-word terms (such as part numbers) should enable the Espell module. For more information about spelling modes and the associated Dgidx flags, refer to the MDEX Engine Development Guide.

The Deployment Template application configuration for the Discover Electronics reference application has spelling correction and Did You Mean enabled as in the following example: 

<!--
  ########################################################################
  # Dgidx
  #
-->
<dgidx id="Dgidx" host-id="ITLHost">
  <properties>
    <property name="numLogBackups" value="10" />
    <property name="numIndexBackups" value="3" />
  </properties>
  <args>
    <arg>-v</arg>
    <arg>--compoundDimSearch</arg>
  </args>
  <log-dir>./logs/dgidxs/Dgidx</log-dir>
  <input-dir>./data/forge_output</input-dir>
  <output-dir>./data/dgidx_output</output-dir>
  <temp-dir>./data/temp</temp-dir>
  <run-aspell>true</run-aspell>
</dgidx>

You enable spelling correction and Did You Mean through Dgraph flags. Additional Dgraph flags provide advanced tuning options for the spelling adjustment features that affect performance and behavioral characteristics, such as the threshold for the number of hits at or above which spelling corrections or Did You Mean suggestions are not generated. For more information on Dgraph flags for search adjustment tuning, refer to the MDEX Engine Development Guide.

Note

Auto-correct should be relatively conservative. You only want the engine to complete the correction when there is a high degree of confidence. For more aggressive suggestions, it is best to use Did You Mean.

The Deployment Template application configuration for the Discover Electronics reference application has spelling correction and Did You Mean enabled as in the following example: 

<!--
  ########################################################################
  # Global Dgraph Settings - inherited by all dgraph components.
  #
-->
<dgraph-defaults>
  <properties>
    <!-- additional elements removed from this example -->
  </properties>
  <directories>
    <!-- additional elements removed from this example -->
  </directories>
  <args>
    <arg>--threads</arg>
    <arg>2</arg>
    <arg>--whymatch</arg>
    <arg>--spl</arg>
    <arg>--dym</arg>
    <arg>--dym_hthresh</arg>
    <arg>5</arg>
    <arg>--dym_nsug</arg>
    <arg>3</arg>
    <arg>--stat-abins</arg>
  </args>
  <startup-timeout>120</startup-timeout>
</dgraph-defaults>

The Search Adjustments cartridge handler extends the NavigationCartridgeHandler. The application-wide default configuration in the Assembler context file allows you to enable or disable the word interpretation debugging feature.

The cartridge handler uses a contentItemInitializer to merge the layered configuration. The included requestParamMarshaller bean enables URL request-based configuration for the cartridge, which is required for dynamically disabling or enabling automatic phrase suggestions and spelling correction.

Related links

The cartridge template for the Search Adjustments cartridge does not include any configurable properties. A content administrator can add the cartridge to a page in order to enable the display of Search Adjustments, but cannot otherwise configure cartridge behavior.

Automatic phrasing and spelling correction are controlled by setting the value of their respective properties on the cartridge configuration model at runtime via the Ntp and Nty URL parameters.

The cartridge renderer in the reference implementation sets both parameters to 1 in all cases. While this is equivalent to setting the properties in the cartridge handler configuration, or in the cartridge template, the intent is to demonstrate where the logic belongs in the application.

Property name

URL Parameter

Description

phraseSuggestionEnabled

Ntp

Specifies whether to enable automatic phrasing.

spellSuggestionEnabled

Nty

Specifies whether to enable automatic spelling correction.

You can configure the MDEX Engine to consider certain combinations of words in a text search as a phrase search and specify whether to apply phrasing automatically to a site visitor's text search queries.

The high level steps for enabling automatic phrasing are:

You enable the MDEX Engine to compute phrases that can be applied to a site visitor's text search by creating a phrase dictionary. For information about creating a phrase dictionary, refer to the section on Automatic Phrasing in the MDEX Engine Developer's Guide.

You can configure the default behavior of the Assembler application as to whether to automatically rewrite a text search as a phrase search or keep it as a search for individual keywords using the following property on the Filter State object:

Property

Description

autoPhraseEnabled

If set to true, instructs the MDEX Engine to compute phrases that can be applied to a text search and automatically rewrite the query using the phrased version. Automatic phrasing is enabled by default.

The autoPhraseEnabled setting on the default Filter State can be overridden at query time using the URL parameter autophrase. If the value of autophrase is 1, then computed phrases are automatically applied to the query. If the value is 0 then phrases may still be computed, but are not automatically applied to the query.

The Filter State configuration in the Assembler context file for the Discover Electronics reference application is shown below: 

<bean id="navigationStateBuilder" scope="request"
    class="com.endeca.infront.navigation.url.UrlNavigationStateBuilder">
    <!-- additional elements removed from this example -->
                        <property name="defaultFilterState">
        <bean scope="singleton" class="com.endeca.infront.navigation.model.FilterState">
            <property name="rollupKey" value="product.code" />
            <property name="autoPhraseEnabled" value="true" />
            <!-- <property name="securityFilter" value="" /> -->
            <!-- <property name="languageId" value="en" /> -->
        </bean>
    </property>
    <!-- additional elements removed from this example -->
</bean>

For Oracle Commerce Experience Manager, if your application contains multiple sites, Oracle recommends using a filterState.xml file instead of the Filter State configuration in the Assembler context file. For example, a filterState.xml file in /pages/DiscoverElectronics/ might contain the following autophrase property: 

<Item class="com.endeca.infront.navigation.model.FilterState" xmlns="http://endeca.com/schema/xavia/2010">
 <Property name="autoPhraseEnabled">
     <Boolean>true</Boolean >
 </Property>
</Item>

Whether automatic phrasing is applied or not, you can specify whether to return a "Did You Mean" link for the alternate version using the Nty URL parameter. For example, if phrasing was automatically applied, the Did You Mean suggestion would provide a link to the unphrased version of the query, and vice versa. If the value of Nty is 1, then the Assembler returns suggestions for the alternate form of the query. If the value is 0, no suggestions are returned.

Note

The Nty parameter controls Did You Mean suggestions for regular text search as well as for automatic phrasing.

In the Discover Electronics application, the default behavior is to automatically apply phrases to text search queries and to return the unphrased version as a search suggestion.

In this scenario, autoPhraseEnabled is set to true on the default Filter State object, and the Search Box cartridge sets Nty=1 on the text search query. The user has two choices:

These outcomes are summarized in the following table:

User action

Autophrase setting (Ntp)

Did You Mean setting (Nty)

Result

Initial search

true

Nty=1

Phrase is automatically applied to the text search. A Did You Mean suggestion is offered for the unphrased version.

Select Did You Mean suggestion

Ntp=0

Nty=0

Phrase is not applied to the search. No suggestion is offered.

Make another follow-on selection

true

Nty=0

Phrase continues to be automatically applied. Suggestions are no longer offered.

You can configure the application not to apply phrases by default, but to return phrases as a search suggestion.

In this scenario, autoPhraseEnabled is set to false on the default Filter State object, and the Search Box cartridge sets Nty=1 on the text search query. The user has two choices:

These outcomes are summarized in the following table:

User action

Autophrase setting (Ntp)

Did You Mean setting (Nty)

Result

Initial search

false

Nty=1

Phrase is not applied to the text search. A Did You Mean suggestion is offered for the phrased version.

Select Did You Mean suggestion

Ntp=1

Nty=0

Phrase is automatically applied to the search. No suggestion is offered.

Make another follow-on selection

false

Nty=0

Text search continues to be treated as individual keywords instead of as a phrase. Suggestions are no longer offered.

Content administrators can configure keyword redirects that redirect a front-end user to a new page if the user's search terms match the set keyword.

When an end user enters a search term that matches a keyword redirect, the Assembler returns the redirect URI with the response model. The Assembler response can be limited to the redirect URI, or it can also return the results for the user's search term.

The content administrator specifies a search term, match mode, and redirect URI on the Keyword Redirects page in Workbench.

The Assembler API includes a RedirectAwareContentIncludeHandler that implements keyword redirect functionality.

The cartridge handler takes the following two properties:

The cartridge handler configuration in the Assembler context file for Discover Electronics is shown below: 

<!--
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    ~ BEAN: CartridgeHandler_ContentInclude
    ~ Used by the assembler service when keyword redirects are not enabled
-->
<bean id="CartridgeHandler_ContentInclude" 
  class="com.endeca.infront.content.ContentIncludeHandler"
  scope="prototype">
    <property name="contentSource" ref="contentSource" />
    <property name="siteState" ref="siteState"/>
				<property name="userState" ref="${user.state.ref}"/>
</bean>

<!--
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    ~ BEAN: CartridgeHandler_RedirectAwareContentInclude
    ~ For root calls to the assembler when keyword redirects are desired
-->
<bean id="CartridgeHandler_RedirectAwareContentInclude" 
  class="com.endeca.infront.cartridge.RedirectAwareContentIncludeHandler"
  scope="prototype">
    <property name="contentSource" ref="contentSource" />
    <property name="contentBroker" ref="contentRequestBroker" />
    <property name="navigationState" ref="navigationState" />
    <property name="defaultFullAssembleOnRedirect" value="false"/>
    <property name="siteState" ref="siteState"/>
				<property name="userState" ref="${user.state.ref}"/>
</bean>

Note

The redirect-aware version of the cartridge is included in the Navigation JAR rather than the core Assembler JAR because it relies on keyword redirects, which are interpreted by the MDEX Engine. The standard Content Include cartridge and classes do not have this dependency, and are packaged with the core JAR file.

You can override the default settings for the fullAssembleOnRedirect or redirectCollection properties by setting new values in the content XML that is retrieved by the RedirectAwareContentIncludeHandler.

The primary use case for setting these properties on content XML is for deployments running the Assembler service. Keyword redirects are programatically enabled in the service, so by default the feature is explicitly disabled for services where it does not apply (Dimension Search and Record Details) by including an element in the content XML that sets redirectCollection to a null value.

Note

If you are creating your Assembler application in Java, you can disable keyword redirects by using the ContentInclude class instead of RedirectAwareContentInclude for those services where you wish to disable the feature.

The Assembler service in the Discover Electronics application implements the com.endeca.infront.assembler.servlet.AbstractAssemblerServlet abstract class. Keyword redirect configuration is configured in the application's web.xml file.

The JSON and XML servlets in the Discover Electronics reference application are configured in reference\discover-service\WEB-INF\web.xml: 

<servlet>
    <servlet-name>JsonAssemblerServiceServlet</servlet-name>
    <servlet-class>com.endeca.infront.assembler.servlet.spring.SpringAssemblerServlet</servlet-class>
    <init-param>
         <param-name>assemblerFactoryID</param-name>
         <param-value>assemblerFactory</param-value>
    </init-param>
    <init-param>
         <param-name>responseWriterID</param-name>
         <param-value>jsonResponseWriter</param-value>
    </init-param>
    <init-param>
        <param-name>enableKeywordRedirects</param-name>
        <param-value>true</param-value>
    </init-param>
</servlet>

When the application queries the Assembler service, the redirect URI is returned as part of the response.

In order to execute a redirect, an application must include logic for handling the URI components returned from the Assembler. You must use the RedirectAwareContentInclude class for any content items that require keyword redirect functionality.

The assemble.jsp service uses the RedirectAwareContentInclude class to enable keyword redirects, as shown below: 

                        <%@page import="com.endeca.infront.cartridge.RedirectAwareContentInclude"%>

...

AssemblerFactory assemblerFactory = (AssemblerFactory)webappCtx.getBean("assemblerFactory");
Assembler assembler = assemblerFactory.createAssembler();

//Retrieve the content for the given content uri
ContentItem contentItem = new RedirectAwareContentInclude("/browse" + contentUri);

// Assemble the content
ContentItem responseContentItem = assembler.assemble(contentItem);

When an end user enters a search term that matches a keyword redirect configured in Workbench, the Assembler response includes a ContentItem with the necessary information for creating a destination URI.

The following example shows a JSON response in an Experience Manager implementation from the Guided Search service when fullAssembleOnRedirect is false: 

{
    endeca:siteRootPath: "/pages",
    endeca:contentPath: "/services/guidedsearch",
    endeca:assemblerRequestInformation:
    {
        @type: "AssemblerRequestEvent",
        endeca:assemblyStartTimestamp: 1341943119538,
        endeca:assemblyFinishTimestamp: 1341943119546,
        endeca:contentPath: "/guidedsearch",
        endeca:requestId":"140252272098164091",
        endeca:sessionId: "FF9D21355A3CBB9DFF75614DD7D2948D",
        endeca:siteRootPath: "/services"
    },
    endeca:redirect:
    {
        @type: "Redirect",
        link: {
            @class: "com.endeca.infront.cartridge.model.UrlAction",
            url: "/browse/cameras/_/N-25y6"
        }
    }
}

The keyword redirect information is included in the ContentItem with the key endeca:redirect. The value specifies an Action object with the destination URI, which may be either relative or absolute.

In an Oracle Commerce Guided Search implementation (without Experience Manager), the site root path and content path in the JSON response would be the following: 

endeca:siteRootPath: "/services",
    endeca:contentPath: "/guidedsearch",

You must retrieve and use the information from the Assembler response in your application to execute a keyword redirect. In the Discover Electronics reference application, this is accomplished in the assemble.jsp service: 

                           <%@ taglib prefix="util" uri="/WEB-INF/tlds/functions.tld"  %> 
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>

...

// Assemble the content
ContentItem responseContentItem = assembler.assemble(contentItem);

request.setAttribute("component", responseContentItem);
request.setAttribute("rootComponent", responseContentItem);

Map map = (Map) request.getAttribute("component");
if (map.containsKey("endeca:redirect")) {
    request.setAttribute("action", ((ContentItem) map.get("endeca:redirect")).get("link"));
    %>
    <c:redirect url="${util:getUrlForAction(action)}"/>
    <%
}
...

For more information about Action objects in an Assembler application, see "Working with Application URLs," or consult the Assembler API Reference (Javadoc).

Copyright © Legal Notices