Overview of the navigation cartridge configuration models

The behavior of the navigation cartridges depends on multiple sources of configuration. The data from these source is combined into a configuration model within the initialize() method of each associated cartridge handler in the Assembler.

Navigation cartridge configuration falls into the following categories, in ascending order of priority:

Additionally, while it is not represented in the cartridge configuration model, configuration in the MDEX Engine impacts the behavior of the navigation cartridges.

Request-based configuration overrides the cartridge instance configuration, which overrides the cartridge-level defaults, which override default feature behavior configured in the MDEX Engine.

The core cartridges typically consist of a strongly typed configuration model, a response model, and a cartridge handler that processes the configuration model into the response model. By convention, they are named as follows:

Class name

Description

<CartridgeName>Config

The configuration model for the cartridge. For the core cartridges, the properties of this class represent all the configuration parameters that the cartridge handler needs to do its processing. It does not include configuration that can only be specified in the MDEX Engine or pass-through properties that are used by the reference application renderers without any modification by the cartridge handler.

<CartridgeName>Handler

The handler that processes a cartridge. The core cartridge handlers are responsible for layering the default configuration, instance configuration, and request-based configuration during processing.

<CartridgeName>

The response model produced by the cartridge handler. Cartridge response models may include objects that are reused among cartridges. For example, the ResultsList and RecordSpotlight both contain Record objects.

For details about the implementations of these classes for specific cartridges, refer to the Assembler API Reference (Javadoc).

You can specify default configuration settings for the navigation cartridges in the reference implementation by adding values to the cartridge handler configuration in the Spring context file.

Cartridge handler configuration (including default configuration values) is specified as part of the Spring context file for the Assembler. In the Discover Electronics application, this is defined in WEB-INF/assembler-context.xml.

You specify the cartridge handler for a specific cartridge by defining a bean whose ID follows the format CartridgeHandler_<CartridgeType>, where the <CartridgeType> is the id of the corresponding cartridge template. For example, the cartridge handler for the Breadcrumbs cartridge is defined in the CartridgeHandler_Breadcrumbs bean. You can map more than one cartridge to the same cartridge handler.

Typically, you specify the default configuration for a cartridge by defining a contentItemInitializer property within the cartridge handler. The value of this property is a bean whose class implements the ContentItemInitializer interface. The core cartridges use the ConfigInitializer class, which provides a default implementation for merging the default, instance, and request-based configuration for a cartridge. Within the contentItemInitializer bean, the defaults property (if defined) must be a bean whose class is a ContentItem representing the cartridge configuration model to use as a default.

For information about the properties available in the configuration model for the core cartridges, refer to the Assembler API Reference (Javadoc) for the relevant configuration model class.

The following shows an example of default configuration for a Record Spotlight cartridge. The defaults property of the ConfigInitializer bean is an instance of RecordSpotlightConfig that has been initialized with a set of default values for the fieldNames property. 

<bean id="CartridgeHandler_RecordSpotlight" 
    class="com.endeca.infront.cartridge.RecordSpotlightHandler"
    parent="NavigationCartridgeHandler" 
    scope="prototype">
    <property name="contentItemInitializer">
        <bean class="com.endeca.infront.cartridge.ConfigInitializer" scope="request">
            <property name="defaults">
                <bean class="com.endeca.infront.cartridge.RecordSpotlightConfig" scope="singleton">
                    <property name="fieldNames">
                        <list>
                            <value>product.name</value>
                            <value>product.brand.name</value>
                            <value>product.price</value>
                            <value>product.min_price</value>
                            <value>product.max_price</value>
                            <value>product.img_url_thumbnail</value>
                            <value>product.review.avg_rating</value>
                        </list>
                    </property>
                </bean>
            </property>
        </bean>
    </property>
</bean>

There are two subcategories of MDEX Engine–level feature configuration: dynamic configuration that can be updated in a running MDEX Engine without re-indexing, and static configuration that must be specified at index time.

Dynamic configuration includes search interfaces, thesaurus, and automatic phrasing. Static configuration includes features such as such as stop words or precedence rules. Updating static configuration requires that you re-run the data ingest process before the changes can take effect. For detailed information about feature configuration in the MDEX Engine, refer to the MDEX Engine Basic Development Guide and the MDEX Engine Development Guide.

In addition, some features depend on certain Dgraph and Dgidx flags to enable or configure their functionality. For information about Dgraph and Dgidx flags, refer to the Oracle Commerce Administrator's Guide.

The content administrator can configure each instance of a cartridge using Experience Manager in Workbench. The cartridge instance configuration is passed in as the argument to the initialize() method of the cartridge handler.

You define which aspects of a cartridge are configurable in Workbench via the cartridge template. Typically this is a subset of the properties in the configuration model. The sample templates provided as part of the Discover Electronics application are intended to cover the majority of use cases.

Cartridge templates for the reference application are included in the reference\discover-data\cartridge_templates directory, or <app dir>\config\cartridge_templates directory for a deployed application.

You can customize the templates for the core cartridges by adding properties to a template in addition to those required by the configuration model. These additional properties can either be processed by a custom cartridge handler implementation or passed through directly to the response model. Some of the templates in the Discover Electronics application define pass-through properties; these are described in the sections on the specific cartridges.

For details about configuring properties and editors in a cartridge template, refer to the "Template Property and Editor Reference" appendix in this guide.

Note

If you have purchased Oracle Guided Search only and do not have Oracle Experience Manager, most of the core cartridges are not available for configuration in Workbench. Of the core cartridges, only the Record Spotlight cartridge is available in Rule Manager. Custom cartridges that use primitive properties only (typically as pass-through properties) can also be configured in Rule Manager. The remaining cartridges can be configured with application-wide default values in the Spring context file for the Assembler.

Related links

For some cartridges, it is appropriate for aspects of their configuration to be overridden at query time. Typically, request-based configuration is specified as URL query parameters.

To enable per-request configuration based on URL parameters, the contentItemInitializer bean of the cartridge handler can specify a requestParamMarshaller bean whose class is RequestParamMarshaller or a subclass. RequestParamMarshaller is a helper class that parses request parameters into properties of the cartridge configuration model.

For information about the URL query parameters that apply to the core cartridges, refer to the Assembler API Reference (Javadoc) for the relevant RequestParamMarshaller subclass. These classes define the URL parameters that the cartridge accepts and their mappings to properties on the configuration model.

Copyright © Legal Notices