Results cartridges

The following sections provide an overview of the configuration models for features that display search results in the reference implementation.

The Results List cartridge displays search and navigation results in a list view.

The response model for this cartridge is ResultsList, which contains a list of Record objects and SortOptionLabel objects that enable the end user to select from a set of pre-defined sort orders.

The order of records returned by the MDEX Engine is determined by a sort key or relevance ranking strategy depending on the type of query that returns the results.

Relevance ranking is applied when the query includes a text search. Record sorting is applied to all other queries including navigation queries. The sort options that are available to the end user in the application represent static sort orders that are not based on relevance to any search terms.

Record boost and bury is a feature that enables fine-grained re-ordering of records within search or navigation results. With record boost, you can assign records to ranked strata, with those in the highest stratum being shown first, those in the second-ranked stratum shown next, and so on. With record bury, you can assign records to strata that are ranked much lower relative to others. This boost/bury mechanism therefore lets you manipulate ranking of returned record results in order to promote or push certain records to the top or bottom of the results list. The records in each stratum are defined as a set of specific records or a navigation state that the records must satisfy. A record is assigned to the highest stratum whose definition it matches, so boosting takes precedence over burying. Record boost and bury apply regardless of whether the records returned are the results of a search or navigation query.

The core Results List cartridge enables the content administrator to specify one set of records to boost and one set of records to bury. Boost and bury are applied to the result list before any additional sorting or relevance ranking modules. For more information about record boost and bury, refer to the MDEX Engine Developer's Guide.

The Results List configuration model allows you to configure the number and sorting of records returned by a search or navigation query. Additionally, it includes whyMatchEnabled and whyRankEnabled properties that can be used for debugging the set of records returned for a query.

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

Property name

Description

recordsPerPage

An integer that controls the number of results to display per page. This value can be set using Nrpp URL parameter.

recordDisplayFieldName

A String that specifies the field that stores the record's logical name.

sortOption

An enumerated list of sort options on the results list available to the site visitor. Each item in this list is a SortOptionConfig with the following properties:

You can set this value via the Ns URL parameter.

sortRequestParameter

A String that specifies the selected Sort.

includePrecomputedSorts

A Boolean that specifies whether to return precomputed sorts. Defaults to false. If you do not set this to true, any calls to the getPrecomputedSorts() method return an empty list.

relRankStrategy

(Optional) The Relevance Ranking Strategy. If you specify a Relevance Ranking Strategy without setting relRankTerms, relRankKey, or relRankMatchMode, your Relevance Ranking strategy will apply to the results from the current search filter. This setting is ignored if an end user explicitly selects a sort.

relRankKey

(Optional) The Relevance Ranking key to use with the selected Relevance Ranking strategy. This can be a search interface, dimension, or property set in the MDEX Engine. You must set a relRankStrategy and relRankTerms if you specify a value for this property.

relRankTerms

(Optional) Relevance Ranking terms, delimited by a + sign. These can be different from the terms in the search filter. You must set a relRankStrategy and relRankKey if you specify a value for this property.

relRankMatchMode

(Optional) The match mode that determines the subset of results to apply Relevance Ranking to. You must set a relRankStrategy if you specify a value for this property.

boostStrata

An ordered list of CollectionFilters that enable items to be boosted to the top of the results list. This setting is ignored if an end user explicitly selects a sort.

buryStrata

An ordered list of CollectionFilters that enable items to be buried at the bottom of the results list. This setting is ignored if an end user explicitly selects a sort.

subRecordsPerAggregateRecord

The number of sub-records to return for any aggregated records in the results list. This property should have one of the following values:

The default value is ONE. For best performance, Oracle recommends that you use ZERO or ONE.

offset

An integer record offset for the result list. This property defaults to 0 and is used for paging. This value can be set using No URL parameter.

includeDerivedProperties

For aggregated records, returns all derived properties to the end user. Defaults to true.

includeSnippetedProperties

For aggregated records, returns all snippeted properties to the end user. Defaults to true.

includeGeoDistanceProperties

For aggregated records, returns all geodistance properties to the end user. Defaults to true. Geocode properties are not calculated by default by MDEX . You must specify one or more geo location filters(Nf) or geo distance sorts(Ns) for these properties to be calculated. For information about geocode properties, see the MDEX Engine Developer's Guide.

fieldNames

A list of record fields to pass through from each record to the Record output model of the ResultsListHandler.

subRecordFieldNames

For aggregated records, a list of sub-record fields to pass through from each sub-record to the Record output model of the ResultsListHandler.

whyMatchEnabled

If query debugging features are enabled, this property enables debugging information about why each record matched the search and navigation state. For additional information, see "About query debugging results in the reference application."

whyRankEnabled

If query debugging features are enabled, this property enables debugging information about why each record was ranked in the given order. For additional information, see "About query debugging results in the reference application."

Note

You only need to set the relRankKey, relRankTerms and relRankMatchMode properties if you wish to apply relevance ranking to values other than those specified in the search filter, or to the results of an EQL expression.

Your MDEX Engine configuration for your application allows you to configure which properties and dimensions should display in the results list view, optimize certain properties to use for sorting records, and specify a default sort order.

In the Property and Dimension editors in Developer Studio, you can specify which properties and dimensions are returned for the record with the record list. This configuration can be overridden in the cartridge handler configuration. For more information about configuring the display of properties and dimensions for the record list, refer to the Developer Studio Help.

Although you can sort on any property or dimension at query time, it is also possible to optimize a property or dimension for sorting in Developer Studio. This controls the generation of a precomputed sort, which you can retrieve on the ResultsListConfig object by using the getPrecomputedSorts() method. For more information about precomputed sorts, refer to the MDEX Engine Developer's Guide.

You can specify the default sort order for records as a flag in Dgidx. For more information about Dgidx flags and sorting, refer to the MDEX Engine Developer's Guide.

The Deployment Template configuration for the Discover Electronics reference application does not specify a default sort key.

The Results List cartridge handler extends the NavigationCartridgeHandler. The application-wide default configuration in the Assembler context file specifies default sort options, relevance ranking strategy, and record and sub-record properties to pass through to the cartridge handler response model. It also allows you to enable or disable debugging features if query debugging features are enabled.

The cartridge handler uses a contentItemInitializer to merge the layered configuration. The included requestParamMarshaller bean enables URL request-based configuration for the cartridge.

The Results List template allows a content administrator to configure the main results of a search or navigation query based on the site visitor's filter state. Configuration options include sort order, boost/bury, and number of records to display per page.

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

End user configuration is passed to the configuration model as URL parameters. This allows application end users to specify how records should be displayed and sorted in order to customize their navigation experience.

For most of the properties on the configuration model, the cartridge renderer in the reference implementation respects the values set at the cartridge handler or template level. The offset value is used to control paging display.

Property

URL Parameter

Description

recordsPerPage

Nrpp

The cartridge renderer uses this property to enable an application end user to set their own limit on records to display per page.

sortOption

Ns

This parameter enables you to override sort options on a per-query basis.

offset

No

This parameter enables you to control record display when paging.

relRankKey

Nrk

(Optional) The Relevance Ranking key. You must set a relRankStrategy on the cartridge to use this parameter. You must also specify relRankTerms.

relRankTerms

Nrt

(Optional) Relevance Ranking terms, delimited by a + sign. You must set a relRankStrategy on the cartridge to use this parameter. You must also specify a relRankKey.

relRankMatchMode

Nrm

(Optional) The match mode that determines the subset of results to apply Relevance Ranking to. You must set a relRankStrategy, relRankKey, and relRankTerms if you specify a value for this property.

whyMatchEnabled

whymatch

If query debugging is enabled for the reference application, this property enables you to include record matching information about a per-query basis, rather than at the cartridge handler level.

whyRankEnabled

whyrank

If query debugging is enabled for the reference application, this property enables you to include record ranking information about a per-query basis, rather than at the cartridge handler level.

Note

The Nrk, Nrt, and Nrm parameters take precedence over any relevance ranking declaration in the Ntk, Ntt, and Ntx parameters.

The Assembler can return snippets (an excerpt from a record property that contains the user's search terms and the surrounding context) for display in results lists.

Snippeting is configured as part of a search interface. You can enable snippeting on one or more properties in a search interface, typically properties that contain multiple lines of text.

To enable snippeting in record results:

  1. Enable snippeting on one or more properties in the relevant search interface.

    For more information about configuring snippeting, see the MDEX Engine Developer's Guide.

  2. In the Results List response model configuration, specify the property includeSnippetedProperties, as in the following example: 

      <bean id="resultsListDefaultConfig" scope="prototype" class="com.endeca.infront.cartridge.ResultsListConfig">
  	 <property name="includeSnippetedProperties" value="true" />
                           <property name="includeDerivedProperties" value="true" />
    <property name="fieldNames">
  		<list>
  			<value>product.id</value>
  			<value>product.code</value>
  			<value>product.name</value>
  			<value>product.brand.name</value>
  			<value>product.short_desc</value>
  			<value>product.price</value>
     <value>product.img_url_thumbnail</value>
					<value>product.review.avg_rating</value>
     <value>product.review.count</value>
  		</list>
  	</property>  
  	<!-- additional elements omitted from this example -->
  </bean>

The snippet is returned as a string property on the response model for each record for display by the renderer.

Copyright © Legal Notices