oracle endeca commerce: assembler application developer's ......• default • christmas •...

Oracle Endeca CommerceAssembler Application Developer's Guide

Version 3.1.2 • April 2013

ContentsPreface.............................................................................................................................9About this guide.............................................................................................................................................9Who should use this guide............................................................................................................................9Conventions used in this guide...................................................................................................................10Contacting Oracle Support..........................................................................................................................10

Chapter 1: Supporting an Assembler Application.................................11About planning your application sitemap....................................................................................................11About page types........................................................................................................................................12

About page structure and content types..............................................................................................13About mapping pages to services........................................................................................................14Creating a page....................................................................................................................................16

About content collections............................................................................................................................16Content collections example................................................................................................................17Creating a content collection................................................................................................................21About moving content collections........................................................................................................22

Chapter 2: Creating Experience Manager Templates............................23About creating templates.............................................................................................................................23Anatomy of a template................................................................................................................................24Template naming conventions....................................................................................................................25About the template XML schema................................................................................................................25About the type and ID for a template..........................................................................................................26Specifying the description and thumbnail image for a template..................................................................26

About using thumbnail images in Experience Manager.......................................................................27Specifying the default name for a cartridge.................................................................................................27About defining the content properties and editing interface........................................................................28

About template properties....................................................................................................................28About defining the editing interface for properties...............................................................................29

Structural properties....................................................................................................................................31Adding a content item property............................................................................................................31Adding a content item list property.......................................................................................................32About cartridge selectors.....................................................................................................................33

Chapter 3: Managing Experience Manager Templates..........................35Updating Experience Manager templates...................................................................................................35

Troubleshooting problems with uploading templates...........................................................................35Troubleshooting invalid templates.......................................................................................................37

About updating templates............................................................................................................................37About modifying templates that are used by existing pages.......................................................................37About removing templates...........................................................................................................................38

Removing templates from Experience Manager..................................................................................39Retrieving the current templates from Experience Manager.......................................................................40

Chapter 4: Building Applications with the Endeca Assembler............41Assembler dependencies............................................................................................................................41About deploying the Assembler...................................................................................................................41Assembler configuration..............................................................................................................................42

About configuring cartridge handlers...................................................................................................42About configuring the Assembler servlet.............................................................................................46

Invoking the Assembler in Java...................................................................................................................46Invoking the Assembler with a ContentInclude item............................................................................47Invoking the Assembler with a ContentSlotConfig item.......................................................................48

Querying the Assembler Service.................................................................................................................49The Assembler servlet response format..............................................................................................50

About retrieving Assembler results using the packaged services...............................................................50

iii

The Dimension Search Service...........................................................................................................51The Record Details Service.................................................................................................................52The Guided Search Service.................................................................................................................53

About handling the Assembler response....................................................................................................57About rendering the Assembler response............................................................................................58

Assembler event framework reference.......................................................................................................60Creating an event listener....................................................................................................................61About registering an event listener......................................................................................................62

About Assembler error handling..................................................................................................................63

Chapter 5: Working with Application URLs............................................65About application URLs...............................................................................................................................65About Actions..............................................................................................................................................65

Action fields..........................................................................................................................................66About using Actions with the packaged services.................................................................................67

About working with URL parameters...........................................................................................................68About URL configuration in the reference application.................................................................................68

URL formatter configuration.................................................................................................................70About working with canonical links..............................................................................................................72

Chapter 6: Implementing Multichannel Applications............................75Overview of multichannel applications with the Endeca Assembler...........................................................75About creating templates for mobile channels............................................................................................75About device detection in the reference application....................................................................................76

Chapter 7: Configuring Front-End Application Features......................79About configuring application features........................................................................................................79

Feature configuration in the MDEX Engine..........................................................................................80Default cartridge configuration.............................................................................................................80Cartridge instance configuration..........................................................................................................81Request-based configuration...............................................................................................................82

Search features...........................................................................................................................................82Search box...........................................................................................................................................82Auto-suggest search results................................................................................................................84Dimension search results.....................................................................................................................85Search adjustments.............................................................................................................................88Keyword redirects................................................................................................................................93

Guided Navigation features.........................................................................................................................97Refinement menu.................................................................................................................................97Navigation Container..........................................................................................................................101Breadcrumbs......................................................................................................................................102

Results features........................................................................................................................................103Results list..........................................................................................................................................103

Record details features.............................................................................................................................108Record details page...........................................................................................................................108

Content and spotlighting features.............................................................................................................109Record Spotlight.................................................................................................................................109Media Banner.....................................................................................................................................111

Dynamic triggering features......................................................................................................................112About dynamic slots...........................................................................................................................112

Chapter 8: Setting up the Preview Application for Workbench..........115About the preview application...................................................................................................................115

About auditing content using a preview application...........................................................................115About previewing specific devices.....................................................................................................116

About instrumenting your application for preview.....................................................................................118Enabling your preview application.....................................................................................................119Changing the preview application in Workbench...............................................................................121Changing the preview link service.....................................................................................................121Testing your preview application........................................................................................................123

Oracle Endeca Commerceiv

Chapter9:EnablingEndecaQueryLanguageinyourAssemblerapplication.125About Endeca Query Language................................................................................................................125Applying an EQL filter in a Java application..............................................................................................125About configuring an EQL filter using the Nrs URL parameter.................................................................127About configuring a default EQL filter.......................................................................................................127About applying Relevance Ranking to EQL results..................................................................................127About troubleshooting EQL performance..................................................................................................128

Chapter 10: Using an MDEX Engine to Manage Media Assets...........129Interaction between an Endeca application and the media MDEX Engine components..........................129Uploading media content for use in Experience Manager........................................................................131Overview of the reference data application...............................................................................................131

Deploying the media MDEX Engine data application........................................................................133Media MDEX Engine schema definition....................................................................................................134

Chapter 11: Understanding and Debugging Query Results...............137About the query debugging features.........................................................................................................137About enabling query debugging features................................................................................................137URL parameters for query debugging features.........................................................................................138About query debugging results in the reference application.....................................................................138

Chapter 12: Configuring Logging for an Assembler Application.......141About request events................................................................................................................................141About request event adapters...................................................................................................................142

About registering a request event adapter.........................................................................................143Request event adapters in the reference application.........................................................................144

Client side click events..............................................................................................................................144

Appendix A: Template Property and Editor Reference.......................147Editor property mapping reference............................................................................................................147Editor label configuration reference..........................................................................................................150Basic content properties............................................................................................................................151

Adding a string property.....................................................................................................................152About numeric properties...................................................................................................................158Adding a Boolean property................................................................................................................160Adding a list property.........................................................................................................................162Adding an item property.....................................................................................................................163

Adding a group label.................................................................................................................................164Complex property editors..........................................................................................................................165

About the microbrowser.....................................................................................................................165About the Select Records dialog........................................................................................................167About the Dynamic Slot editor...........................................................................................................168Adding a Link Builder.........................................................................................................................171About the Media editor.......................................................................................................................173Adding a Boost-Bury Record editor...................................................................................................180Adding a Guided Navigation editor....................................................................................................181Adding a Dimension Selector.............................................................................................................183Adding a Dimension List editor..........................................................................................................184Adding a Dimension Value Boost-Bury editor....................................................................................185Adding a Dimension Value List editor................................................................................................187Adding an Image Preview..................................................................................................................188Adding a Record List editor................................................................................................................190Adding a Record Stratification editor.................................................................................................192Adding a Rich Text editor...................................................................................................................193Adding a Sort editor...........................................................................................................................195Adding a Spotlight Selection editor....................................................................................................197

Application feature property reference......................................................................................................199

Appendix B: Request Event Attributes.................................................203Base request event attributes....................................................................................................................203Navigation request event attributes...........................................................................................................203

v

Contents

Copyright and disclaimer

Copyright © 2003, 2013, Oracle and/or its affiliates. All rights reserved.

This software and related documentation are provided under a license agreement containing restrictionson use and disclosure and are protected by intellectual property laws. Except as expressly permittedin your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast,modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or byany means. Reverse engineering, disassembly, or decompilation of this software, unless required bylaw for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to beerror-free. If you find any errors, please report them to us in writing.

If this is software or related documentation that is delivered to the U.S. Government or anyone licensingit on behalf of the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integratedsoftware, any programs installed on the hardware, and/or documentation, delivered to U.S. Governmentend users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulationand agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, andadaptation of the programs, including any operating system, integrated software, any programs installedon the hardware, and/or documentation, shall be subject to license terms and license restrictionsapplicable to the programs. No other rights are granted to the U.S. Government.

This software or hardware is developed for general use in a variety of information managementapplications. It is not developed or intended for use in any inherently dangerous applications, includingapplications that may create a risk of personal injury. If you use this software or hardware in dangerousapplications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, andother measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability forany damages caused by use of this software or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may betrademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarksare used under license and are trademarks or registered trademarks of SPARC International, Inc.AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks ofAdvanced Micro Devices. UNIX is a registered trademark of The Open Group.

This software or hardware and documentation may provide access to or information on content,products, and services from third parties. Oracle Corporation and its affiliates are not responsible forand expressly disclaim all warranties of any kind with respect to third-party content, products, andservices. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damagesincurred due to your access to or use of third-party content, products, or services.

vii

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Programwebsite at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Oracle customers have access to electronic support through My Oracle Support. For information, visithttp://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visithttp://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.

Oracle Endeca Commerceviii

Preface

The Oracle Endeca Commerce solution enables your company to deliver a personalized, consistentcustomer buying experience across all channels — online, in-store, mobile, or social. Whenever andwherever customers engage with your business, the Oracle Endeca Commerce solution delivers,analyzes, and targets just the right content to just the right customer to encourage clicks and drivebusiness results.

Oracle Endeca Commerce is the most effective way for your customers to dynamically explore yourstorefront and find relevant and desired items quickly. An industry-leading faceted search and GuidedNavigation solution, Oracle Endeca Commerce enables businesses to help guide and influencecustomers in each step of their search experience. At the core of Oracle Endeca Commerce is theMDEX Engine™, a hybrid search-analytical database specifically designed for high-performanceexploration and discovery. The Endeca Content Acquisition System provides a set of extensiblemechanisms to bring both structured data and unstructured content into the MDEX Engine from avariety of source systems. Endeca Assembler dynamically assembles content from any resource andseamlessly combines it with results from the MDEX Engine.

Oracle Endeca Experience Manager is a single, flexible solution that enables you to create, deliver,and manage content-rich, cross-channel customer experiences. It also enables non-technical businessusers to deliver targeted, user-centric online experiences in a scalable way — creating always-relevantcustomer interactions that increase conversion rates and accelerate cross-channel sales. Non-technicalusers can control how, where, when, and what type of content is presented in response to any search,category selection, or facet refinement.

These components — along with additional modules for SEO, Social, and Mobile channel support —make up the core of Oracle Endeca Experience Manager, a customer experience management platformfocused on delivering the most relevant, targeted, and optimized experience for every customer, atevery step, across all customer touch points.

About this guideThis guide provides an overview of the Endeca Assembler and Experience Manager applicationdevelopment architecture. It uses examples from the Discover Electronics reference application todescribe the configuration and customization tasks developers can perform to implement features intheir own applications.

Who should use this guideThis guide is intended for developers responsible for building applications using the Endeca Assemblerand supporting users of Experience Manager. You should familiarize yourself with the concepts in theOracle Endeca Commerce Concepts Guide and the Oracle Endeca Commerce Getting Started Guidebefore reading this guide.

Conventions used in this guideThis guide uses the following typographical conventions:

Code examples, inline references to code elements, file names, and user input are set in monospacefont. In the case of long lines of code, or when inline monospace text occurs at the end of a line, thefollowing symbol is used to show that the content continues on to the next line: ¬

When copying and pasting such examples, ensure that any occurrences of the symbol and thecorresponding line break are deleted and any remaining space is closed up.

Contacting Oracle SupportOracle Support provides registered users with important information regarding Oracle Endeca software,implementation questions, product and solution help, as well as overall news and updates.

You can contact Oracle Support through Oracle's Support portal, My Oracle Support athttps://support.oracle.com.

Oracle Endeca Commerce Assembler Application Developer's Guide

| Preface10

https://support.oracle.com

Chapter 1

Supporting an Assembler Application

This section covers the supporting constructs that you must create in order to enable an Assemblerapplication.

About planning your application sitemapAn Assembler application consists of a combination of static pages and dynamic pages that containcontent related to an end user's navigation state. Your planned sitemap helps determine what pagesand content collections you should create for your application.

Consider a site with the following structure:

• about• contact• faq

• promotions• christmas• mothersDay

• browse• details

In this case, each of the pages maps directly to a set of content. To separate most of the content outfrom the site structure and support dynamic triggering, the organization of an Assembler applicationis divided into the pages within an application, and the content that populates them:

• pages• about

• contact• faq

• browse• details

• content

• guided navigation• record details• browse pages

default•• christmas• mothers day

• spotlights• top rated• best sellers

In the example above, the promotional Christmas and Mother's Day pages no longer exist as explicitpages. Instead, the content associated with those promotions is stored as available "browse" pageconfigurations that each trigger during a specified date range.

You can refer to the Discover Electronics reference application for a further example of how contentand pages can be separated. When planning your own application, you should consider which locationsin your site are best represented as pages, and which locations consist of triggered content on anexisting page.

About page typesA typical application has several types of pages that may display under different circumstances orcontain different content.

For example, a site may have the following three basic page types:

These pages may differ in the following ways:• They are intended to display in different contexts. The home page displays before the user

has made any selections. The results page displays only when the user has performed somesearch or navigation query. The record detail page displays only when a user has selected aspecific product. These conditions are configured in Experience Manager as triggering criteria.

• They display different types of content. A home page or category page typically displayshigh-level promotions and merchandising. A results page displays a list of record results as wellas additional controls for the user to select additional facets or otherwise refine the search. A recorddetail page displays detailed product information as well as controls for transactions (such as addto cart, wishlist, and so on). These differences in content imply differences in layout, which isconfigured at the template level.

• They are accessed via different URLs. The home page is accessed at the base URL for the site.Search results pages may be accessed at a URL that includes the path /browse/. Record details


Supporting an Assembler Application | About page types12

pages may be accessed at a URL that includes the path /detail/. These URL mappings aretypically achieved by setting up individual services for each page type.

The Discover Electronics reference application includes examples of results pages and a record detailspage.

About page structure and content typesThe logical structure of a page, including the types of content it can contain, is defined in an ExperienceManager template.

Every template defines a content item that can be processed by the Assembler. A page templatedefines a container content item with sections that can be populated with other content items, suchas the following:

Typically, a section represents a physical area on the page, but it can also represent a functionalgrouping, including content that may not be visible to an end user. Each section has an associatedcontent type that determines what kind of content items can be inserted in that section. An applicationmay have multiple cartridges of each type, providing greater flexibility for the content administrator toconfigure the content for a specific page.


13Supporting an Assembler Application | About page types

You can create templates for different page types within your application and define which contenttypes are valid for each type of page. You can create templates for high-level page structures anddifferent layouts for a single page type. Each of the content items that can be inserted into a templateis itself defined by a template, and may be either another container content item or (more commonly)a leaf content item associated with a front end feature.

About mapping pages to servicesYou can map the URL paths of pages in your application to specific services.

Services can be used to set attributes on the incoming request before it is processed by the Assemblerdepending on the type of page being requested, which can control what content is triggered in responseto the request, and the format in which the response is returned.

The following is an example from the WEB-INF\web.xml file for the Discover Electronics referenceapplication, which maps end user requests to /services via a URL redirect and sends them to theapplication controller, WEB-INF\services\assemble.jsp.


Supporting an Assembler Application | About page types14

<servlet> <servlet-name>assemble</servlet-name> <jsp-file>/WEB-INF/services/assemble.jsp</jsp-file> </servlet>

<servlet> <servlet-name>assemble-stats</servlet-name> <jsp-file>/WEB-INF/services/assemble-stats.jsp</jsp-file> </servlet>

<servlet> <servlet-name>autosuggest.json</servlet-name> <jsp-file>/WEB-INF/services/autosuggest-json.jsp</jsp-file> </servlet> <servlet> <servlet-name>link</servlet-name>

 </servlet>

<servlet-mapping> <servlet-name>autosuggest.json</servlet-name> <url-pattern>/servlet/autosuggest.json/*</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>link</servlet-name> <url-pattern>/servlet/link.json/*</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>assemble-stats</servlet-name> <url-pattern>/servlet/stats/*</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>assemble</servlet-name> <url-pattern>/servlet/*</url-pattern> </servlet-mapping>

When a content administrator defines a new application page in the reference application, requestson that page are mapped to the /services servlet. Your application should include similar logic formapping arbitrary pages to a controller, though you may also choose to explicitly define additionalservices for certain pages within your site. Additionally, your UI tier must be able to resolve whateverlinks you expect your content administrators to create. For more information about handling applicationURLs, see "Working with Application URLs."

Related LinksWorking with Application URLs on page 65

Each of the user-facing pages in an Assembler application exists as a page with acorresponding navigation or record state; the combination of the page and its state resultsin a specific set of results or a set of record details. The Assembler API includes an Actionclass for storing these URL components and returning them as part of the output modelproduced by a cartridge handler.


15Supporting an Assembler Application | About page types

Creating a pageThe Content Tree in the left pane of Experience Manager is divided into two sections: Pages andContent. You create pages within the Pages section.

You must deploy and provision your application with the EAC in order to modify it in Workbench.

To create a page:

1. Login to Workbench and navigate to Experience Manager.2. Mouse over the Pages heading in the Content Tree.

The drop-down menu arrow appears on the right.

3. Click the drop-down menu arrow and select Add Page.The Add Page panel appears.

4. Enter a Name/Path for the new page.This is the part of the URL path that uniquely identifies the page within your application.

5. Click Create.The new page is added to your application.

A page exists as a content item in Experience Manager. A content administrator can configure it directlyby selecting a template with included editors, or they can specify a template with a dynamic slot topopulate the page from a selected content collection.

About content collectionsBefore a content administrator can configure dynamic content items within an application, you mustcreate content collections to contain those items. Content items within the same collection are evaluatedagainst each other at runtime to determine which item (or items) should be returned to populate adefined section of the current page.

In Experience Manager, content collections define the top-level organizational structure of an application,in which the content administrator can browse for content. Within the MDEX Engine, a collectionrepresents the set of content items that are evaluated against each other to determine which ones arereturned for a particular query. If a query satisfies the trigger criteria for multiple content items withina collection, items with higher priority take precedence over those with lower priority. A single applicationrequest may trigger content items from multiple collections.

Content collections have the following properties:• Content type — Specifies the type of content items that can be created in this collection, as defined

by the type attribute of the content template.• Evaluation limit — The maximum number of content items in this collection that can be returned

for a single query.

Oracle recommends that you create at least one content collection for pages and one for each slot onthe page that can contain either shared or variable content. This provides a logical organization ofcontent within Experience Manager. It enables content to be triggered independently of the pages thatcontain them and also enables content in one slot to be triggered independently of content in anotherslot.

For example, the Discover Electronics reference application includes the following content collections:


Supporting an Assembler Application | About content collections16

• Mobile \ Mobile Browse Pages — Top-level page configuration for pages viewed from a mobiledevice. Mobile pages must be more streamlined than Web pages, so they require a different pagetemplate.

• Shared \ Auto-Suggest Panels — Configuration for the auto-suggest panel that displays whena user starts to enter a search query. The Shared collections return the same response model forboth the Mobile and Web versions of the application, but the renderers vary based on the client.

• Shared \ Detail Pages — Configuration for record details pages within the application.• Shared \ Guided Navigation — Configuration for the Guided Navigation menu.• Shared \ Results List — Configuration for a list of search results.• Web \ Category Spotlights — Category-specific product spotlights that display above the search

results when a user navigates to those products.• Web \ Web Browse Pages — Top-level page configuration for Web pages. These templates are

structural and primarily consist of dynamic slots that pull in content items from other collectionsto populate the page.

Content collections exampleContent collections determine which content items are evaluated and which items are returned for aparticular query.

Suppose you have a site where a typical structure for a search and navigation page looks like thefollowing:

Based on this template, the content administrator wants to configure a page for a specific trigger (forexample, Category > Cameras > Digital Cameras) using contextual, shared, and variable content asin this picture:


17Supporting an Assembler Application | About content collections

• The header and footer are populated from a content collection in order to avoid defining themmultiple times for a large number of pages.

• The Guided Navigation and Results List cartridges are configured specifically for this page and donot need to vary based on criteria other than the page triggers.

• The Banner area is configured to display a different image depending on the brand that the sitevisitor has selected.

• The Spotlight area displays a mix of promotions based on triggers that are independent of thetriggering criteria for the page itself. For example, a "Holiday Specials" spotlight may display forthe date range between November 1 and January 2.

The configuration for the page (as specified in Experience Manager) looks like this:



The configuration for Guided Navigation (including which dimensions to display and which dimensionvalues to boost or bury within those dimensions) and for the Results List (including default sort optionsand record boost and bury) are specified as part of the page configuration. The other slots on the pagecontain only placeholders. The actual Header, Footer, Banner, and Spotlight content items that displaywhen someone visits the site are defined in their respective content collections.

The mechanism for populating these slots is the same regardless of whether the content that shoulddisplay in each slot is shared or variable content. The only difference between the two kinds of contentis in the trigger criteria on the content items within those collections: variable content, such as theSpotlight, has triggers that are more specific than the page trigger. Reusable content, such as thegeneric header and footer, has triggers that are more general than or orthogonal to the page trigger.

When the content administrator has created all the content needed to populate this page (and a fewother pages), the application may include the following content items in the following collections:

The collections are configured as follows:• The Browse Page collection contains all the content items representing search and navigation

pages in the site. Because only one page can display to a user for any given query, the evaluationlimit is 1.

• The Brand Banner collection contains cartridges of type MediumBanner that are appropriate todisplay in the Banner slot. This collection also has an evaluation limit of 1 because the page isdesigned to display only one banner at a time.

• The Spotlight collection contains cartridges of type SidebarItem because items created in thiscollection are intended to display in the Spotlight slot in the right column. Because this space isintended to display several independently triggered spotlight items, the evaluation limit for thiscollection is 3.

• The Header and Footer collections each contain cartridges of type FullWidthContent. Theevaluation limit for these collections is also 1.

Each page or content item within these collections has an associated trigger and priority (relative tothe other items in the same collection) specified by the content administrator in Experience Manager.

When a site visitor refines on Category > Cameras > Digital Cameras and Brand > Sony, the followingcontent is triggered:



• The Digital Cameras page is returned from the Browse Page collection, which includes the contentadministrator's configuration for Guided Navigation and for Results List. Note that the Default page(with a trigger of "Applies at all locations") is also eligible to fire, but the Browse Page collection islimited to one content item and the Digital Cameras page has a higher priority, therefore it takesprecedence and the Default page does not fire.

• The Banner slot is populated by the highest priority content item that matches the user's navigationstate in the Brand Banner collection. In this case, it is the Sony cameras banner. Again, there isa Default banner but it does not fire because it has a lower priority.

• The Spotlight slot is populated by the highest priority content items that match the user's navigationstate in the Spotlight collection. In this case, the Default spotlight does fire because there is roomfor three spotlights in this slot and that item has a high enough priority (among those that satisfythe user's context) to be included. These three content items display in the Spotlight area in orderof priority.

• The Header and Footer collections have only one content item each, which is set to display at alllocations, therefore the same content is returned for this page as for all pages.

In this example, content is returned from five content collections (including the Browse Page collection).Priority between items is specified within each collection. It does not make sense to prioritize the Sonycameras banner against the April spotlight cartridge, for example, because they are not competingagainst each other to be displayed on the page. In general, content items with more specific triggercriteria should have a higher priority than those with more general criteria, especially if a contentcollection has an evaluation limit of 1.

Oracle recommends that you create separate collections for each area on the page, even if they havethe same content type. For example, if you want to have two banners on the page, each populatedvia dynamic slots, they should reference two different collections, or else the same banner (the onewith the highest priority for the current navigation state) would be returned for both sections of thepage.

Oracle also recommends that you do not mix reusable and variable content within the same collection.For example, if a slot (such as the Spotlight slot) can be populated with either reusable or variablecontent, create two different collections, Reusable Spotlight collection and Variable Spotlight collection.The content administrator can configure a particular page to populate the Spotlight slot from eithercollection as applicable. In order to populate the same slot with a mixture of reusable and variablecontent, the content administrator can insert two (or more) placeholders in the Spotlight slot, eachreferencing the corresponding collection for each type of content.

The final result for the site visitor who is looking at Sony cameras looks something like the following:



Related LinksAbout dynamic slots on page 112

A dynamic slot is a generic mechanism that enables content administrators to manage thecontent for specific sections of an Experience Manager-driven page independently from theoverall page.

Creating a content collectionThe Content Tree in the left pane of Experience Manager is divided into two sections: Pages andContent. You create content collections within the Content section.

You must deploy and provision your application with the EAC in order to modify it in Workbench.

To create a content collection:

1. Login to Workbench and navigate to Experience Manager.2. Mouse over the Content heading in the Content Tree.

The drop-down menu arrow appears on the right.

3. Click the drop-down menu arrow and select Add Collection.The Add Content Collection panel appears.

4. Enter the Name of the collection you wish to add.5. Enter the content type that you wish to use for the collection in the Content Type Allowed field.

You may also use the drop-down arrow to display a list of available content types. The drop-downlist is populated based on the available type values for each cartridge template you have uploadedto the Endeca Configuration Repository.This selection restricts the content collection to items of the specified type.

6. Set the Evaluation Limit for the content collection in the combo box.7. Click Add.

The new content collection is added to the Content Tree in Experience Manager.



8. Optionally, drag the new content collection to a folder within Experience Manager for organizationalpurposes.You can create a new folder using the drop-down menu for the Content heading.

About moving content collectionsYou can move and re-organize content collections in the Content Tree within Experience Manager.

If you move a content collection that includes dynamic content referenced elsewhere in the application,a warning dialog appears with a list of content items that rely on the content you are moving. You mustmanually update these content items if you proceed with the move.



Chapter 2

Creating Experience Manager Templates

This section describes the process of creating templates that enable the configuration of content itemsin Experience Manager.

About creating templatesTemplates define the content structure of a content item as well as the editing interface that contentadministrators can use to configure instances of content items in Experience Manager.

In general, you create one or more templates that define the high-level structure of the pages in yourapplication. These templates define sections that can be populated with other content items, orcartridges. Cartridge templates specify the properties required to display the content for that component.This may include values that the client application uses directly to render the information, or inputsinto the Assembler for processing (such as parameters for queries to an MDEX Engine or anotherexternal resource).

While cartridges and template properties typically determine aspects of the visual appearance of thepage, keep in mind that they can also represent page elements that are not visible in the application.For example, a property could contain meta keywords used for search engine optimization, or acartridge could include embedded code that does not render in the page but enables functionality suchas Web analytics beaconing.

The Discover Electronics reference application provides some sample page templates for somestandard page types as well as templates to enable configuration of the core set of cartridges inExperience Manager. These cartridges cover basic Endeca functionality, and are provided as a startingpoint for your application and can be customized to suit your needs.

Note: In some cases, the reference application includes more than one template for the samefunctional cartridge. This is in order to enforce the proper constraints on which cartridges areavailable to insert in specific sections or content collections in the application. The only differencebetween the different versions of these templates is the template type.

This section concentrates on the basic template elements that enable you to create top-level pagetemplates appropriate to your application. Details about the template configuration for the core cartridgesare covered in the "Feature Configuration" section. Reference information about the full range ofproperties and editors that can be used in templates is provided in the appendix to this guide.

Related LinksAbout the type and ID for a template on page 26

Each template is required to have a type and a unique id.Configuring Front-End Application Features on page 79

This section describes the cartridge configuration model for front-end application features,and provides a description of the core cartridges in Oracle Endeca Tools and Frameworks.

Template Property and Editor Reference on page 147This section describes how to define basic content properties and associated editing interfacesin Experience Manager templates.

Anatomy of a templateTop-level templates, which define an entire page, and cartridge templates, which drive the content ofindividual components, are both XML documents that share the same structure.

Templates can be broken down into three parts:• General information such as the template type, ID, description, and thumbnail image. This

information is used in Experience Manager to help the content administrator select the appropriatetemplate for a page or section.

• Content item definition. In this part of the template, you explicitly declare all the properties of thecontent item that is described by this template. Property types can include Strings, Lists, andBooleans. You can also specify the default values of properties here.

• Editor panel definition. These allow you to define the editing interface in Experience Managerfor this content item. Properties are generally associated with an editor that enables contentadministrators to configure the content items that they create within the tool.

By defining the properties in the template along with how they can be configured in the tool, you ensurethat the content configured in Experience Manager matches the expected configuration model for thecorresponding cartridge handler in the Assembler.


Creating Experience Manager Templates | Anatomy of a template24

Template naming conventionsTemplates are saved as XML files that are then uploaded to Experience Manager. It is possible tohave multiple templates in a single file, however, for ease of maintenance Oracle recommends thefollowing practices.

• Each template should be in a separate file.• Name each template file using the following format: <TemplateType>-<TemplateID>.xml.

For example, ResultsPage-ThreeColumnNavigationPage.xml orHorizontalBanner-ImageMap.xml

Note: Template file names cannot have spaces in them.

Endeca also recommends that you treat templates as part of your application's configuration and storethem in a version control system. It can also be useful to include a template version number in aproperty for debugging purposes.

About the template XML schemaAll templates share the same primary schema. In addition, there are several other namespaces thatare commonly used in templates.

The template schema

The template schema describes the overall structure of page and cartridge templates. It is also usedfor primitive property types such as String and Boolean.

All templates must include the following schema declaration:<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008" type="PageTemplate" id="ThreeColumnNavigationPage">

Before you upload your templates to Experience Manager, Endeca recommends that you validatethem against the template schema. A copy of the template schema (content-template.xsd) islocated for your reference with your Endeca Workbench installation in%ENDECA_TOOLS_CONF%\conf\schema (on Windows) or $ENDECA_TOOLS_CONF/conf/schema(on UNIX).

The Xavia schema

The Xavia namespace is used for properties that are lists or items (collections of key-value pairs).Include the following namespace declaration in templates that use these properties:<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008" xmlns:xavia="http://endeca.com/schema/xavia/2010"

type="PageTemplate" id="ThreeColumnNavigationPage">

The editors schema

There is no formal schema for editor configuration, however, by convention, they are associated withan editors namespace to distinguish these elements from the template schema. Include the followingnamespace declaration in all templates:<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008" xmlns:xavia="http://endeca.com/schema/xavia/2010"


25Creating Experience Manager Templates | Template naming conventions

xmlns:editors="editors" type="PageTemplate" id="ThreeColumnNavigationPage">

About the type and ID for a templateEach template is required to have a type and a unique id.

The template type determines where a template can be applied. There are two general categories oftemplates. For top-level templates, such as page templates or templates that describe content itemsthat can be triggered independently from a content collection, the type must match the content typeof the collection in Experience Manager. Container templates specify the content type for each of theirsections, which determines which cartridges can be inserted into that section. For example, if you havea template that includes a "HorizontalBanner" section, only cartridges of type "HorizontalBanner" areavailable to insert into that section in Experience Manager.

The template id is a string that is used to identify the template. It must be unique within your application;templates with non-unique IDs are not available in Experience Manager. The ID displays as the nameof the cartridge in the cartridge selector in Experience Manager. The value should be as descriptiveas possible to help the user select the appropriate template, for instance,"ThreeColumnWithLargeBanner" or "HolidaySalePromotion."

The template type and id are specified as required attributes on the <ContentTemplate> element.For example:<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008" xmlns:xavia="http://endeca.com/schema/xavia/2010" xmlns:editors="editors"type="PageTemplate" id="ThreeColumnNavigationPage">

Note: The type and id attributes are defined as type xs:Name in the template schema. Thismeans that valid values for these attributes must:

• be a single string token (no spaces or commas)• begin with a letter, a colon (:), or an underscore (_)

Numbers are allowed as long as they do not appear at the beginning of the string.

Specifying the description and thumbnail image for atemplate

The description and thumbnail image for a template display in the template selector and cartridgeselector dialog boxes in Experience Manager. Adding a description and thumbnail image to a templateis optional.

To specify the description and thumbnail image for a template:

Insert the following elements within <ContentTemplate>:DescriptionElement

One or two brief sentences to help the content administrator identify thetemplate in Experience Manager. This can include information about the visual

<Description>

layout of the template ("Three-column layout with large top banner") or itsintended purpose ("Back to school promotion").


Creating Experience Manager Templates | About the type and ID for a template26

DescriptionElement

The absolute URL to a thumbnail image that shows a sample page or sectionthat is based on the template. The images must be hosted on a Web serveraccessible from the Experience Manager server.

<ThumbnailUrl>

Note: If your thumbnails are hosted on the same server as EndecaWorkbench, you can omit http://<host>:<port> from the URL.

Example<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008" xmlns:xavia="http://endeca.com/schema/xavia/2010" xmlns:editors="editors" type="PageTemplate" id="ThreeColumnNavigationPage"> <RuleInfo zone="NavigationPageZone" style="PageStyle"/><Description>A page layout with left and right sidebars intended for

general category pages.</Description><ThumbnailUrl>http://images.mycompany.com/thumbnails/PageTemplate/Three¬

ColumnNavigationPage.png</ThumbnailUrl>

</ContentTemplate>

About using thumbnail images in Experience ManagerThumbnail images can help the content administrator identify the appropriate template to use for thepages they create.

The suggested size for thumbnail images is 81 x 81 pixels; smaller images are stretched to fill thissize and larger images are cropped to show only the top left corner.

The images must be hosted on a Web server accessible from the Experience Manager server. If thethumbnail image for a template is either not specified or not accessible, a default image displays inthe dialog box.

Specifying the default name for a cartridgeThe value of <Name> within the <ContentItem> displays as a label for the cartridge in the ContentTree in Experience Manager.

To specify a default name for a cartridge:

Insert the <Name> element inside <ContentItem> as in the following example:<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008"

xmlns:xavia="http://endeca.com/schema/xavia/2010" xmlns:editors="editors" type="PageTemplate" id="ThreeColumnNavigationPage"> <RuleInfo zone="NavigationPageZone" style="PageStyle"/> <Description>A page layout with left and right sidebars intended for general category pages.</Description> <ThumbnailUrl>http://images.mycompany.com/thumbnails/PageTemplate/Three¬


27Creating Experience Manager Templates | Specifying the default name for a cartridge

ColumnNavigationPage.png</ThumbnailUrl><ContentItem>

<Name>New Three-Column Navigation Page</Name>

</ContentItem>

</ContentTemplate>

<Name> is a required element. The value you specify in the template becomes the default namewhen a content adminstrator creates the page or adds a cartridge. If you insert an empty <Name/>element, an empty text field displays in Experience Manager and the content administrator cansupply a value.

About defining the content properties and editing interfaceA template defines the properties of a content item and also the interface that enables a contentadministrator to configure the properties.

You define properties within the <ContentItem> element in the template. For each property, youspecify a name and a property type. You can optionally specify a default value for a property.

You associate editors with properties to enable the content administrator to configure their valueswithin Experience Manager. Properties are generally primitive types such as Strings, Booleans, orLists. Another type of property is a section, which allows content administrators to insert and configureanother content item.

You can choose not to expose a particular property in Experience Manager and simply specify a defaultvalue to pass to the Assembler and ultimately to the client application. This is useful for values thatdo not need to be configured by the content administrator, but are needed by the Assembler for contentprocessing or by the client application to determine how to render the content.

About template propertiesYou can define the properties of a content item by nesting any number of <Property> elementswithin the <ContentItem> element.

Cartridge properties are typically used for one of the following purposes:• The property values may be intended to be used directly by the client application. For example,

the content administrator may be able to enter text to use a heading or link text, or she may supplya URL to an image. Property values can also contain information such as meta keywords that arepart of the page but do not affect its display.

• The values may be intended for the relevant cartridge handler in the assembler to use for processing,for example, parameters for a query to the MDEX Engine (or another external resource) to returnthe actual content that the application should display.

• Occasionally, a cartridge has no properties (and therefore no configuration options in ExperienceManager), but exists only as a placeholder to indicate that a certain functional component shouldbe included on a page. The Assembler inserts the necessary information for this cartridge at querytime.

Each property must have a name that is unique within the template. If the property is to be passedthrough directly to the renderer, this can be any name that makes sense for your application. However,some properties are part of the configuration model for the cartridge. In this case the associatedcartridge handler depends on the presence of specific properties in the template.


Creating Experience Manager Templates | About defining the content properties and editing interface28

The property name is specified in the name attribute of the <Property> element.

Note: The name attribute is defined as type xs:Name in the template schema. This means thatvalid values for these attributes must:

• be a single string token (no spaces or commas)• begin with a letter, a colon (:), or a hyphen (-)

Numbers are allowed as long as they do not appear at the beginning of the string.

You specify the property type by adding a child element of <Property>. Properties can be one oftwo kinds:

• content properties (described by the template schema for primitive properties and Xavia for listsand items)

• structural properties (described by the template schema)

About defining the editing interface for propertiesAfter you have defined the content properties in your template, you can define how those propertiescan be configured by the content administrator in Experience Manager.

You add content editors inside the <EditorPanel> element in the template. The <BasicCon¬tentItemEditor> element enables you to specify individual property editors that display in ExperienceManager and associate them with a particular property.

For example, this excerpt from a sample template defines a configurable string property named title:<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008" xmlns:editors="editors" type="ResultsPage" id="ThreeColumnNavigationPage">

<ContentItem> <Name>Three-Column Navigation Page</Name>

 <Property name="title"> <String>Discover Electronics</String> </Property>

 </ContentItem> <EditorPanel> <BasicContentItemEditor>

 <StringEditor propertyName="title" label="Title"/>

 </BasicContentItemEditor> </EditorPanel></ContentTemplate>

Editors are defined in templates with the editors namespace. By convention, the propertyNameis a required attribute and specifies the property that this editor is associated with. The property mustbe defined in the <ContentItem> part of the template, and must be of the appropriate type for thateditor. For example, an <editors:StringEditor> cannot be associated with a <xavia:List>property. If you define a content editor for a property that does not exist, or that is of the wrong type,a warning displays in Experience Manager when a content administrator attempts to configure thecontent.


29Creating Experience Manager Templates | About defining the content properties and editing interface

Property editors do not have to be defined in the same order as the properties in the template. The<BasicContentItemEditor> renders the editors in a vertical layout in Experience Manager, in theorder in which you define them in the template. If you do not want a property to be exposed in theExperience Manager interface, do not define an editor associated with it.

It is possible to create more than one editor associated with the same property. However, be awarethat all editors that you define in the template are displayed in Experience Manager, which may beconfusing to the content administrator. When the value of a property is changed, any other editorsassociated with that property are instantly updated with the new value.

Related LinksEditor property mapping reference on page 147

This section provides an overview of which property types are associated with the differentOracle Endeca Commerce Suite editors.

About configuring editor default valuesYou can configure default values for Experience Manager editors across the entire application bymodifying the editor configuration file, or on a per-template basis by modifying cartridge templatesdirectly.

You can configure Experience Manager editors through the following methods:• You can configure editors in the editor configuration file, editors.xml. This configuration applies

to all instances of a specific editor within an application.• You can configure editors within a cartridge template. This configuration applies to all instances

of a specific editor created based on that template. In the case of shared properties, configurationin the cartridge template overrides configuration in editors.xml.

For details about configuring the core editors packaged with Oracle Endeca Tools and Frameworks,see the "Template Property and Editor Reference" Appendix.

Related LinksTemplate Property and Editor Reference on page 147

This section describes how to define basic content properties and associated editing interfacesin Experience Manager templates.

About defining the editing interface for properties on page 29After you have defined the content properties in your template, you can define how thoseproperties can be configured by the content administrator in Experience Manager.

Specifying editor-specific configurationYou can modify the editor configuration file to set configuration that is common to all instances of aspecific editor within an application. This can include basic values for the editor, or information usedto communicate with an external resource.

Note: Oracle recommends configuring a data service for cases where different editors all needto access a common set of configuration for an external resource.

To add configuration information to the editor configuration file:

1. Navigate to the editor configuration file at <app dir>\config\editors_config\editors.xml.2. Insert an <EditorConfig> element directly inside the <Editor> tag of the editor you wish to

modify.3. Add your arbitrary configuration information.


Creating Experience Manager Templates | About defining the content properties and editing interface30

The example below includes the configuration inside a nested element, but you can also specifythe information as attributes of the EditorConfig element:<Editor name="editors:MyEditor"><EditorConfig>

<Arbitrary foo="bar" size="10" resizeable="false"/> </EditorConfig></Editor>

4. Save and close the file.5. Navigate to the <app dir>\control directory.6. Run the set_editors_config script to publish your changes to the Endeca Configuration

Repository.

Structural propertiesYou can define a section within a template by inserting a <ContentItem> or <ContentItemList>element within a <Property>.

Adding a content item propertyA content item property defines a template section by creating a placeholder for a nested content itemdefined by a cartridge template.

Content administrators can configure a section in Experience Manager by choosing a cartridge toinsert in the section then configuring the properties of the cartridge.

To add a content item property to a template:

1. Insert a <ContentItem> element inside a <Property> element.2. Specify the section type.

Only cartridge templates with a type that matches the section type are presented as options for thecontent administrator to choose from in Experience Manager. For example, when a contentadministrator inserts a cartridge in a RecommendedContent section, only templates of type Rec¬ommendedContent display in the Select Cartridge dialog box. (Recall that the cartridge templateis the part of a cartridge that is exposed in Experience Manager). Because the type of the sectionproperty and cartridge templates must match exactly, the type attribute is also defined as typexs:Name in the schema and all restrictions that apply to template types also apply to section types.

The following example defines two sections within a template. Note that more than one section in atemplate can have the same type, as long as your client application expects this kind of content.

<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008" xmlns:xavia="http://endeca.com/schema/xavia/2010" xmlns:editors="editors" type="PageTemplate" id="ThreeColumnNavigationPage">

<ContentItem> <Name>New Three-Column Navigation Page</Name>

 <Property name="leftColumn"> <ContentItem type="SidebarItem" /> </Property>


31Creating Experience Manager Templates | Structural properties

<Property name="rightColumn"> <ContentItem type="SidebarItem" /> </Property> </ContentItem>

</ContentTemplate>

Adding a content item list propertyA content item list allows content administrators to add an arbitrary number of items to a section andto reorder those items within the list using the Content Tree in Experience Manager.

Using content item properties to define the subsections of a cartridge restricts the number of subsectionsavailable to the content administrator in Experience Manager. For example, the right column of thispage template can contain exactly four cartridges:<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008" xmlns:xavia="http://endeca.com/schema/xavia/2010" xmlns:editors="editors" type="PageTemplate" id="ThreeColumnNavigationPage">

<ContentItem> <Name>New Three-Column Navigation Page</Name> <Property name="rightColumn1"> <ContentItem type="SidebarItem" /> </Property> <Property name="rightColumn2"> <ContentItem type="SidebarItem" /> </Property> <Property name="rightColumn3"> <ContentItem type="SidebarItem" /> </Property> <Property name="rightColumn4"> <ContentItem type="SidebarItem" /> </Property> </ContentItem></ContentTemplate>

Although some of the sections can be left empty, no more than four cartridges can be added to theright column.

Using a content item list removes the restriction and allows the content administrator to add an arbitrarynumber of content items to the right column of the page:<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008" xmlns:xavia="http://endeca.com/schema/xavia/2010" xmlns:editors="editors" type="PageTemplate" id="ThreeColumnNavigationPage">

<ContentItem> <Name>New Three-Column Navigation Page</Name> <Property name="rightColumn"> <ContentItemList type="SidebarItem" /> </Property> </ContentItem>


Creating Experience Manager Templates | Structural properties32

</ContentTemplate>

To add a content item list to a template:

1. Insert a <ContentItemList> element inside a <Property> element.2. Specify the template type.

Only cartridge templates with a type that matches the content item list type are presented as optionsfor the content administrator to choose from in Experience Manager. In the above example, whena content administratorinserts a cartridge in a RightColumn section, only templates of typeSidebarItem display in the Select Cartridge dialog box.

3. Optionally, specify a maximum number of content items using the maxContentItems attribute.For example: <Property name="RightColumn"> <ContentItemList type="SidebarItem" maxContentItems="4"/> </Property>

By default, the value of maxContentItems is 0, which means that there is no limit to the numberof cartridges that can be added to a content item list.

About cartridge selectorsUnlike other types of content properties, section properties are always editable; you do not need toexplicitly specify an editor in the template.

In Experience Manager, content administrators can select cartridges to insert in sections either byclicking the cartridgeAdd button in the content detail panel or by right-clicking the section in the ContentTree. Both options bring up the cartridge selector dialog box and are enabled automatically when youdefine a section in the template.


33Creating Experience Manager Templates | Structural properties

Chapter 3

Managing Experience Manager Templates

You must upload templates to Endeca Workbench before they are available to users in ExperienceManager.

Updating Experience Manager templatesAll deployment template applications include a set_templates script in the control directory toupdate Experience Manager templates. You run the script after you locally modify XML template filesand you want the templates available in Experience Manager.

This script requires that the templates you modify are stored locally in <appdir>\config\cartridge_templates.

To send updated templates to Experience Manager:

1. Start a command prompt (on Windows) or a shell (on UNIX).2. Navigate to the control directory of your deployed application.

This is located under your application directory. For example: C:\Endeca\apps\<appname>\control.

3. Run the set_templates script.For example:C:\Endeca\apps\Discover\control>set_templates.batRemoving existing cartridge templates for DiscoverSetting new cartridge templates for DiscoverFinished setting templates

Troubleshooting problems with uploading templatesTemplate errors are returned to the emgr_update command line call and detailed in the webstudio.logfile.

The webstudio.log file is located in:• %ENDECA_TOOLS_CONF%\logs on Windows• $ENDECA_TOOLS_CONF/logs on UNIX

Uploading templates can fail for the following reasons:

Schema validation

Schema validation failure issues an error returned to the emgr_update command line call similar tothe following:C:\Endeca\apps\ContentAssemblerRefApp\config\cartridge_templatesERROR: The template "NavigationPage.xml" is invalid (org.xml.sax.SAXParse¬Exception: cvc-complex-type.4: Attribute 'id' must appear on element 'Con¬tentTemplate'.)ERROR: Failed to set app config. Make sure you can connect to http://local¬host:8006.

Each template that fails validation appears as a separate component. The error is also written to thewebstudio.log file at the WARN level.

In the case of malformed XML, a similar error is output to both the command line and thewebstudio.log file. For a file with multiple validation errors, only the first failure is logged.

Duplicate template ID

If you upload two template files with the same ID but different file names, then two separate templatesare stored in Experience Manager but neither one displays to content administrators. An error messageis returned to the emgr_update command line call similar to the following:ERROR: 2 errors follow: [ERROR 1] The template "HorizontalBanner-ImageMap.xml" has a non-unique ID ("ImageMap"). [ERROR 2] The template "VerticalBanner-ImageMap.xml" has a non-unique ID ("ImageMap"). ERROR: Failed to set app config. Make sure you can connect to http://local¬host:8006.

The error is also written to the webstudio.log file at the SEVERE level.

To re-enable the templates, edit the id attribute of the <ContentTemplate> element so that eachtemplate ID is unique, remove the templates from Experience Manager, and re-upload the templates.In general, it is a best practice to remove templates from the Experience Manager and upload acomplete set of templates whenever you need to update templates.

Invalid filename or directory path

If the template file or containing directories include a space, the emgr_update command line call issuesan error similar to the following (in this case, for a file named Copy of TestA.xml):ERROR: 09/22/09 15:54:36.795 UTC (1253634876795) EMGR_MKPKG {emgr_mkpkg}: Unknown file type "of" specified for filename "C:\Ende¬ca\apps\ContentAssemblerRefApp\config\cartridge_templates\Copy". Valid file types are: AENE_OP_CONFIG ANALYTICS_CONFIG CONTENT CRAWLER_DEFAULTS CRAWLER_GLOBAL_CONFIG CRAWL_PROFILE CRAWL_PROFILES CRAWL_PROFILE_CON¬FIGCRAWL_PROFILE_URL_LIST DERIVED_PROPS DIMENSIONS DIMENSION_GROUPS DIMEN¬SION_REFS DIMSEARCH_CONFIG DIMSEARCH_INDEX DVAL_RANKS DVAL_REFS ENEIDX_OP_CON¬FIG ENE_OP_CONFIG FORGEOUTDIMS FORGE_OP_CONFIG KEYWORD_REDIRECT_GROUP KEY_PROPS LANGUAGES MERCHSTYLES MERCHZONES MERCH_RULES MERCH_RULE_GROUP PHRASES PIPELINE PIPELINE_PARTIAL PRECEDENCE_RULES PRECOMPUTE PROFILES PROP_REFS RECORD_FILTER RECORD_ID_PROP RECORD_SORT_CONFIG RECORD_SPEC REC¬SEARCH_CONFIG RECSEARCH_INDEXES REFINEMENT_CONFIG RELRANK_STRATEGIES REN¬DER_CONFIG ROLLUPS SEARCH_CHARS STEMMING STOP_WORDS THESAURUS VIEWS RESOURCE

To avoid this error, make sure that your file and directory names do not include spaces.


Managing Experience Manager Templates | Updating Experience Manager templates36

Empty directory

When uploading templates, if the specified directory does not contain any XML files, the emgr_updatecommand line call displays the following message:There are no templates in the specified directory.

If you receive this message, check to make sure that you specified the correct directory to theemgr_update call. The utility script provided with the Deployment Template module assumes that thetemplates are located in APP_DIR/config/cartridge_templates.

Troubleshooting invalid templatesSome templates may be successfully uploaded to Workbench, but still contain errors that lead tounexpected behavior in Experience Manager.

The most common scenario is when a property is associated with an editor that has constraints, suchas a choice editor that can only accept certain string properties. If the default value of the propertydoes not meet the editor's constraints, the editor may discard the value and display the followingmesssage in the Content Details Panel when a user adds the cartridge to a page:Some fields or cartridges within this cartridge may have been updated or removed. Your content has been converted to the new cartridge. To accept these changes click OK and Save All Changes from the List View. To reject these changes, click Cancel. For more information, see "Troubleshooting pages" in the Oracle Endeca Workbench Help.

To avoid this message, ensure that all property defaults are valid options in the associated propertyeditor.

About updating templatesWhen updating templates in Experience Manager, you should be aware of how conflicts are handled.

Experience Manager uses the most recently uploaded template. If you have an existing template inExperience Manager and upload a template with the same file name, the new template replaces thepreviously uploaded template.

However, if you upload two template files with the same ID but different file names, then two separatetemplates are stored in Experience Manager but neither one displays to content administrators. Forthis reason, you should avoid renaming template files after they have been uploaded to ExperienceManager unless you make sure to remove the old template first. In general, it is a best practice toremove templates from Experience Manager and upload a complete set of templates whenever youneed to update templates.

About modifying templates that are used by existing pagesDuring the development and testing phase of your application deployment, you may need to makeadjustments to your templates and update them in Experience Manager.

When Experience Manager populates the Content Detail Panel for a content item, it checks thecontent configuration of the loaded page against the template. If the template has been changed suchthat it is no longer compatible with the content, Experience Manager displays a warning and attemptsto upgrade existing content to fit the new template definition.


37Managing Experience Manager Templates | About updating templates

Note: Existing configurations are not upgraded to the new template until a content administratoredits and saves the affected content item in Experience Manager.

Experience Manager does the following to ensure that the content and template are in sync:

• If a property has not changed its name or type, the existing values are migrated to the new template.• If new properties are added to a template, any corresponding property editors become available

in Experience Manager when a content administrator edits a content item based on the updatedtemplate. If you specify default values for the new properties, they are applied when a contentadministrator edits and saves the content item using the updated template.

• If properties are removed from a template, the corresponding property editors no longer displayin Experience Manager when a content administrator edits a content item based on the updatedtemplate. The properties and their values are deleted from the page configuration.

• If the type of a property has changed (for example from string to list) within a template, thecorresponding property editor (if one is specified) becomes available in the Experience Managerwhen a content administrator edits a content item based on the updated template. The existingvalue for the property does not display in Experience Manager until the content administrator savesthe new value, replacing the previous value.

• If a content item or content item list property has changed to specify a different content type, thenany existing cartridge in that section is ejected and its configured properties deleted.

• If the default value of an existing property has changed, it is only applied to new content items thatare created based on the updated template. In existing pages, the previously saved value of theproperty (even if it is an empty string) is preserved regardless of whether it was originally a defaultor user-specified value.

• Some editors may implement specific update-handling logic in cases where an existing value doesnot meet the editor's constraints.

Note: Changing the name of a property is equivalent to removing the property with the old nameand adding a property with the new name. Avoid changing the names of properties that are beingused by existing pages. To change the display name of a property on Experience Manager, usethe label attribute instead.

Managing template changes

Because existing content is not automatically updated to the new templates, and default values arenever updated in existing pages, any changes that you make to your rendering code to reflect changesto a template should be backward-compatible. You can trigger the content upgrade process manuallyby accessing all affected content, but this approach is not recommended.

For this reason, you should avoid making changes to existing templates that are being used inproduction. You should limit updates to templates to the early stages of application development whenyou have little or no legacy content to support.

About removing templatesIf you remove a template that is being used for an existing page, the properties of the correspondingcontent item are no longer editable in Experience Manager.

When a content administrator attempts to edit an existing content item that uses a missing template,the following occurs:


Managing Experience Manager Templates | About removing templates38

• The properties defined in the content item itself can no longer be edited in the content details panel.All the existing values of the missing template's properties are preserved unless the contentadministrator removes the content item and selects a different template.

• The tree of child content items is still active. The content administrator can change or edit childcartridges via the Content Tree, as long as their templates are still available.

The content administrator has the following options:• Leave the existing content as is. The Assembler continues to evaluate and process configurations

as long as the appropriate cartridge handlers are present, regardless of whether the templateexists in Experience Manager. Existing pages continue to display in the client application as longas the appropriate rendering code is still in place.

• Replace the missing template or cartridge with another template. This action deletes all configuredproperties of the template as well as any nested cartridges.

• The existing content can be re-enabled for editing by uploading the missing template.

Note: Changing the ID of a template is equivalent to removing the template with the old ID andcreating a new template with the new ID. Avoid changing the ID of templates that are being usedfor existing pages.

Removing templates from Experience ManagerYou can remove all the templates from Experience Manager using the emgr_update utility.

Note: Before removing templates from Experience Manager, be sure you have a backup of thecurrent set of templates. Oracle recommends that you store page and cartridge templates in aversion control system.

When removing or updating templates, make sure that all users are logged out of ExperienceManager.

The emgr_update --action remove_templates command removes all templates from anapplication, not specific templates. Removing specific templates from Experience Manager consistsof the following steps:

1. Retrieving the current set of templates from Experience Manager.2. Deleting the templates that are no longer needed from your local copy.3. Removing all templates from Experience Manager using the procedure below.4. Uploading the remaining templates to Experience Manager.

To remove templates from Experience Manager:

1. Open a command prompt or UNIX shell.2. Run emgr_update with the --action of remove_templates and the following parameters:

ValueParameters

The machine name and port for the staging Endeca Workbenchenvironment, in the format host:port.

--host

The name of the application from which you want to remove thetemplates.

--app_name


39Managing Experience Manager Templates | About removing templates

The following is a Windows example:emgr_update.bat --action remove_templates --host localhost:8006 --app_name My_application

The following is a UNIX example:emgr_update --action remove_templates --host localhost:8006 --app_name My_application

Retrieving the current templates from Experience ManagerIf you need to view or edit an existing template on a local machine, you can run the get_templatesscript to download templates from Experience Manager to the local <appdir>\config\cartridge_templates directory.

To get templates from Experience Manager:

1. Start a command prompt (on Windows) or a shell (on UNIX).2. Navigate to the control directory of your deployed application.

This is located under your application directory. For example: C:\Endeca\apps\<appdir>\control.

3. Run the get_templates script.


Managing Experience Manager Templates | Retrieving the current templates from Experience Manager40

Chapter 4

Building Applications with the Endeca Assembler

This section describes how to build a client application that uses the Endeca Assembler to query theMDEX Engine or other services.

Assembler dependenciesAssembler dependencies are packaged in the %ENDECA_TOOLS_ROOT%\assembler\lib directory.You must include them in any custom Assembler application that you build.

The Assembler relies on the following libraries:• AOP Alliance 1.0• Apache Commons Logging 1.1.1• Endeca Navigation API 6.3.0• Endeca Logging API 6.3.0• Spring AOP 3.0.1• Spring ASM 3.0.1• Spring Beans 3.0.1• Spring Context 3.0.1• Spring Core 3.0.1• Spring Expression 3.0.1• Spring Web 3.0.1

About deploying the AssemblerThe Assembler can run in process as part of a Java application that powers a Web site, or it can bedeployed as a standalone servlet. Non-Java applications must use the Assembler servlet.

The Tools and Frameworks package includes an example of each deployment mode in/reference/discover-electronics (for the Assembler running in process) and/reference/discover-service (for the standalone Assembler servlet). The standalone servlet,or Assembler Service, provides a RESTful interface for Assembler queries that returns results in eitherJSON or XML.

Both deployment modes depend on a Spring context file for application-specific configuration. Thedeployment descriptor files for the reference implementations specify a context file located in/WEB-INF/assembler-context.xml, as follows:<listener> <listener-class> org.springframework.web.context.ContextLoaderListener </listener-class></listener><listener> <listener-class> org.springframework.web.context.request.RequestContextListener </listener-class></listener><context-param> <param-name>contextConfigLocation</param-name> <param-value>/WEB-INF/assembler-context.xml</param-value></context-param>

Assembler configurationThe Assembler implementation included with Tools and Frameworks is configured through Spring.The configuration in the Spring context file applies to both the in-process Assembler, and the AssemblerService.

This guide assumes an application based around the included Assembler implementations. You canprovide your own implementation if you wish to use an alternate means of configuring the Assembler.

In the reference implementations, application-specific Assembler configuration is specified in the Springcontext file located in WEB-INF\assembler-context.xml.

Assembler factory

The AssemblerFactory is an interface for creating a new Assembler. In the reference implementation,it is implemented in the SpringAssemblerFactory class and defined as follows:<bean id="assemblerFactory" class="com.endeca.infront.assem¬bler.spring.SpringAssemblerFactory" scope="singleton"> <constructor-arg> <bean class="com.endeca.infront.assembler.AssemblerSettings"> <property name="previewEnabled" value="${preview.enabled}" /> <property name="previewModuleUrl" value="http://${work¬bench.host}:${workbench.port}/preview" /> </bean> </constructor-arg></bean>

For details on the AssemblerFactory interface and SpringAssemblerFactory implementation,see the Assembler API Reference (Javadoc).

About configuring cartridge handlersA cartridge handler is an Assembler component that takes the configuration model for a specificcartridge and interacts with an external system to produce a response model. Cartridge handlerconfiguration is a subset of Assembler configuration.


Building Applications with the Endeca Assembler | Assembler configuration42

HTTP servlet request accessThe httpServletRequest bean provides access to the HTTPServletRequest object for thecurrent request.<bean id="httpServletRequest" scope="request" factory-bean="springUtility" factory-method="getHttpServletRequest" />

Cartridge handlers that need access to the servlet request can specify a reference to this bean asfollows:<property name="httpServletRequest" ref="httpServletRequest" />

Search and navigation request configurationThe Assembler provides several utilities for parsing incoming requests and forming MDEX Enginequeries.

MDEX resource configuration

The MDEX resource provides access to the MDEX Engine and manages information about the MDEXEngine and its schema configuration. Cartridge handlers can request data from their MDEX resourceduring the course of processing a cartridge.

The MDEX resource has the following properties:

DescriptionMDEX resource property

The hostname or IP address of your MDEX Engine server.host

The port on which the MDEX Engine server listens.port

The name of the property that serves as the record spec inyour data set.

recordSpecName

Navigation state builder configuration

The navigation state builder is responsible for parsing the request URL into a NavigationStateobject and for generating Endeca URLs based on a NavigationState.

DescriptionNavigation state builder property

Specifies the UrlFormatter object to use for parsing therequest URL into a NavigationState object and forgenerating Endeca URLs based on a NavigationState.

urlFormatter

Note: In the Discover Electronics application, this beanis configured in endeca-url-config.xml.

The MdexRequestBuilder implementation to use forforming MDEX Engine requests. For more information, see

mdexRequestBuilder

"About configuring cartridge handlers that make search andnavigation queries."

Specifies the ContentPathProvider implementation thatprovides the URL path info for a navigation query or a record

contentPathProvider

query. A reference implementation, BasicContentPath¬


43Building Applications with the Endeca Assembler | Assembler configuration

DescriptionNavigation state builder property

Provider, is included as part of Discover Electronics. Asconfigured in the example below, it returns /browse fornavigation queries and /detail for record detail queries.

The name of a property, dimension, or search interfaceagainst which searches (using the Search Box cartridge) areperformed.

defaultSearchKey

The match mode to use for text searches. Valid values forthis property follow the syntax of URL parameters for searchmode, without the mode+match prefix.

defaultMatchMode

A default filter state to apply to all queries. See below formore details about default filter state configuration; allproperties of the default filter state are optional.

defaultFilterState

These properties configure which URL parameters from therequest URL are preserved when generating action strings

removeAlways and which ones are removed, depending on the type oftransition the action URL represents.removeOnUpdateFilterState

removeOnClearFilterState

A list of dimensions whose dimension values should beapplied to the navigation state for a record query (based on

recordDetailsDimensionNames

the values that are tagged on that record). This navigationstate can be used for triggering configuration for theassociated record detail page or for a spotlight cartridge thathas the "restrict to refinement state" option enabled.

DescriptionFilter state property

A rollup key (used for aggregated records) to apply to allqueries made with the default filter state.

rollupKey

Specifies whether to apply automatic phrasing to text searchqueries. By default, automatic phrasing is enabled. For more

autoPhraseEnabled

information about automatic phrasing configuration, see"About implementing automatic phrasing" in this guide.

A default record filter to apply to MDEX Engine queries. Forinformation about the record filter syntax, refer to the MDEXEngine Advanced Developer's Guide.

securityFilter

The language ID (as a valid RFC-3066 or ISO-639 code) tospecify for MDEX Engine queries. For information about

languageId

working with internationalized data, refer to theMDEXEngineAdvanced Developer's Guide.

About configuring cartridge handlers that make search and navigation queriesCartridge handlers that need to make MDEX Engine queries can reference the navigation state, recordstate, and MDEX request builder beans configured in the cartridge support section of the Spring contextfile.


Building Applications with the Endeca Assembler | Assembler configuration44

The navigation state and record state represent the query parameters for each type of MDEX Enginequery. The MDEX request builder consolidates requests from all the cartridge handlers in a singleAssembler processing cycle into as few MDEX queries as possible. These beans are defined in termsof previously configured beans; their configuration should not need to vary between applications..

The NavigationCartridgeHandler references the navigationState and mdexRequest¬Builder beans for making navigation queries. The RecordDetailsHandler references therecordState for record detail queries. Cartridge handlers (including many of the core cartridges)that need access to the navigation state, record state, or the MDEX request builder typically extendone of these handlers. Note that RecordDetailsHandler itself extends NavigationCartridge¬Handler as shown below, thereby inheriting the references to the navigation state and MDEX requestbuilder specified in the NavigationCartridgeHandler bean.<bean id="NavigationCartridgeHandler" abstract="true"> <property name="navigationState" ref="navigationState" /> <property name="mdexRequestBuilder" ref="mdexRequestBuilder" /></bean>

<bean id="CartridgeHandler_RecordDetails" class="com.endeca.infront.cartridge.RecordDetailsHandler"parent="NavigationCartridgeHandler" scope="prototype" >

<property name="recordState" ref="recordState" /></bean>

About configuring cartridges to retrieve dynamic contentCartridge handlers that need to retrieve content dynamically from content collections based on triggercriteria can reference the content manager bean configured in the cartridge support section of theSpring context file.

The content manager depends on the content trigger state builder and its associated content triggerstate, which perform similar functions to the navigation state builder and navigation state, only for thetrigger query that retrieves dynamic content configuration, rather than the main navigation query.

Application-specific configuration for these beans relates to preview and auditing functionality. Formore information about configuring preview, see "Setting up the Preview Application for Workbench."

The ContentSlotHandler references the content manager to make dynamic content queries. Otherhandlers that need to retrieve contents from a content collection should extend from this handler.<bean id="CartridgeHandler_ContentSlot" class="com.endeca.infront.cartridge.ContentSlotHandler" scope="prototype"> <property name="contentManager" ref="contentManager" /></bean>

Related LinksSetting up the Preview Application for Workbench on page 115

If you are using Experience Manager, you can use a preview application to simulate sets oftrigger conditions, such as time-based triggers, in order to determine which content itemsdisplay when specific conditions are met. This section describes how to set up a customEndeca application to function as the preview application in Workbench.


45Building Applications with the Endeca Assembler | Assembler configuration

About configuring the Assembler servletThe Spring Assembler servlet extends the AbstractAssemblerServlet class, which requires amethod for retrieving an AssemblerFactory, and another for retrieving a ResponseWriter thatprocesses Assembler output.

The Assembler servlet references the same Spring configuration as the rest of the Assembler, withan additional dependency on response writer configuration.

Response writers

The Assembler servlet uses JSON or XML response writers to serialize the results of a query. TheAssembler includes default implementations of a JSONResponseWriter and an XMLResponseWrit¬er. You can provide your own implementation if you need to output the Assembler response to adifferent format (such as a different XML representation).<bean id="jsonResponseWriter" class="com.endeca.infront.assembler.servlet.JsonResponseWriter" scope="singleton"/>

<bean id="xmlResponseWriter" class="com.endeca.infront.assembler.servlet.XmlResponseWriter" scope="singleton"/>

Reference implementations

The reference content includes two Web applications that run the Spring Assembler servlet with theappropriate configuration for Discover Electronics in either an authoring or a live environment:

• The implementation for an authoring environment is located atreference\discover-service-authoring.

• The implementation for a live environment is located at reference\discover-service.

Invoking the Assembler in JavaYou invoke the Assembler by passing in a content item object to be assembled.

The content item that is passed as input to the Assembler is known as the configuration model. TheAssembler invokes the appropriate cartridge handler to process that content item, which may in turninvoke other cartridge handlers to process child content items. The end result of the processing cycleis another content item representing the response model.// Get the AssemblerFactory from the Spring context and // create an AssemblerWebApplicationContext webappCtx = WebApplicationContextUtils.getRequiredWebApplicationContext(application);AssemblerFactory assemblerFactory = (AssemblerFactory)webappCtx.getBean("assemblerFactory");Assembler assembler = assemblerFactory.createAssembler();assembler.addAssemblerEventListener(new MyLogger());

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

You can instantiate any configuration model programmatically and pass it to the Assembler, but typicallyan assembly cycle begins with a ContentInclude or ContentSlotConfig item. Both of these


Building Applications with the Endeca Assembler | Invoking the Assembler in Java46

methods retrieve additional content configuration specified in Workbench, the former by URI, and thelatter by triggering content from a collection populated either in Experience Manager or Rule Manager.

Note: If you have only purchased Oracle Endeca Guided Search, you typically query theAssembler using one of the packaged services, either with a ContentInclude item or via theAssembler servlet.

Related LinksAbout retrieving Assembler results using the packaged services on page 50

If you have purchased Oracle Endeca Guided Search (without Oracle Endeca ExperienceManager), you must retrieve Assembler results via the packaged services. These servicesare also available for Experience Manager implementations.

Invoking the Assembler with a ContentInclude itemThe content include mechanism retrieves content configuration that a content administrator has specifiedin the sitemap section of Experience Manager.

In an authoring instance the content configuration is stored in the Endeca Configuration Repository.In a live instance, the Assembler retrieves the content configuration from the live content source. Thisis specified in the CartridgeHandler_ContentInclude bean in assembler-context.xml.

The ContentInclude item specifies the URI from which to retrieve the content.• In Oracle Endeca Experience Manager implementations, the URI typically begins with /pages (a

hard-coded path to distinguish the sitemap from the content collections in Experience Manager),with the path info from the request URL appended.

• In Oracle Endeca Guided Search implementations, the URI must begin with /services andspecify one of the Assembler packaged services.

The following shows an example of a content include query that retrieves the page content for theDiscover Electronics application with Experience Manager:// Construct a content include to query the content source// for content, given the path info of the requestContentItem contentItem = new ContentInclude("/pages" + request.getPathInfo());

The ContentIncludeHandler retrieves the content that matches the deepest path in the URI. Forexample, if the request URL ishttp://www.example.com/browse/electronics/Sony/Cameras,the URI passed to the Assembler is /pages/browse/electronics/Sony/Cameras. Supposethat the sitemap for this site looks like the following:

The cartridge handler first tries to retrieve the content at the exact URI. There is no content at thatlocation, so it attempts to find the deepest matching path, which in this case is the content configuration


47Building Applications with the Endeca Assembler | Invoking the Assembler in Java

at /browse/electronics. The Assembler then processes the content item at that location andreturns the response for rendering.

Invoking the Assembler with a ContentSlotConfig itemThe content slot mechanism retrieves configuration from a content collection based on a set of triggercriteria.

The ContentSlotConfig specifies a content collection and the number of content items to returnfrom that collection.

The following shows an example of a content slot query that drives the autosuggest feature of theSearch Box cartridge:// Construct a content slot config to query content// in the SearchBoxAutoSuggestContent collectionContentItem contentItem = new ContentSlotConfig(request.getParameter("col¬lection"), 1);

The ContentSlotHandler uses these parameters to form a content trigger request to fetch the topconfiguration content item (or items) from the collection by priority. The Assembler then processes thecontent items from the collection and returns them as part of the response for rendering.

Content slots within other content itemsYou can construct a ContentSlotConfig as the root content item of an Assembler query, but othercontent items can also contain content slots that are configured to retrieve content dynamically fromcollections.

For example, in Discover Electronics the /browse path corresponds to a page within the sitemap.The browse page consists of a content slot that references the Web Browse Pages collection. Mostof the pages within the Web Browse Pages collection contain a mixture of content items that areconfigured directly in the page, and content slots that retrieve content from other collections. As theAssembler processes the query for http://www.example.com/discover/browse (assuming nosearch terms or refinement selections), the following steps occur:

1. The Assembler is invoked with a ContentInclude item with the URI /pages/browse.2. The Assembler invokes the ContentIncludeHandler to retrieve the configuration for the browse

page, which is a ContentSlotConfig that specifies a single content item from the Three-ColumnPage collection.

3. The Assembler invokes the ContentSlotHandler to retrieve the highest priority content itemwithin the Three-Column Page collection. In this case, it is the Default Browse Page, which is aThreeColumnPage.

4. There is no cartridge handler configured to process the ThreeColumnPage, but it contains childcontent items, so the Assembler goes on to process the child content items:

a. It passes the configuration for the search box cartridge through to the response object.b. It invokes the BreadcrumbsHandler to process the breadcrumbs cartridge.c. It invokes the ContentSlotHandler to process the navigation slot, which in turn retrieves the

Default Guided Navigation configuration from the Guided Navigation collection and invokesDimensionNavigationHandler to process it.

d. It invokes the SearchAdjustmentsHandler to process the search adjustments cartridge.e. It invokes the ContentSlotHandler to process the results list slot, which in turn retrieves the

Default Results List configuration from the Results List collection and invokes Result¬sListHandler to process it.


Building Applications with the Endeca Assembler | Invoking the Assembler in Java48

f. It invokes the RecordSpotlightHandler to process the spotlight records.

Querying the Assembler ServiceThe Assembler Service provides a RESTful interface for making Assembler queries and retrievingresults in either JSON or XML.

You query the Assembler Service by making a GET request to a URL that specifies the location of acontent item that you wish to assemble. The URL should be of the following form:http://[hostname:port]/[servlet-path]/[content-URI]?[query-params]

In the reference deployment of the Assembler Service, the servlet path determines the format of theAssembler response. The deployment descriptor file (web.xml) in the reference deployment definestwo servlets:

Servlet descriptionServlet path

Returns the Assembler response as JSON./json

Returns the Assembler response as XML./xml

The difference between the servlets is in the ResponseWriter implementation that they use. It isalso possible to write an Assembler response writer that forwards the results to another servlet ratherthan serializing them.

The content-URI is the path to the content item to be assembled.• In Experience Manager implementations, the URI typically begins with /pages (a hard-coded path

to distinguish the sitemap from the content collections in Experience Manager), with the path infofrom the request URL appended.

• In Oracle Endeca Guided Search-only implementations, the URI must begin with /services andspecify one of the Assembler packaged services.

The Assembler servlet request URL http://www.example.com/json/pages/browse is equivalentto passing a ContentInclude item to the Assembler assemble() method with the URI/pages/browse and retrieving the results in JSON format.

Query parameters in an Assembler servlet request URL are processed the same way as in theembedded Java Assembler. For example, the URLhttp://www.example.com/json/browse?N=101022 with the reference Assembler servletdeployment returns the same results as http://www.example.com/discover/browse?N=101022in the reference Java application.

Making dynamic content queries to the Assembler servlet

Unlike the Assembler in embedded mode, which allows assembly of any configuration content item,all queries to the Assembler servlet are treated as content include queries. To request content from acontent collection based on a set of trigger criteria, you can create a content slot at a location in thesitemap that you can then specify in your Assembler request URL. In the reference implementation,the browse page is one example of a content item that is addressable by URI that then referencescontent items within a content collection.

Related LinksInvoking the Assembler with a ContentInclude item on page 47


49Building Applications with the Endeca Assembler | Querying the Assembler Service

The content include mechanism retrieves content configuration that a content administratorhas specified in the sitemap section of Experience Manager.

Content slots within other content items on page 48You can construct a ContentSlotConfig as the root content item of an Assembler query,but other content items can also contain content slots that are configured to retrieve contentdynamically from collections.

The Assembler servlet response formatThe Assembler provides response writer implementations that serialize the Assembler response toJSON or XML.

The Assembler response takes the form of a content item (that is, a map of properties). The propertiesare key-value pairs where the key is a string and the value may be one of the following types:

• String• Boolean• Integer• List (of any property type)• Item (a nested map of properties)

This structure makes it straightforward to serialize the response to JSON.

The XML output of the Assembler (using the default XmlResponseWriter) is not SOAP-compliant.The default XML format has the following characteristics:

• The root element of the response is <Item>.• <Item>may have either a type attribute whose value is equivalent to the template id that defined

the content item, or a class attribute in the case of a strongly typed reponse model for a contentitem.

• The child elements of <Item> are <Property> elements.• Each <Property> element has a name attribute whose value is the property key, and contains

either a <String>, <Boolean>, <Integer>, <List>, or <Item> element whose contentsrepresent the property value.

For convenience, the Discover Electronics reference application provides links to the JSON and XMLrepresentations of the Assembler response, which are identical to the output of the Assembler servlet.This link can be useful for debugging purposes, but it is not recommended as a primary means ofquerying the Assembler for JSON or XML-formatted results.

About retrieving Assembler results using the packagedservices

If you have purchased Oracle Endeca Guided Search (without Oracle Endeca Experience Manager),you must retrieve Assembler results via the packaged services. These services are also available forExperience Manager implementations.

The packaged services include the following:


Building Applications with the Endeca Assembler | About retrieving Assembler results using the packagedservices

50

DescriptionService URI

Returns dimension search results based on a text search./services/dimensionsearch

Returns record detail information for a given record./services/recorddetails

Returns search and navigation results including core Endecafeatures such as Guided Navigation, along with dynamic contentreturned from content collections.

/services/guidedsearch

You query the services by passing a ContentInclude item to the Assembler with the relevant serviceURI or making an Assembler servlet request specifying the service URI. The services are configuredto return results for a specific cartridge or set of cartridges.

The cartridges that are returned by the services cannot be configured on a per-instance basis in RuleManager or Experience Manager, but application-wide default configuration for the cartridges can bespecified in the Spring context file for the Assembler. The exception is the dynamic content that canbe configured in content collections and that is returned by the Guided Search Service, which can beconfigured in Rule Manager or Experience Manager.

The services are populated in the Endeca Configuration Repository (for use by the authoring instance)when you run initialize_services after deploying an application. They are promoted to the livecontent source when you promote the site configuration for the live instance.

Related LinksDefault cartridge configuration on page 80

You can specify default configuration settings for a cartridge as part of the cartridge handlerconfiguration in the Spring context file for the Assembler.

The Dimension Search ServiceThe Dimension Search Service returns dimension search results for a keyword search.

The service returns a single DimensionSearchResults object in a dimensionSearchResultsproperty, representing the list of dimensions that match the search term.

The default behavior of this cartridge is configured as part of the CartridgeHandler_Dimension¬SearchResults bean in the Spring context file for the Assembler. For information about theconfiguration options for the Dimension Search Results cartridge, refer to the Endeca Assembler APIReference (Javadoc) for the DimensionSearchResultsConfig class.

This service exists for cases where you want to retrieve dimension search results only (such as in thecase of an auto-suggest dimension search feature). Dimension search results are also returned aspart of the response from the Guided Search Service.

The following is an example of the results of a Dimension Search Service query for the URIhttp://localhost:8006/assembler-authoring/json/services/dimension¬search?Ntt=fla*&Dy=1, serialized to JSON:{ "@type": "DimensionSearchService", "name": "Dimension Search Service", "dimensionSearchResults": { "@type": "DimensionSearchResults", "totalNumResults": 13, "dimensionSearchGroups": [ {


51Building Applications with the Endeca Assembler | About retrieving Assembler results using the packagedservices

"@class": "com.endeca.infront.cartridge.model.Dimension¬SearchGroup", "dimensionSearchValues": [ … ], "dimensionName": "camera.flash" }, { "@class": "com.endeca.infront.cartridge.model.Dimension¬SearchGroup", "dimensionSearchValues": [ … ], "dimensionName": "product.features" }, { "@class": "com.endeca.infront.cartridge.model.Dimension¬SearchGroup", "dimensionSearchValues": [ … ], "dimensionName": "product.category" } ] }, "endeca:contentPath": "/services/dimensionsearch", "previewModuleUrl": "http://localhost:8006/preview"}

The Record Details ServiceThe Record Details Service returns record detail information for a given record.

The service returns a single RecordDetails object in a recordDetails property, representing thedetails for a single record or an aggregate record.

The default behavior of this cartridge is configured as part of the CartridgeHandler_RecordDe¬tails bean in the Spring context file for the Assembler. For information about the configuration optionsfor the Record Details cartridge, refer to the Endeca Assembler API Reference (Javadoc) for theRecordDetailsConfig class.

The following is an example of the results of a record details service query for the URI http://lo¬calhost:8006/assembler-authoring/json/services/recorddetails/Canon/Prima-Super-130U-Date/_/A-266556, serialized to JSON:{ "@type": "RecordDetailsService", "name": "Record Details Service", "recordDetails": { "@type": "ProductDetail", "record": { "@class": "com.endeca.infront.cartridge.model.Record", "numRecords": 1, "attributes": { … }, "records": [ { "@class": "com.endeca.infront.cartridge.model.Record",

"numRecords": 0, "attributes": { … } } ] } },



52

"endeca:siteRootPath": "/services", "endeca:contentPath": "/recorddetails", "previewModuleUrl": "http://localhost:8006/preview", "endeca:assemblerRequestInformation": { … }}

The Guided Search ServiceThe Guided Search Service returns search and navigation results including core Endeca features suchas Guided Navigation, along with dynamic content returned from content collections.

The properties returned as part of the response model, as well as their associated configuration, arelisted below:

Configuration modelConfiguration beanResponse modelProperty name

GuidedNavigation¬Config

CartridgeHan¬dler_GuidedNaviga¬tion

GuidedNavigationnavigation

BreadcrumbsConfigCartridgeHan¬dler_Breadcrumbs

Breadcrumbsbreadcrumbs

ResultsListConfigCartridgeHan¬dler_ResultsList

ResultsListresultsList

SearchAdjust¬mentsConfig

CartridgeHan¬dler_SearchAdjust¬ments

SearchAdjustmentssearchAdjustments

DimensionSearchRe¬sultsConfig

CartridgeHan¬dler_Dimension¬SearchResults

DimensionSearchRe¬sults

dimensionSearchRe¬sults

ContentSlotConfigCartridgeHan¬dler_Con¬tentSlotList

Depends on contents ofreferenced contentcollections

zones

The following is an example of the results of a guided search service query for the URI http://lo¬calhost:8006/assembler-authoring/json/services/guidedsearch?Ntt=pink+camera,serialized to JSON:{ "@type": "GuidedSearchService", "name": "Guided Search Service", "navigation": { "@type": "GuidedNavigation" }, "breadcrumbs": { "@type": "Breadcrumbs", "removeAllAction": "/services/guidedsearch", "refinementCrumbs": [ ], "searchCrumbs": [ … ], "rangeFilterCrumbs": [ ] }, "resultsList": { "@type": "ResultsList",



"totalNumRecs": 213, "sortOptions": [ … ], "firstRecNum": 1, "lastRecNum": 10, "pagingActionTemplate": "/services/guidedsearch?No=%7Boff¬set%7D&Nrpp=%7BrecordsPerPage%7D&Ntt=pink+camera", "recsPerPage": 10, "records": [ … ] }, "searchAdjustments": { "@type": "SearchAdjustments", "originalTerms": [ "pink camera" ] }, "zones": { "@type": "ContentSlotList" }, "endeca:contentPath": "/services/guidedsearch", "previewModuleUrl": "http://localhost:8006/preview"}

Note:

For details about the contents of the zones property, see "About dynamic content and theGuided Search Service."

About dynamic content and the Guided Search ServiceIn order to retrieve results from content collections as part of the response from the Guided SearchService, you must configure the default content slot list in the Spring context file for the Assembler.

The content slot list is configured in the CartridgeHandler_ContentSlotList bean inassembler-context.xml.

For each content collection that you want to enable for the Guided Search Service, add a ContentSlot¬Config bean to the contentSlotList as in the example below:<bean id="CartridgeHandler_ContentSlotList" class="com.endeca.infront.car¬tridge.ContentSlotListHandler" scope="prototype"> <property name="contentItemInitializer"> <bean class="com.endeca.infront.cartridge.ConfigInitializer" scope="request"> <property name="defaults"> <bean class="com.endeca.infront.cartridge.ContentSlotList¬Config" scope="singleton"> <property name="contentSlotList"> <list>

<bean class="com.endeca.infront.cartridge.ContentSlot¬Config" scope="singleton"> <property name="contentCollection" val¬ue="/content/Right Column Spotlights"/> <property name="ruleLimit" value="3"/> </bean> </list> </property> </bean> </property>



54

</bean> </property></bean>

For each ContentSlotConfig, specify the following properties:

ValueProperty name

The path to the collection from which you want to return results. Theexample above specifies a collection named Record Spotlight Contentin a folder named Web.

contentCollection

The maximum number of content items to return from this collection. TheAssembler returns up to this number of items that match the triggercriteria, based on priority.

ruleLimit

Recall the zones property returned by the guided search service query for the URI http://in¬front.eng.endeca.com:8006/assembler-authoring/json/services/guided¬search?Ntt=pink+camera:{

[Additional items removed from this response] "zones": { "@type": "ContentSlotList" }, "endeca:contentPath": "/services/guidedsearch", "previewModuleUrl": "http://localhost:8006/preview"}

The response model, determined by the configuration above, is the following:

About retrieving content item properties from packaged servicesThis topic outlines the logic required for retrieving properties from the Assembler response model forthe included Guided Search Service.

The example below includes processing logic within a renderer JSP file. Oracle recommends includingmost of your logic for handling Assembler responses in your cartridge handlers, as this minimizes theamount of duplicate code required across multiple renderers.

Note: API documentation for the Assembler packages is available in theassembler\apidoc\assembler directory of your Tools and Frameworks installation.

Retrieving information from the Assembler response

Recall the serialized Assembler response for the URI http://localhost:8006/assembler-au¬thoring/json/services/guidedsearch?Ntt=pink+camera:{ "@type": "GuidedSearchService", "name": "Guided Search Service", "navigation": { "@type": "GuidedNavigation" }, "breadcrumbs": { "@type": "Breadcrumbs", "removeAllAction": "/services/guidedsearch", "refinementCrumbs": [ ],



"searchCrumbs": [ … ], "rangeFilterCrumbs": [ ] }, "resultsList": { "@type": "ResultsList", "totalNumRecs": 213, "sortOptions": [ … ], "firstRecNum": 1, "lastRecNum": 10, "pagingActionTemplate": "/services/guidedsearch?No=%7Boff¬set%7D&Nrpp=%7BrecordsPerPage%7D&Ntt=pink+camera", "recsPerPage": 10, "records": [ … ] }, "searchAdjustments": { "@type": "SearchAdjustments", "originalTerms": [ "pink camera" ] }, "zones": { "@type": "ContentSlotList" }, "endeca:contentPath": "/services/guidedsearch", "previewModuleUrl": "http://localhost:8006/preview"}

To create a sample JSP file that invokes the Assembler:

1. Import the required packages and create the necessary objects for supporting the Assembler:<%@page language="java" contentType="text/html; charset=UTF-8" %><%@page import="com.endeca.infront.assembler.Assembler"%><%@page import="com.endeca.infront.assembler.AssemblerFactory"%><%-- additional imports removed from this example --%><%@page import="org.springframework.web.context.WebApplicationContext"%><%@taglib prefix="discover" tagdir="/WEB-INF/tags/discover" %><% // Create the Web Application Context object WebApplicationContext webappCtx = WebApplicationContextUtils.getRe¬quiredWebApplicationContext(application);

// Get the AssemblerFactory from the Spring context file AssemblerFactory assemblerFactory = (AssemblerFactory)webappCtx.get¬Bean("assemblerFactory");

2. Recall that the packaged services invoke the Assembler with a ContentInclude item. Createthe assembler object and the ContentInclude item, and pass it into the Assembler as theconfiguration model: // Create an Assembler object Assembler assembler = assemblerFactory.createAssembler();

// Construct a content include item for the Guided Search service ContentItem contentItem = new ContentInclude("/services/guidedsearch");



56


The Assembler returns a com.endeca.infront.assembler.ContentItem interface as theresponse model; this extends the Java Map interface. Assign this response to a responseCon¬tentItem object.

3. get the resultsList object from the responseContentItem: ContentItem resultsListItem = (ContentItem) responseContentItem.get("re¬sultsList");

This retrieves the top-level resultsList object, which is itself an extension of BasicCon¬tentItem, from the Assembler response.

4. You can now retrieve and use the individual values stored on the resultsList object, for example,the total number of records: String totalNumRecs = resultsListItem.get("totalNumRecs");

This assigns a value of "213" to the totalNumRecs variable (based on the sample responsepresented at the start of this topic). Similarly, you could retrieve any other value from the key/valuepairs that comprise resultsList, including other objects that extend the Map interface and arethemselves made up of key/value pairs.

Refer to the Assembler API documentation for additional information on available Assembler interfaces,implementations, and methods. Following the pattern described in Steps 3-4, you can continue toretrieve values from the Assembler response by calling the get method on the response model objectto traverse the nested values.

About handling the Assembler responseAs a best practice, your application should have modular renderers to handle the response model foreach content item.

A typical page consists of a content item that contains several child content items representing theindividual feature cartridges. The Discover Electronics application maps each response model to theproper renderer by convention, based on the @type. The model @type corresponds to the id of thetemplate that was used to configure it. (Recall that the template type determines where a cartridgecan be placed in another content item, while the template id uniquely identifies the cartridge and itsassociated content definition.) For each cartridge, the associated renderer is located inWEB-INF/views/<channel>/<TemplateID>/<TemplateID>.jsp. For example, the rendererfor the Breadcrumbs cartridge is located inWEB-INF/views/desktop/Breadcrumbs/Breadcrumbs.jsp.

In the Discover Electronics application, this logic is implemented in include.tag. Your applicationshould implement a similar mapping of response models to their corresponding rendering code.

Source code for the renderers in the Discover Electronics application is provided as an example ofhow to work with the model objects returned by the Assembler in Java. The sample rendering code isintentionally lightweight, enabling it to be more easily customized for your own site. For informationabout the response models for the core cartridges, refer to the Endeca Assembler API Reference(Javadoc).

Some features in the Discover Electronics application are designed with certain assumptions aboutthe data set, such as property and dimension names. Mirroring the Discover Electronics data schema


57Building Applications with the Endeca Assembler | About handling the Assembler response

for your own data can facilitate reuse of the reference cartridges, reducing the need to update renderinglogic and Assembler configuration for your data set.

About rendering the Assembler responseOnce you have retrieved the necessary information for your page, Oracle recommends subdividingyour view logic to correspond to the hierarchy of content items returned by the Assembler.

The renderer for the Three Column Navigation Page content item in Discover Electronics provides anexample of the page rendering process as implemented in the reference application. It is located inyour Tools and Frameworks installation directory underreference\discover-electronics-authoring\WEB-INF\views\desktop\ThreeColumnPage\ThreeColumnPage.jsp.You can use this JSP file as a point of reference for developing your own application pages. While thedetails are specific to the Discover Electronics implementation of the Assembler API, your generalapproach should be similar.

Recall that each of the <div> elements that make up the page uses a custom <discover:include>tag, defined in WEB-INF\tags\discover\include.jsp, to include the rendering code for theassociated page component:<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head>

</head><body> <endeca:pageBody rootContentItem="${rootComponent}"> <div class="PageContent"> <%--include user panel --%> <%@ include file="/WEB-INF/views/userPanel.jsp" %> <%--include user page logo --%> <%@ include file="/WEB-INF/views/pageLogo.jsp" %> <div class="PageHeader"> <c:forEach var="element" items="${component.headerContent}">

<discover:include component="${element}"/> </c:forEach> </div> <div class="PageLeftColumn"> <c:forEach var="element" items="${component.leftContent}">

<discover:include component="${element}"/> </c:forEach> </div> <div class="PageCenterColumn"> <c:forEach var="element" items="${component.mainContent}">

<discover:include component="${element}"/> </c:forEach> </div> <div class="PageRightColumn"> <c:forEach var="element" items="${component.rightContent}">

<discover:include component="${element}"/> </c:forEach> </div> <div class="PageFooter"> <%--include copyright --%>


Building Applications with the Endeca Assembler | About handling the Assembler response58

<%@include file="/WEB-INF/views/copyright.jsp" %> </div> </div> </endeca:pageBody></body></html>

For the example above, the JSP is composed as follows:

1. The static <div class="UserPanel"> and <div class="PageLogo"> elements are includedfrom the specified JSP files.

2. The <div class="PageHeader"> element retrieves the list of headerContent content itemsfrom the component.

• In an Oracle Endeca Experience Manager installation, this is the list of content items definedby the content administrator in Experience Manager:

• In an Oracle Endeca Guided Search installation, this is the list of content items specifiedapplication-wide under WEB-INF\services\browse.jsp:<div class="PageContent"> <%--include user panel --%> <%@ include file="/WEB-INF/views/userPanel.jsp" %> <%@ include file="/WEB-INF/views/pageLogo.jsp" %>

<div class="PageHeader"><discover:include component="${searchBox}"/>

</div> <div class="PageLeftColumn"> <discover:include component="${component.breadcrumbs}"/> <discover:include component="${component.navigation}"/> </div> ...

3. For each of the included content items, the JSP includes the output of the associated renderer.4. The <div class="PageLeftColumn">, <div class="PageCenterColumn">, and <div

class="PageRightColumn"> elements are included in the same fashion.5. The static <div class="Copyright"> element is included from the specified JSP file.


59Building Applications with the Endeca Assembler | About handling the Assembler response

For additional information on cartridge handlers and renderers, as well as a walkthrough of creatinga sample cartridge, refer to the Cartridge Development Guide.

Assembler event framework referenceThe Assembler includes an AssemblerEventListener interface that you can use to create andregister event listeners. Creating listeners enables you to retrieve or modify data at more granularpoints in the Assembly process.

Note that event listeners do not have access to the current Assembler request or to the navigationstate.

You can create an event listener for the following events:

ConditionEvent

Fires when an assemble() call starts.assemblyStarting

Fires when an assemble() call completes.assemblyComplete

Fires when an assemble()call is aborted due toan unrecoverable error.

assemblyError

Fires when a cartridge handler calls the initial¬ize() method.

cartridgeInitializeStarting

Fires when a call to the initialize() methodcompletes.

cartridgeInitializeComplete

Fires when a cartridge handler calls the prepro¬cess() method.

cartridgePreprocessStarting

Fires when a call to the preprocess() methodcompletes.

cartridgePreprocessComplete

Fires when a cartridge handler calls the pro¬cess() method.

cartridgeProcessStarting

Fires when a call to the process() methodcompletes.

cartridgeProcessComplete

Fires when a cartridge fails due to a local error.This stops execution of the cartridge handler

cartridgeError

workflow, and prevents any additional events fromfiring.

Event payload

Each Assembler event has an AssemblerEvent payload consisting of three objects:• Assembler source — the Assembler responsible for servicing the request.• Content item — the content item that is passed to the handler. This can be a cartridge configuration

model (with template, instance, and URL configuration) or a cartridge response model withinformation from the MDEX Engine.

• Cartridge handler — the cartridge handler associated with the event.


Building Applications with the Endeca Assembler | Assembler event framework reference60

Creating an event listenerThe Assembler provides an empty implementation of the AssemblerEventListener, Assem¬blerEventAdapter. You can extend this implementation to create a listener that triggers on anAssembler event.

To create an event listener:

1. Create a new Java class that extends the AssemblerEventAdapter.For example:public class ResultsListListener extends AssemblerEventAdapter {}

2. Override the methods that correspond to the events for which you wish to trigger custom processinglogic:public class ResultsListListener extends AssemblerEventAdapter {

@Override public void cartridgePreprocessStarting(AssemblerEvent event){ ... }

@Override public void cartridgeProcessComplete(AssemblerEvent event){ ... }}

For a list of Assembler events, see the Assembler event framework reference on page 60 or referto the Assembler API Reference (Javadoc).

3. Add conditional logic to restrict processing to a specific cartridge handler:public class ResultsListListener extends AssemblerEventAdapter { ...

@Override public void cartridgeProcessComplete(AssemblerEvent event){

if(event.getContentItem() != null && "ResultsList".equals(event.get¬ContentItem().getType()){

... } }}

4. Add processing logic.The example below prefixes the max_price property on a record with a dollar sign:public class ResultsListListener extends AssemblerEventAdapter {

...

@Override public void cartridgeProcessComplete(AssemblerEvent event){ if(event.getContentItem() != null && "ResultsList".equals(event.get¬ContentItem().getType()){

ResultsList resultsList = (ResultsList) event.getContentItem();

for(Record record : resultsList.getRecords()){


61Building Applications with the Endeca Assembler | Assembler event framework reference

Attribute price = record.getAttributes().get("prod¬uct.max_price"); if(price != null){ for(int i = 0 ; i < price.size(); i++){ price.set(i, "$" + price.get(i).toString()); } } } } }}

After creating a new listener, you must register it by including it in the list of listeners for the assem¬blerFactory object.

About registering an event listenerYou must register all event listeners with the AssemblerFactory object.

The AssemblerFactory takes event listeners as constructor arguments. These listeners areinstantiated with each Assembler object created by the factory class.

Optionally, you may also choose to use the Assembler.addAssemblerEventListener()methodto add a listener for a single assembly request.

Example

The example below uses the ResultsListListener defined in the previous topic, registered inthe Discover Electronics reference application.

The reference application uses the Assembler context file to configure global application properties.The configuration bean for the AssemblerFactory includes a list of listeners as constructorarguments:<bean id="assemblerFactory" class="com.endeca.infront.assem¬bler.spring.SpringAssemblerFactory" scope="singleton"> <constructor-arg> ... </constructor-arg> <constructor-arg>  <list>

<bean class="com.endeca.infront.ResultsListListener" /> <bean class="com.endeca.infront.logger.SLF4JAssemblerEventLogger" /> <bean class="com.endeca.infront.assembler.event.request.Con¬tentItemAugmentAdapter"> <constructor-arg ref="springUtility"/> </bean> ... </list> </constructor-arg></bean>


Building Applications with the Endeca Assembler | Assembler event framework reference62

About Assembler error handlingThe Assembler API defines two kinds of exceptions: AssemblerException and CartridgeHan¬dlerException.

The exceptions are distinguished as follows:

DescriptionException

Indicates that an exception occurred while creating or processingan Assembler request. Exceptions of this type indicate that the entireassembly process was terminated.

AssemblerException

Indicates that an exception occurred while invoking a single cartridgehandler. Exceptions of this type do not terminate the entire assemblyprocess.

CartridgeHandlerExcep¬tion

Both types of exceptions are returned as part of the Assembler response.

Error handling in the Assembler servlet

The Assembler servlet returns an HTTP status code of 200 (OK) regardless of whether any exceptionsoccurred during Assembler processing. The Assembler communicates error conditions as exceptionsthat are serialized as part of the response, as in the following example.{ @error: "com.endeca.infront.assembler.CartridgeHandlerException" description: "Detailed cartridge handler error description"}

Unchecked exceptions result in the Assembler servlet returning HTTP status code 500 (Internal ServerError).


63Building Applications with the Endeca Assembler | About Assembler error handling

Chapter 5

Working with Application URLs

Each of the user-facing pages in an Assembler application exists as a page with a correspondingnavigation or record state; the combination of the page and its state results in a specific set of resultsor a set of record details. The Assembler API includes an Action class for storing these URLcomponents and returning them as part of the output model produced by a cartridge handler.

About application URLsFeatures in a front-end application can provide one or more links to other locations within a site. Theinformation required for constructing these links is provided on the cartridge response model as anAction object that includes the components of a destination URL.

For example, a dimension refinement in a Refinement Menu cartridge has an associated action toselect the refinement and add it to the end user's navigation state. A record in a Results List cartridgehas an action to view the corresponding record detail page.

The Assembler API includes an ActionPathProvider interface that returns components of anapplication URL. For the Discover Electronics reference application, an implementation of this interfaceis configured in the NavigationCartridgeHandler.

Cartridge handlers in the reference application use this implementation to create NavigationActionpaths to a certain navigation state (like the modified navigation state created when a user selects adimension refinement), or RecordAction paths to specified records (such as a record select fromthe results list).

About ActionsAn Action object allows you to construct a link that represents a decision by an end user. The includedfields and values depend on the action that the user wishes to take; they can include the action label,the root site path, and the path to the destination content within the site.

The Action class does not include a complete URL to the resulting navigation state or record; instead,the URL resulting from an Action is generally created by combining fields. For details, see "Actionfields."

The Assembler splits the class into three subclasses:• NavigationAction — An Action that represents changing the current navigation state, such as

through a search query or the addition of a dimension refinement. For example, the "See All" link

on a RecordSpotlight object includes a NavigationAction for navigating to the refinementstate represented by the spotlight.

• RecordAction— An Action that represents selecting a record or aggregate record. The individualrecords in a RecordSpotlight each include a RecordAction for selecting that record.

• UrlAction — An Action that represents following an arbitrary URL. The Media Banner cartridgeincludes a UrlAction for URLs that are manually specified in Experience Manager.

Note: For information on the Actions associated with each output model, refer to the AssemblerAPI Reference (Javadoc) for the corresponding class.

Action fieldsAll Actions include the following fields:

DescriptionField

The label that displays to the application end-user for the specified action. Forexample, you might set this to a product name for a link from a results list to a record

Label

detail page, or it you might set it to a dimension refinement name when displaying abreadcrumb with an associated Action to remove the refinement and adjust the user'snavigation state.

The path that identifies the site associated with the Action.Site root path

The path that identifies the content associated with the Action within the containingsite . In the Discover Electronics reference application, this is the servlet that handlesthe specified content type, such as /browse or /detail.

Content path

Additionally, certain types of Actions may include additional fields. A NavigationAction includesa field for the navigation state represented by the Action, while a RecordAction action includes afield for the corresponding record state.

Using action fields

To construct a useable link from an Action, the UI tier of your application (the cartridge renderers inthe Discover Electronics reference application) must include logic for combining the Action fields. Atypical use case consists of directly concatenating fields, depending on the type of page you wish tolink to.

In the reference application, a link to a navigation state typically combines the content path and thedesired navigation state:String href = action.getContentPath() + action.getNavigationState();

A link to a record details page combines the content path with the appropriate record state:String href = action.getContentPath() + action.getRecordState();

A link to an arbitrary URL does not require combining fields, since the UrlAction object includes amethod for directly retrieving a configured URL:String href = action.getUrl();

Most of the Discover Electronics cartridge renderers use the <discover:link> tag, defined inWEB-INF\tags\discover\link.tag. The tag makes use of the getUrlForAction functiondeclared in WEB-INF\tlds\functions.tld and defined inWEB-INF\classes\com\endeca\infront\refapp\support\FunctionTags.java.


Working with Application URLs | About Actions66

About using Actions with the packaged servicesThe packaged services in Oracle Endeca Tools and Frameworks return specific actions for the includedcartridges.

The following is an example of the results of a guided search service query for the URI http://lo¬calhost:8006/assembler-authoring/json/services/guidedsearch?Ntt=pink+camera,serialized to JSON:{ "@type": "GuidedSearchService", "name": "Guided Search Service", "navigation": { … }, "breadcrumbs": { … }, "resultsList": { "@type": "ResultsList", "totalNumRecs": 213, "sortOptions": [ { "@class": "com.endeca.infront.cartridge.model.SortOptionLa¬bel", "selected": false,

"navigationState": "?Ntt=pink+camera", "contentPath": "/guidedsearch", "siteRootPath": "/services", "label": "Relevance" }, { "@class": "com.endeca.infront.cartridge.model.SortOptionLa¬bel", "selected": false,

"navigationState": "?Ns=product.price%7C0&Ntt=pink+camera",

"contentPath": "/guidedsearch", "siteRootPath": "/services", "label": "Price (Ascending)" }, { … } ], "firstRecNum": 1, "lastRecNum": 10, "pagingActionTemplate": { … }, "recsPerPage": 10, "records": [ { "@class": "com.endeca.infront.cartridge.model.Record", "detailsAction": { "@class": "com.endeca.infront.cartridge.model.RecordAc¬tion",

"recordState": "/Kodak/Slim-Camera-Case/_/A-2707821", "contentPath": "/recorddetails", "siteRootPath": "/services" }, "numRecords": 1, "attributes": { … }, "records": [ … ] },

{ content removed from this example } ] },


67Working with Application URLs | About Actions

"content removed from this example"}

Note that the sortOptions returned for the Results List cartridge include the Action fields requiredto create a URL for the navigation state resulting from modifying the sort order. Sorting by Price(Ascending) requires constructing a URL with the appropriate navigationState, resulting inhttp://localhost:8006/assembler-authoring/json/services/guidedsearch?Ns=product.price|0&Ntt=pink+camera.Querying this URL returns the JSON response for the re-ordered results.

Similarly, each of the records returned in the Results List includes the Action fields for an associatedrecord details page. Using the /recorddetails content root and the recordState for the SlimCamera Case results in the URLhttp://localhost:8006/assembler-authoring/json/services/recorddetails/Kodak/Slim-Camera-Case/_/A-2707821.Querying this URL returns the record details for the Slim Camera Case.

About working with URL parametersThe navigationStateBuilder handles both Endeca-specific and non-Endeca URL parameters.

All URL parameters are parsed into the parameters map in the NavigationState object thatrepresents the user's current navigation state. Endeca-specific parameters are used in constructingMDEX Engine queries. All other parameters are included in the navigation state or record state fieldson the Action object in the output model. You can change this default behavior by specifying whichparameters to remove when generating Actions:

DescriptionProperty

A list of URL parameters that should be removedfrom all Actions.

removeAlways

A list of URL parameters that should be removedfrom an Action when the Action represents achange in the filter (search or navigation) state.

removeOnUpdateFilterState

A list of URL parameters that should be removedfrom an Action when the user clears the filter stateof all search and navigation selections.

removeOnClearFilterState

About URL configuration in the reference applicationURL configuration in the Discover Electronics reference application is located in the Assembler contextfile, WEB-INF\assembler-context.xml. Configuration is divided between the navigationState¬Builder and the NavigationCartridgeHandler.

The configuration for the navigationStateBuilder specifies a urlFormatter to use whenserializing a NavigationState:

<bean id="navigationStateBuilder" scope="request"


Working with Application URLs | About working with URL parameters68

class="com.endeca.infront.navigation.url.UrlNavigationStateBuilder">

<property name="urlFormatter" ref="seoUrlFormatter" /> <property name="mdexRequestBroker" ref="mdexRequestBroker"/> <property name="defaultSearchKey" value="All" /> <property name="defaultMatchMode" value="ALLPARTIAL" /> <property name="defaultFilterState">

 </property>

Note: The seoUrlFormatter bean is defined in the imported endeca-seo-url-configfile.

Configuring URL parameters

The configuration for the navigationStateBuilder also lets you specify the URL parameters toremove from the request URL when serializing a NavigationState or RecordState:

<property name="removeAlways"> <list> <value>contentText</value> <value>Nty</value> <value>Dy</value> <value>collection</value> </list>

</property> <property name="removeOnUpdateFilterState"> <list> <value>No</value> </list> </property>

<property name="removeOnClearFilterState"> <list> <value>Ns</value> <value>Nrpp</value> <value>more</value> </list>

</property></bean>

Configuration for navigation and record paths

The content paths that prefix navigation and record states when creating Action URLs are configuredin the actionPathProvider of the NavigationCartridgeHandler as sets of key-value pairs:<bean id="NavigationCartridgeHandler" abstract="true"> <property name="navigationState" ref="navigationState" /> <property name="mdexRequestBroker" ref="mdexRequestBroker" /> <property name="actionPathProvider"> <bean scope="request" class="com.endeca.infront.refapp.navigation.Ba¬sicActionPathProvider"> <constructor-arg index="0" ref="contentSource"/> <constructor-arg index="1" ref="httpServletRequest"/>

 <constructor-arg index="2"> <map> <entry key="^/pages/mobile/detail$" value="/pages/mo¬bile/browse" />


69Working with Application URLs | About URL configuration in the reference application

<entry key="^/pages/detail$" value="/pages/browse" /> </map> </constructor-arg>  <constructor-arg index="3"> <map> <entry key="^/pages/mobile/.*$" value="/pages/mobile/de¬tail" /> <entry key="^/pages/.*$" value="/pages/detail" /> </map> </constructor-arg> </bean> </property></bean>

URL formatter configurationThe Discover Electronics reference application serializes NavigationState objects through the useof a UrlNavigationStateBuilder configured with a UrlFormatter. By default, the applicationis configured for search engine optimized (SEO) URLs using the SeoUrlFormatter class, but it alsoincludes a BasicUrlFormatter for creating basic Endeca URLs.

The basic URL formatter

The following properties can be set on the basicUrlFormatter bean:

DescriptionProperty

Specifies the default query encoding, for example, UTF-8.defaultEncoding

Specifies whether a question mark is prepended to the URLparameter portion of the URL, after the servlet path.

prependQuestionMark

The configuration in WEB-INF\endeca-url-config is shown below:

<bean id="basicUrlFormatter" class="com.endeca.soleng.urlformatter.basic.Ba¬sicUrlFormatter"> <property name="defaultEncoding"> <value>UTF-8</value> </property>

<property name="prependQuestionMark"> <value>true</value> </property></bean>

The SEO URL formatter

The following properties can be set on the seoUrlFormatter bean:


Working with Application URLs | About URL configuration in the reference application70

DescriptionProperty

Specifies the default query encoding, for example, UTF-8.defaultEncoding

The separator token used to separate the path section of the URLfrom the parameter section.

pathSeparatorToken

The character used to separate key/value pairs in the parametersection of the URL.

pathKeyValueSeparator

Specifies the URL parameter keys for the following:pathParamKeys

• The parameter key used for record detail links. The default valueis R.

• The parameter key used for aggregate record detail links. Thedefault value is A.

• The parameter key used for navigation state. The default value isN.

The NavStateFormatter that maps navigation state information toURL path keywords.

navStateFormatter

The ERecFormatterthat maps Endeca record attributes to URL pathkeywords.

ERecFormatter

The AggrERecFormatter that maps aggregate record attributes toURL path keywords.

aggrERecFormatter

Specifies the canonicalizer used to sort URL parameters to ensurethat included parameters are arranged a specific order.

navStateCanonicalizer

Determines whether or not the canonicalizer specified in navState¬Canonicalizer is used. The default value is true. This value isignored if the canonicalLinkBuilder enables canonical links.

useNavStateCanonicaliz¬er

A list of UrlParamEncoder objects to use for encoding URLparameters.

urlParamEncoders

The configuration in WEB-INF\endeca-seo-url-config is shown below: <bean id="seoUrlFormatter" class="com.endeca.soleng.urlformat¬ter.seo.SeoUrlFormatter">

<property name="defaultEncoding"> <value>UTF-8</value> </property>

<property name="pathSeparatorToken"> <value>_</value> </property>


71Working with Application URLs | About URL configuration in the reference application

<property name="pathKeyValueSeparator"> <value>-</value> </property>

<property name="pathParamKeys"> <list> <value>R</value> <value>A</value> <value>N</value> </list> </property>

<property name="navStateFormatter"> <ref bean="navStateFormatter"/> </property>

<property name="ERecFormatter"> <ref bean="erecFormatter"/> </property>

<property name="aggrERecFormatter"> <ref bean="aggrERecFormatter"/> </property>

<property name="navStateCanonicalizer"> <ref bean="navStateCanonicalizer"/> </property>

<property name="useNavStateCanonicalizer"> <value>false</value> </property>

<property name="urlParamEncoders"> <list> <ref bean="N-paramEncoder"/> </list> </property></bean>

About working with canonical linksConfigure the Assembler to add canonical link support to the root content item.

The canonical link configuration in the Discover Electronics reference application is located in theAssembler context file, WEB-INF\assembler-context.xml. Configuration is handled by thecanonicalLinkBuilder which constructs links for navigation state and record state URLs thatinclude the canonical link element.

The Canonical Link Builder

The following properties can be set on the canonicalLinkBuilder:

DescriptionProperty

Allows the retrieval of services without explicitinjection. In this case, it is used to reference the

objectLocator


Working with Application URLs | About working with canonical links72

DescriptionProperty

framework for retrieving the recordState andnavigationState for the current request.

The ID of the recordState being retrieved, notthe actual recordState.

recordStateId

The ID of the navigationState being retrieved,not the actual navigationState.

navigationStateId

The list of URL parameters that are included in thecanonical link.

includedParameters

The configuration for the canonicalLinkBuilder specifies an objectLocator to use whencreating canonical links:<bean id="assemblerFactory" class="com.endeca.infront.assem¬bler.spring.SpringAssemblerFactory">... <constructor-arg> <list> ... <bean class="com.endeca.infront.navigation.url.event.CanonicalL¬inkBuilder"> <property name="objectLocator" ref="springUtility"/> <property name="recordStateId" value="recordState"/> <property name="navigationStateId" value="navigationState"/>

<property name="includedParameters"> <list> <value>R</value> <value>A</value> <value>N</value> <value>Ntt</value> </list> </property> </bean> </list> </constructor-arg></bean>

Output content items

The Assembler API returns navigation state and record state content items as output from theCanaonicalLinkBuilder. The following examples are JSON representations of the output.

NavigationState{ name: "Static Page Slot", ..., canonicalLink: { @class: "com.endeca.infront.cartridge.model.NavigationAction", navigationState: "/Canon/cameras/_/N-1z141xuZ1z141yaZ25y6Zej4?for¬mat=json", contentPath: "/browse", siteRootPath: "/pages", label: ""


73Working with Application URLs | About working with canonical links

}}

RecordState{ name: "Static Page Slot", ..., canonicalLink: { @class: "com.endeca.infront.cartridge.model.RecordAction", recordState: "/_/A-1318562?format=json", contentPath: "/detail", siteRootPath: "/pages", label: "" }}

For each of the content items, a JSP file can render output as in this example:<link rel="canonical" href="<c:url value='${util:getUrlForAction(rootCompo¬nent.canonicalLink)}'/>"/>


Working with Application URLs | About working with canonical links74

Chapter 6

Implementing Multichannel Applications

This section covers how to design and implement multichannel applications built on the Assemblerand managed using Workbench with Experience Manager.

Overview of multichannel applications with the EndecaAssembler

The Endeca Assembler provides an API for delivering content across an entire site, allowing contentconfiguration to be shared between channels when appropriate, and also enabling a more targetedchannel-specific experience where desired.

Enabling the full flexibility of the cross-channel experience involves the following:• Creating channel-specific templates. Content administrators may wish to configure different

features or cartridges for different channels. For example, pages designed for mobile devicestypically have a simpler structure and present fewer options than pages designed for desktop Web.

• Writing channel-specific rendering code. Due to the limitations of mobile browsers and devicebandwidth, renderers for mobile Web applications are typically more lightweight than those fordesktop Web, while native applications for mobile devices require platform-specific client code.

• Enabling device detection. The UI tier of your Assembler application should include logic forhandling device detection. Typically, this also includes redirecting a client to the appropriate servicefor their user agent.

Note: Endeca for Mobile is licensed separately from Oracle Endeca Guided Search and OracleEndeca Experience Manager. It requires an additional software license.

About creating templates for mobile channelsThe set of templates in a multichannel application should give content administrators the flexibility tomanage channel-specific content in Experience Manager. At the same time, it should enable them toshare configuration across channels whenever possible in order to provide the maximum consistencythroughout a site.

The following general practices help enable this combination of flexibility and consistency:• Create different top-level page templates for channels that have a different high-level structure.

For example, the same range of cartridges may not be appropriate to a page designed to display

on a mobile device as opposed to a page designed to display on a desktop computer. Nativeapplications for mobile devices may display content in "pages" that differ from those intended formobile Web browsers.

• Use dynamic slots for configuration that should be shared across channels, similar to how dynamicslots enable reuse of content between pages. For example, if the same refinement configuration(such as overall dimension order, refinement ordering, and boost and bury options) should applyat a specific navigation state regardless of channel, it may make sense to configure this in aseparate content collection for navigation and reference it from the appropriate pages for eachchannel.

To enable the greatest flexibility in Experience Manager while ensuring that content administratorscreate configurations that are appropriate to each channel, you can restrict the cartridges that can beplaced on a page or in a content collection via the content type mechanism in Experience Manager.These content types may vary depending on the intended purpose of a page or dynamic slot. Forexample, you may have the following in your application:

• Page templates for desktop Web, which may define a section of type SecondaryContent. Thissection may be populated with Guided Navigation cartridges, Spotlight cartridges, or dynamic slotsserving as a placeholder for either type.

• A content collection designed for Guided Navigation cartridges. This is similar to the Navigationsection of the mobile page, but it should not allow a content administrator to create a dynamic slotwithin a dynamic slot, so it should have a third content type (such as Navigation) to enforce thisrestriction.

In most cases, all the Dimension Navigation cartridges in an application should be identical as theconfiguration of data-driven cartridges should be the same regardless of channel. Each of theseidentical cartridges should be mapped to the same cartridge handler in the Endeca Assembler. Formore information about configuring cartridge handlers, refer to the Endeca Assembler ApplicationDeveloper's Guide.

About device detection in the reference applicationThe reference application uses a DeviceManager class in the com.endeca.mobile.services.de¬tection package to parse user agent strings and determine the appropriate content path and renderingchannel for a request.

Each end user request is sent to the application controller, WEB-INF\services\assemble.jsp.The controller determines the device channel, dispatches the request to the Assembler, then sendsthe resulting response model to the appropriate renderer:<% //The channel to prefix map. See the DeviceManager class for more info

//Note: LinkedHashMap will preserve the order of entries Map<String,String> channelToPagePrefixMap = new Linked¬HashMap<String,String>(); channelToPagePrefixMap.put("Endeca.Infront.Channel.Mobile","/mobile");

//This channel is the default one. This entry should be the last one in the map //because all strings start with the empty string. channelToPagePrefixMap.put("Endeca.Infront.Channel.Desktop","");

//The resources map. See the DeviceManager class for more info Map<String,String> resourcesMap = new LinkedHashMap<String,String>(); resourcesMap.put("/desktop", "/WEB-INF/views/desktop/");


Implementing Multichannel Applications | About device detection in the reference application76

resourcesMap.put("/mobile", "/WEB-INF/views/mobile/");

//The list of the pages that will get redirected. See the DeviceManager class for more info List<String> validMobilePages = new ArrayList<String>(); validMobilePages.add("/browse"); validMobilePages.add("/detail");

DeviceManager deviceManager = new DeviceManager(channelToPagePrefixMap, validMobilePages, resourcesMap);

//AssemblerFactory, spring context, and user state creation removed from this example

String userAgent = userState.getUserAgent();

//If the userAgent is null, then no user-agent was specified and we need to use the original one. if(userAgent == null){ userAgent = request.getHeader("user-agent"); }

String contentUri = deviceManager.getContentPath(request.getPathInfo(), userAgent);

if(!contentUri.equals(request.getPathInfo())){ String query = request.getQueryString() == null ? "" : "?" + re¬quest.getQueryString(); response.sendRedirect(request.getContextPath() + contentUri + query);

}else{// Assembler and ContentInclude creation removed from this example

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

// If the response contains an error, send an error// error handling removed from this example

else { // Determine the output format and write to response String format = request.getParameter("format"); if("json".equals(format)) { response.setHeader("content-type", "application/json"); new JsonSerializer(response.getWriter()).write(responseCon¬tentItem); } else if ("xml".equals(format)) { response.setHeader("content-type", "application/xml"); new XmlSerializer(response.getWriter()).write(responseCon¬tentItem); } else { request.setAttribute("component", responseContentItem); request.setAttribute("rootComponent", responseContentItem);

// This is used by the discover:include tag request.setAttribute("Endeca.InFront.ComponentResourcePath", deviceManager.getResourcePath(contentUri));


77Implementing Multichannel Applications | About device detection in the reference application

%> <discover:include component="${component}"/> <% } } }%>

For more information about content paths and application URLs, see "Working with Application URLs."

Related LinksWorking with Application URLs on page 65

Each of the user-facing pages in an Assembler application exists as a page with acorresponding navigation or record state; the combination of the page and its state resultsin a specific set of results or a set of record details. The Assembler API includes an Actionclass for storing these URL components and returning them as part of the output modelproduced by a cartridge handler.


Implementing Multichannel Applications | About device detection in the reference application78

Chapter 7

Configuring Front-End Application Features

This section describes the cartridge configuration model for front-end application features, and providesa description of the core cartridges in Oracle Endeca Tools and Frameworks.

About configuring application featuresFeatures in an Assembler application are implemented as cartridges. In the Discover Electronicsreference application, the behavior of cartridges depends on multiple sources of configuration. Theseare combined into a configuration model.

Cartridge-specific configuration falls into the following categories, in ascending order of priority:• MDEX Engine configuration, which may be specified as part of the data integration process or

by a configuration update• Default cartridge configuration, which is typically specified in the Spring context file for the

Assembler• Cartridge instance configuration, which is typically specified by the content administrator in

Workbench• Request-based configuration, which is typically specified by the end-user in the client application

Request-based configuration overrides the cartridge instance configuration, which overrides thecartridge-level defaults, which override the application-wide defaults in the MDEX Engine.

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

DescriptionClass name

The configuration model for the cartridge. For the core cartridges,the properties of this class represent all the configuration parameters

<CartridgeName>Config

that the cartridge handler needs to do its processing. It does notinclude configuration that can only be specified in the MDEX Engineor pass-through properties that are used by the reference applicationrenderers without any modification by the cartridge handler.

The handler that processes a cartridge. The core cartridge handlersare responsible for layering the default configuration, instance

<CartridgeName>Handler

configuration, and request-based configuration during processing.For more information about how to customize the handling of

DescriptionClass name

cartridge configuration (such as introducing additional sources ofconfiguration), refer to the Experience Manager CartridgeDeveloper's Guide.

The response model produced by the cartridge handler. Cartridgeresponse models may include objects that are reused among

<CartridgeName>

cartridges. For example, the ResultsList and RecordSpot¬light both contain Record objects.

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

Feature configuration in the MDEX EngineThere are two subcategories of MDEX Engine–level feature configuration: dynamic configuration thatcan be updated in a running MDEX Engine without re-indexing, and static configuration that must bespecified at index time.

Dynamic configuration includes search interfaces, thesaurus, and automatic phrasing. Staticconfiguration includes features such as such as stop words or precedence rules. Updating staticconfiguration requires that you re-run the data ingest process before the changes can take effect. Fordetailed information on feature configuration in the MDEX Engine, refer to the MDEX Engine BasicDevelopment Guide and the MDEX Engine Advanced Development Guide.

In addition, some features depend on certain Dgraph and Dgidx flags to enable or configure theirfunctionality. For information about Dgraph and Dgidix flags, refer to the Oracle Endeca CommerceAdministrator's Guide.

Default cartridge configurationYou can specify default configuration settings for a cartridge as part of the cartridge handler configurationin the Spring context file for the Assembler.

Cartridge handlers are responsible for managing the various sources of configuration that apply to aspecific cartridge. The cartridge handler configuration (including default configuration values) is specifiedas part of the Spring context file for the Assembler. In the Discover Electronics application, this isdefined in WEB-INF/assembler-context.xml.

You specify the cartridge handler for a specific cartridge by defining a bean whose ID follows the formatCartridgeHandler_<CartridgeType>, where the <CartridgeType> is the id of thecorresponding template. For example, the cartridge handler for the Breadcrumbs cartridge is definedin the CartridgeHandler_Breadcrumbs bean. You can map more than one cartridge to the samecartridge handler.

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


Configuring Front-End Application Features | About configuring application features80

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

The following shows an example of default configuration for a Record Spotlight cartridge. The defaultsproperty of the ConfigInitializer bean is an instance of RecordSpotlightConfig that hasbeen 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.RecordSpotlight¬Config" 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>

Note: Any property of the configuration model can be specified in the Spring context file. However,it is not required to specify a value for every property, only those for which you want to specifya default.

Cartridge instance configurationThe content administrator can configure each instance of a cartridge using Experience Manager inEndeca Workbench. The cartridge instance configuration is passed in as the argument to the initial¬ize() 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 providedas part of the Discover Electronics application are intended to cover the majority of use cases.

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

You can customize the templates for the core cartridges by adding properties to a template in additionto those required by the configuration model. These additional properties can either be processed bya custom cartridge handler implementation or passed through directly to the response model. Some


81Configuring Front-End Application Features | About configuring application features

of the templates in the Discover Electronics application define pass-through properties; these aredescribed in the sections on the specific cartridges.

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

Note: If you have purchased Oracle Endeca Guided Search only and do not have Oracle EndecaExperience 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. Customcartridges that use primitive properties only (typically as pass-through properties) can also beconfigured in Rule Manager. The remaining cartridges can be configured with application-widedefault values in the Spring context file for the Assembler.

Related LinksTemplate Property and Editor Reference on page 147

This section describes how to define basic content properties and associated editing interfacesin Experience Manager templates.

Request-based configurationFor 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 contentItemInitializerbean of the cartridge handler can specify a requestParamMarshaller bean whose class is Re¬questParamMarshaller or a subclass. RequestParamMarshaller is a helper class that parsesrequest parameters into properties of the cartridge configuration model.

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

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

Search boxThe Search Box cartridge enables the site visitor to enter search terms and view record results. Ifdimension search is enabled, dimension search results may also be displayed. A content administratorcan configure Search Box behavior such as whether to apply search adjustments or display auto-suggestsearch 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; propertiesspecified in the cartridge template and in the end user's search request are passed through to therenderer.


Configuring Front-End Application Features | Search features82

The renderer for this cartridge makes use of a JavaScript module, endeca-auto-suggest.js, todisplay the auto-suggest panel for search suggestions.

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

Dynamic configuration

The main aspects of search-related configuration that can be updated without re-indexing are thesearch interfaces for an application. Search interfaces specify a collection of properties and dimensionsagainst which text searches are performed, and may also specify a default relevance ranking strategy.For information about creating search interfaces, refer to theMDEXEngine Basic Development Guide.

The properties and dimensions within a search interface must be enabled for record search as partof the data ingest process. For information about enabling properties and dimensions for search, referto the Developer Studio Help.

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

Static configuration

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

• stop words are commonly occurring words (like "the") that are ignored for keyword search.• stemming broadens search results to include root words and variants of root words.• search characters configuration enables you to designate certain non-alphanumeric characters as

significant for search.

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

Template configuration for the Search Box cartridgeThe 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 includes properties that impact auto-suggest behavior. Theauto-suggest panel itself is implemented as a configurable dynamic slot, and is configured separately.

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

DescriptionProperty name

This property specifies the content collection that should be usedto populate the dynamic slot for the auto-suggest panel.

contentCollection

This property specifies how many characters a user must type beforethe auto-suggest panel displays.

minAutoSuggestInput¬Length

This property sets the number of content items to return whenpopulating the auto-suggest panel dynamic slot. It is limited by the

ruleLimit

evaluation limit of the specified contentCollection. The actualnumber of auto-suggest content items displayed is also limited bythe rendering code, which only supports rendering a singleauto-suggest panel by default.


83Configuring Front-End Application Features | Search features

Note: If you do not want to provide the option of enabling auto-suggest search results inExperience Manager, remove the properties and editors from the template, and remove theJavaScript module from the component.

Related LinksAuto-suggest search results on page 84

Auto-suggest search results display as the site visitor types in the search box, rather thandisplaying after the visitor has completed the search. In the Discover Electronics referenceapplication, the auto-suggest panel is implemented as a content item that populates a dynamicslot in the Search Box cartridge.

Auto-suggest search resultsAuto-suggest search results display as the site visitor types in the search box, rather than displayingafter the visitor has completed the search. In the Discover Electronics reference application, theauto-suggest panel is implemented as a content item that populates a dynamic slot in the Search Boxcartridge.

In addition to configuring the auto-suggest feature on the Search Box cartridge, a content administratormust also configure the display of different types of search suggestions. This section describes thecartridges that can be configured within the auto-suggest panel.

Currently, the only auto-suggest cartridge in the Discover Electronics reference application is one thatdisplays dimension search results. It returns the same response model as the Dimension Searchcartridge. Other possible uses for auto-suggest cartridges include those for Popular Searches, FeaturedCategories, and Product Search.

MDEX Engine configuration that impacts search results also applies to auto-suggest results. Forexample, enabling or disabling wildcard search on dimension search will affect the dimensions returnedfor a dimension search auto-suggest panel.

The JavaScript component of the Search Box in the Discover Electronics application acts as therenderer for the auto-suggest panel.

Template configuration for the auto-suggest panelThe cartridge template for the auto-suggest panel itself includes a dynamic content slot, with no otherconfiguration.

Configuration model for the Auto-Suggest Dimension Search Results cartridgeThe Auto-Suggest Dimension Search Results cartridge uses the same configuration model as theDimension Search Results cartridge.

The configuration model for this cartridge is DimensionSearchResultsConfig. For an overviewof this model, see "Configuration model for the Dimension Search Results cartridge" or refer to theAssembler API documentation (Javadoc).

Related LinksConfiguration model for the Dimension Search Results cartridge on page 86

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



Cartridge handler configuration for the Auto-Suggest Search Results cartridgeBecause the Auto-Suggest Dimension Search Results cartridge uses the same configuration modelas the Dimension Search Results cartridge, it also shares the same cartridge handler.

The cartridge handler configuration maps the Dimension Search Auto-Suggest cartridge to the Dimen¬sionSearchResultsHandler. There are no application-wide default values set for this cartridge.

Related LinksSearch box on page 82

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

Template configuration for the Auto-Suggest Dimension Search Results cartridgeThe Auto-Suggest Dimension Search Results cartridge populates the dynamic slot in the Auto-Suggestpanel. The cartridge template is similar to the Dimension Search Results template.

The Auto-Suggest Dimension Search Results cartridge template allows a content administrator toconfigure the following properties on the configuration model:

• maxResults

• dimensionList

• maxResultsPerDimension

• showCountsEnabled

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


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

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

displayImage

Note: If there is no such property on dimension values in thedata set, remove this option and its associated editor from thetemplate to disable this feature.

Dimension search resultsThe Dimension Search Results cartridge displays refinement links based on the names of dimensionvalues 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 resultsprovide suggestions for additional navigation refinements based on the search terms.

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



Configuration model for the Dimension Search Results cartridgeThe Dimension Search Results cartridge configuration model controls the number, ranking, and displayof returned results.

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


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

enabled

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

maxResults

Specifies the maximum number of dimension values to display perdimension.

maxResultsPerDimension

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

dimensionList

Specifies whether to display refinement counts in dimension searchresults.

showCountsEnabled

Optional. Specifies a relevance ranking string to use for dimensionsearch, such as "first,static(nbins,desc)". If you do not set this

relRank

property, dimension value relevance ranking is set to the default(alpha, numeric, or manual) defined in Developer Studio.

MDEX Engine configuration for dimension search resultsDifferent 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 inDeveloper Studio. Oracle recommends enabling wildcard search for dimensions, especially if you areusing the Auto-Suggest Dimension Search cartridge or the Dimension Value Boost-Bury editor. Wildcardsearch 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 theuser is typing search terms.

Additional options include whether to return only the highest ancestor dimension value, and whetherto return inert dimension values in dimension search results. For more information about globaldimension configuration, refer to the Developer Studio Help.


You can configure dimension-specific search behavior in the Dimension editor in Developer Studio.This includes whether to search across the entire dimension hierarchy rather than only individualdimension 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 Developer Studio Help.



Cartridge handler configuration for Dimension Search ResultsThe Dimension Search Results cartridge handler extends the NavigationCartridgeHandler.

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

Template configuration for the Dimension Search Results cartridgeThe Dimension Search Results cartridge template allows a content administrator to configure howmany results should be displayed to the end user, and how they should display. The cartridge templatealso 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 thefollowing properties on the configuration model:

• maxResults

• dimensionList

• maxResultsPerDimension

• showCountsEnabled

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


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

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

displayImage

Note: If there is no such property on dimension values in thedata set, remove this option and its associated editor from thetemplate to disable this feature.

URL request parameters for the Dimension Search Results cartridgeThe display of the Dimension Search Results cartridge on a page is controlled by setting the value ofthe 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. Whilethis is equivalent to setting the property to true in the cartridge handler configuration, or as anon-editable property in the cartridge template, the intent is to demonstrate where the logic belongsin the application.

DescriptionURLParameter

Property name

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

Dyenabled



Search adjustmentsSearch adjustments include automatic spelling correction, automatic phrasing, and Did You Meanfunctionality.

The response model for this cartridge is SearchAdjustments.

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

Configuration model for the Search Adjustments cartridgeThe Search Adjustments cartridge configuration model enables you to enable or disable automaticphrasing 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 followingproperties:


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

phraseSuggestio¬nEnabled

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

spellSuggestionEn¬abled

If query debugging features are enabled, this property enables debugginginformation about word or phrase subsitutions as a map that can be accessed

showWordInterp

via SearchAdjustments.getInterpretedTerms(). For additionalinformation, see "About query debugging results in the reference application."

Related LinksAbout query debugging results in the reference application on page 138

In Discover Electronics, query debugging results can be returned as part of the responsemodel for the Results List, Search Adjustments, and Refinement Menu cartridges asappropriate. In the Discover Electronics reference application, these results can be enabledby un-commenting the corresponding properties in each cartridge handler.

MDEX Engine configuration for the Search Adjustments cartridgeSearch 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 Developer Studio.For more information about configuring automatic phrasing, refer to the MDEX Engine AdvancedDevelopment Guide.


You can configure the constraints on the spelling dictionaries for record search and dimension searchin the Spelling editor in Developer Studio. These settings determine the size of the spelling dictionarythat is generated at indexing time. Larger spelling dictionaries lead to slower performance of spellingcorrection 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 spellingdictionary, refer to the MDEX Engine Performance Tuning Guide.

Dgidx flags

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

The Deployment Template application configuration for the Discover Electronics reference applicationhas spelling correction and Did You Mean enabled as in the following example:<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>

Dgraph flags

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

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

The Deployment Template application configuration for the Discover Electronics reference applicationhas spelling correction and Did You Mean enabled as in the following example:<dgraph-defaults> <properties>

</properties> <directories>

 </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>

Cartridge handler configuration for Search AdjustmentsThe Search Adjustments cartridge handler extends the NavigationCartridgeHandler. Theapplication-wide default configuration in the Assembler context file allows you to enable or disable theword interpretation debugging feature.

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

Related LinksAbout implementing automatic phrasing on page 91

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

Template configuration for the Search Adjustments cartridgeThe cartridge template for the Search Adjustments cartridge does not include any configurableproperties. A content administrator can add the cartridge to a page in order to enable the display ofSearch Adjustments, but cannot otherwise configure cartridge behavior.

URL request parameters for the Search Adjustments cartridgeAutomatic phrasing and spelling correction are controlled by setting the value of their respectiveproperties 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. Whilethis is equivalent to setting the properties in the cartridge handler configuration, or in the cartridgetemplate, the intent is to demonstrate where the logic belongs in the application.


Property name

Specifies whether to enable automatic phrasing.NtpphraseSugges¬tionEnabled

Property name

Specifies whether to enable automatic spelling correction.NtyspellSuggestio¬nEnabled

About implementing automatic phrasingYou can configure the MDEX Engine to consider certain combinations of words in a text search as aphrase 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:• Enabling the MDEX Engine to compute phrases• Configuring the default behavior of the Assembler application as to whether or not to automatically

apply computed phrases• Adding application logic to enable Did You Mean suggestions or override the default automatic

phrasing behavior in certain situations

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

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

DescriptionProperty

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

autoPhraseEnabled

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

The Filter State configuration in the Assembler context file for the Discover Electronics referenceapplication is shown below:<bean id="navigationStateBuilder" scope="request" class="com.endeca.infront.navigation.url.UrlNavigationStateBuilder">

<property name="defaultFilterState">

<bean scope="singleton" class="com.endeca.infront.navigation.mod¬el.FilterState"> <property name="rollupKey" value="product.code" />

<property name="autoPhraseEnabled" value="true" />   </bean> </property>

</bean>

Interaction with the Did You Mean feature

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

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

Phrase search scenario: Automatically applying phrasesIn the Discover Electronics application, the default behavior is to automatically apply phrases to textsearch 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 SearchBox cartridge sets Nty=1 on the text search query. The user has two choices:

• Select the Did You Mean suggestion to search for the keywords separately, rather than as a phrase.This link sends the same query with the URL parameter Ntp=0 to override the Filter Stateconfiguration, and also sets Nty=0 since we do not need to suggest the phrased version of thequery after the user has decided to use the unphrased version.

• Make another selection on the page, such as clicking on a refinement or advancing to the nextpage of results. This signifies acceptance of the automatically applied phrase, so we keep au¬toPhraseEnabled=true from the Default Filter State and suppress further suggestions by settingNty=0.

These outcomes are summarized in the following table:

ResultDid You Meansetting (Nty)

Autophrasesetting (Ntp)

User action

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

Nty=1trueInitial search

Phrase is not applied to the search. Nosuggestion is offered.

Nty=0Ntp=0Select Did You Meansuggestion

Phrase continues to be automaticallyapplied. Suggestions are no longeroffered.

Nty=0trueMake anotherfollow-on selection

Phrase search scenario: Phrases as a search suggestionYou can configure the application not to apply phrases by default, but to return phrases as a searchsuggestion.



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

• Select the Did You Mean suggestion to consider the text search as a phrase. This link sends thesame query with the URL parameter Ntp=1 to override the default Filter State configuration, andalso sets Nty=0 since we do not need to suggest the unphrased version of the query after theuser has decided to use the phrased version.

• Make another selection on the page, such as clicking on a refinement or advancing to the nextpage of results. This signifies acceptance of the unphrased query, so we keep autoPhraseEn¬abled set to false and suppress further suggestions by setting Nty=0.

These outcomes are summarized in the following table:

ResultDid You Meansetting (Nty)

Autophrase setting(Ntp)

User action

Phrase is not applied to the textsearch. A Did You Mean

Nty=1falseInitial search

suggestion is offered for thephrased version.

Phrase is automatically appliedto the search. No suggestion isoffered.

Nty=0Ntp=1Select Did You Meansuggestion

Text search continues to betreated as individual keywords

Nty=0falseMake anotherfollow-on selection

instead of as a phrase.Suggestions are no longeroffered.

Keyword redirectsContent administrators can configure keyword redirects that redirect a front-end user to a new pageif 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 theredirect URI with the response model. The Assembler response can be limited to the redirect URI, orit 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 KeywordRedirects page in Workbench.

Cartridge handler configuration for keyword redirectsThe Endeca Assembler API includes a RedirectAwareContentIncludeHandler that implementskeyword redirect functionality.

The cartridge handler takes the following two properties:



• defaultFullAssembleOnRedirect— A Boolean that specifies whether to return search resultsin addition to the redirect URI when making an assemble() call. Defaults to false. If you do notnecessarily wish to execute a redirect (for cases where the redirect URI is displayed as a link, ormay be skipped entirely if the user is not on a specific device), you must set this property to true.

• defaultRedirectCollection — A string that contains the name of the keyword redirectcollection in the Endeca Configuration Repository. Setting a null or empty value for this propertydisables keyword redirect functionality.

The cartridge handler configuration in the Assembler context file for Discover Electronics is shownbelow:<bean id="CartridgeHandler_ContentInclude" class="com.endeca.infront.cartridge.ContentIncludeHandler" scope="prototype"> <property name="contentSource" ref="contentSource" /></bean>

<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"/></bean>

Content XML for keyword redirectsYou can override the default settings for the fullAssembleOnRedirect or redirectCollectionproperties by setting new values in the content XML that is retrieved by the RedirectAwareCon¬tentIncludeHandler.

The primary use case for setting these properties on content XML is for deployments running theAssembler service. Keyword redirects are programatically enabled in the service, so by default thefeature 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 redirectsby using the ContentInclude class instead of RedirectAwareContentInclude for thoseservices where you wish to disable the feature.

About using keyword redirects with the Assembler serviceThe Assembler service in the Discover Electronics application implements the com.endeca.in¬front.assembler.servlet.AbstractAssemblerServlet abstract class. Keyword redirectconfiguration is configured in the application's web.xml file.

The JSON and XML servlets in the Discover Electronics reference application are configured inreference\discover-service\WEB-INF\web.xml:<servlet> <servlet-name>JsonAssemblerServiceServlet</servlet-name> <servlet-class>com.endeca.infront.assembler.servlet.spring.SpringAssem¬blerServlet</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.

About handling keyword redirects in an applicationIn order to execute a redirect, an application must include logic for handling the URI componentsreturned from the Assembler. You must use the RedirectAwareContentInclude class for anycontent items that require keyword redirect functionality.

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

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

...

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

//Retrieve the content for the given content uriContentItem contentItem = new RedirectAwareContentInclude("/pages" + conten¬tUri);


The Assembler response

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 adestination URI.



The following example shows a JSON response from the Guided Search service when fullAssem¬bleOnRedirect is false:{ endeca:siteRootPath: "/services", endeca:contentPath: "/guidedsearch", endeca:assemblerRequestInformation: { @type: "AssemblerRequestEvent", endeca:assemblyStartTimestamp: 1341943119538, endeca:assemblyFinishTimestamp: 1341943119546, endeca:contentPath: "/guidedsearch", 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.

Using the Assembler response

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

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

...


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:redi¬rect")).get("link")); %> <c:redirect url="${util:getUrlForAction(action)}"/> <%}...

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

Related LinksAbout Actions on page 65



An Action object allows you to construct a link that represents a decision by an end user.The included fields and values depend on the action that the user wishes to take; they caninclude the action label, the root site path, and the path to the destination content within thesite.

Guided Navigation featuresThe following sections provide an overview of the configuration models for Guided Navigation featuresincluded with Tools and Frameworks and implemented in Discover Electronics.

Refinement menuThe Refinement Menu cartridge displays dimension values within a single dimension for GuidedNavigation. It supports dimension value boost and bury.

The response model for this cartridge is RefinementMenu, which contains a list of Refinementobjects.

Dimension value boost and bury

Dimension value boost and bury is a feature that enables re-ordering of dimension values within aparticular dimension for Guided Navigation. With dimension value boost, you can assign specificdimension values to ranked strata, with those in the highest stratum being shown first, those in thesecond-ranked stratum shown next, and so on. With dimension value bury, you can assign specificdimension values to strata that are ranked much lower relative to others. This boost/bury mechanismtherefore lets you manipulate ranking of returned dimension values in order to promote or push certainrefinements to the top or bottom of the navigation menu.

The Refinement Menu cartridge enables the content administrator to specify an ordered list of dimensionvalues to boost and an ordered list of dimension values to bury. Each dimension value is translatedinto its own stratum in the query that returns refinements so as to preserve the exact order of refinementsspecified by the content administrator.

For more information about dimension value boost and bury, refer to the MDEX Engine BasicDevelopment Guide.

Configuration model for the Refinement Menu cartridgeThe Refinement Menu cartridge configuration model allows you to configure sorting, "Show More..."link behavior, and boosted and buried refinements. Additionally, it includes a whyPrecedenceRule¬Fired property that can be used for debugging precedence rule behavior in your application.

The configuration model for this cartridge is RefinementMenuConfig. It includes the followingproperties:


A string representing the id of the dimension being configured.dimensionId

An ordered list of dimension value refinements to display at the top of the list.boostRefine¬ments

An ordered list of dimension value refinements to display at the bottom of the list.buryRefine¬ments


97Configuring Front-End Application Features | Guided Navigation features


The base sort order of dimension values within this dimension. This property shouldhave one of the following values:

sort

• default — Sort dimension values according to the application configurationfor this dimension.

• static — Sort dimension values in alphabetic or numeric order, dependingon the dimension configuration.

• dynRank — Sort dimension values so that the refinements with the highestnumber of records display first.

A Boolean indicating whether to enable a link to show more refinements than aredisplayed by default.

showMoreLink

A string representing the text to use for the "show more refinements" link.moreLinkText

A string representing the text to use for the "show fewer refinements" link.lessLinkText

A string representing the number of refinements to display by default, or when auser clicks the "show fewer refinements" link.

numRefine¬ments

A string representing the maximum number of refinements to display when a userclicks the "show more refinements" link.

maxNumRefine¬ments

A string that sets the amount of refinements to return, from the following values:refine¬mentsShown • none — returns no refinements.

• some — returns numRefinements refinements.• all — returns maxNumRefinements refinements.

(Deprecated) A Boolean indicating whether to display the maxNumRefinementsnumber of menu items. When this value is false, the number of menu items

showMore

generated is limited by numRefinements, and a "show more refinements" linkis generated. This value should be set using showMoreIdsURL parameter whenthe "show more refinements" link is selected.

(Deprecated) A Boolean that sets whether to use the showMoreIds URLparameter when determining how many refinements to display. If false, the

useShowMoreI¬dsParam

showMore property on the RefinementMenuConfig object is used instead. Ifthis property is set to true, refinements cannot be collapsed. Defaults to true.

If query debugging features are enabled, this property enables debugginginformation about why precedence rules fired on a query in a

whyPrece¬denceRule¬Fired DGraph.WhyPrecedenceRuleFired property for each root dimension value.

For additional information, see "About query debugging results in the referenceapplication."

Important: The useShowMoreIdsParam property and associated showMoreIds URLparameter are included in this release for backwards compatibility. Use the refinementsShownproperty if you are refactoring your code or developing a new application.

Notes on sorting

The static sort option is described as "Alphanumeric" sorting in the Experience Manager userinterface for the default Refinement Menu cartridge. Dimension values are ordered alphanumerically


Configuring Front-End Application Features | Guided Navigation features98

within a dimension by default, however it is possible to manually specify a dimension order (for example,using the Dimension Values editor in Developer Studio). This custom dimension value order is usedwhen static sorting is specified. To ensure alphanumeric sorting of dimension values, do not specifya custom dimension value order.

Dynamic refinement ranking is incompatible with displaying disabled refinements for a dimension. Inthe default Refinement Menu cartridge, the option to show disabled refinements is not available unlessthe content administrator has explicitly selected static sorting.

Related LinksAbout query debugging results in the reference application on page 138

In Discover Electronics, query debugging results can be returned as part of the responsemodel for the Results List, Search Adjustments, and Refinement Menu cartridges asappropriate. In the Discover Electronics reference application, these results can be enabledby un-commenting the corresponding properties in each cartridge handler.

MDEX Engine configuration for Guided NavigationNo special configuration is necessary to enable Guided Navigation, however, there is some staticconfiguration that affects the display of refinements.


In the Dimension editor in Developer Studio, you can configure dimensions to be:• multiselect — A multiselect dimension enables a user to select more than one refinement at the

same time. You can specify whether the navigation results when multiple refinements are selectedare treated as a Boolean AND or Boolean OR on a per-dimension basis.

• hidden — A hidden dimension does not display in Guided Navigation; however, users can stillsearch for records based on their dimension values in a hidden dimension.

You can also configure the following refinement behavior on a per-dimension basis:• dynamic refinement ranking — Dynamic ranking returns refinements based on their popularity

(number of associated record results for each refinement). This is a default setting that can beoverridden by the content administrator in Experience Manager.

• refinement statistics — Enabling refinement statistics returns the number records (or aggregatedrecords) are associated with each refinement so that this information can be displayed in theapplication.

Additionally, you can designate specific dimension values as inert. For more information about theseconfiguration options, refer to the MDEX Engine Basic Development Guide.

Cartridge handler configuration for the Refinement Menu cartridgeThe Refinement Menu cartridge handler extends the NavigationCartridgeHandler. Theapplication-wide default configuration in the Assembler context file determines the behavior of collapseddimensions and "show more" and "show less" links, and can be set to enable or disable the precedencerule debugging feature if query debugging features are enabled.

The cartridge handler uses a contentItemInitializer to merge the layered configuration. Theincluded requestParamMarshaller bean enables URL request-based configuration for the cartridge,which is required for disabling or enabling the full list of refinement results returned when the end userclicks the "show more refinements" link.



Template configuration for the Refinement Menu cartridgeThe Refinement Menu cartridge template allows a content administrator to configure which dimensionto query for the cartridge and how many results should display. It also allows control over boosted andburied dimension refinements, in order to modify the order in which dimensions display to the enduser.

The Refinement Menu cartridge template allows a content administrator to configure the followingproperties on the configuration model:

• dimensionId

• sort

• showMoreLink

• moreLinkText

• lessLinkText

• numRefinements

• maxNumRefinements

• boostRefinements

• buryRefinements

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


The name of the string property that represents the dimension name.This is required by the Dimension Selector editor to enable a contentadministrator to select a dimension by name, rather than by ID.

dimensionName

URL request parameters for the Refinement Menu cartridgeYou can configure the Refinement Menu cartridge at runtime by setting the value of the DYNAMIC_RE¬FINEMENT_MENU_CONFIG property on the RefinementMenuRequestParamMarshaller via theNrmc URL parameter.

The sample cartridge renderer includes logic for displaying the maxNumRefinements number ofresults when a user clicks on the "show more refinements" link.

DescriptionURL parameterProperty name

The Nrmc parameter takes multiple arguments allow you toconfigure dimension refinement behavior in the cartridge.

NrmcDYNAMIC_RE¬FINE¬MENT_MENU_CON¬FIG

(Deprecated) A Boolean indicating whether to display themaxNumRefinements number of menu items. Use the re¬

ShowMoreIdsshowMore

finementsShown property if you are refactoring your codeor developing a new application.

About Nrmc URL parameter syntax

The Nrmc parameter takes the following values:• Dimension ID — Required. The ID of the dimension you wish to configure.• +show:<value>— Required; <value> is the value to pass to the refinementsShown property

on the configuration object.



The configuration for each dimension is separated by a vertical pipe, as in the example below:20001+show:all|20002+show:some

Note: You can also use the notation used with the Presentation API, for example:Nrc=id+10074+expand+true+more+true. For more information about this notation, seethe MDEX Engine Basic Developer's Guide.

Navigation ContainerThe Navigation Container is provided as an alternative the refinement menu cartridge forimplementations using Oracle Endeca Guided Search with the packaged services. It enables you toretrieve the full list of available dimension refinements for a dimension query.

The response model for the Navigation Container includes a list of RefinementMenu objects thateach include the records within a dimension refinement. The NavigationContainerHandlerhandles the "show more refinements" link and associated link Action for each of these refinements,and also controls whether to display debugging information.

Related LinksAbout Actions on page 65

An Action object allows you to construct a link that represents a decision by an end user.The included fields and values depend on the action that the user wishes to take; they caninclude the action label, the root site path, and the path to the destination content within thesite.

Configuration model for the Navigation ContainerThe Navigation Container configuration model includes the List<String> property of dimensionIDs that are returned with the response model. Since it is a dimension navigation feature, it includesa whyPrecedenceRuleFired property that can be used for debugging precedence rule behavior inyour application.

The configuration model for this cartridge is NavigationContainerConfig. It includes the followingproperties:


A List of dimension IDs to return as expanded lists of available refinements.Any dimension refinements not included in this List are returned in the default,shorter form output by the MDEX Engine.

showMoreIds

A string representing the text to use for the "show more refinements" link.The same string is used for each of the included dimension refinements.

moreLinkText

A string representing the text to use for the "show fewer refinements" link.The same string is used for each of the included dimension refinements.

lessLinkText

A Boolean indicating whether the refinement menus should be fully expanded.Defaults to true. When using a dataset that includes dimensions with alarge number of refinements, you should set this to false.

refinementsShownBy¬Default

A string that sets the amount of refinements to return on each refinementmenu, from the following values:

refinementsShown

• none — returns no refinements.




• some — returns numRefinements refinements.

(Deprecated) A Boolean that sets whether to use the showMoreIds URLparameter when determining how many refinements to display. If false,

useShowMoreI¬dsParam

the showMore property on the RefinementMenuConfig object is usedinstead. If this property is set to true, refinements cannot be collapsed.Defaults to true.

If query debugging features are enabled, this property enables debugginginformation about why precedence rules fired on a query in a

whyPrecedenceRule¬Fired

DGraph.WhyPrecedenceRuleFired property for each root dimensionvalue. For additional information, see "About query debugging results in thereference application."

Cartridge handler configuration for the Navigation ContainerThe Navigation Container handler extends the NavigationCartridgeHandler. The application-widedefault configuration in the Assembler context file determines the behavior of collapsed dimensionsand "show more" and "show less" links, and can be set to enable or disable the precedence ruledebugging feature if query debugging features are enabled.

The cartridge handler uses a contentItemInitializer to merge the layered configuration. Theincluded requestParamMarshaller bean enables URL request-based configuration for the cartridge,which is required for modifying the properties on the response model through URL parameters.

URL request parameters for the Navigation ContainerBecause the Navigation Container returns a list of RefinementMenu objects, it takes the same NrmcURL parameter as the Refinement Menu cartridge.

DescriptionURL parameterProperty name

The Nrmc parameter takes multiple arguments allowyou to configure dimension refinement behavior in thecartridge.

NrmcDYNAMIC_REFINE¬MENT_MENU_CONFIG

If query debugging is enabled for the referenceapplication, this property allows you to include

whyPrece¬denceRuleFired

whyPrecedenceRule¬Fired

debugging information about why precedence rulesfired on a query in a DGraph.WhyPrecedenceRule¬Fired property for each dimension value.

For details on configuring the Nrmc parameter, see "URL request parameters for the Refinement Menucartridge."

BreadcrumbsThe Breadcrumbs cartridge displays the parameters defining the search or navigation state for thecurrent set of search results.

The response model for this cartridge is Breadcrumbs, which may contain SearchBreadcrumb,RefinementBreadcrumb,RangeFilterBreadcrumb, and GeoFilterBreadcrumb objects as



appropriate. Each breadcrumb contains information about search or navigation selections that the enduser has made, and provides links to remove that selection from the filter state.

The Breadcrumbs cartridge does not have any associated Experience Manager configuration optionsor MDEX Engine configuration.

Cartridge handler configuration for BreadcrumbsThe Breadcrumbs cartridge handler extends the NavigationCartridgeHandler, but otherwisedoes not require any additional configuration.

Results featuresThe following sections provide an overview of the configuration models for features that display searchresults in the reference implementation.

Results listThe 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 andSortOptionLabel objects that enable the end user to select from a set of pre-defined sort orders.

About the order of records in the record list

The order of records returned by the MDEX Engine is determined by a sort key or relevance rankingstrategy 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 allother queries including navigation queries. The sort options that are available to the end user in theapplication represent static sort orders that are not based on relevance to any search terms.

Record boost and bury

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

The core Results List cartridge enables the content administrator to specify one set of records to boostand one set of records to bury. Boost and bury are applied to the result list before any additional sortingor relevance ranking modules. For more information about record boost and bury, refer to the BasicDevelopment Guide.


103Configuring Front-End Application Features | Results features

Configuration model for the Results List cartridgeThe Results List configuration model allows you to configure the number and sorting of records returnedby a search or navigation query. Additionally, it includes whyMatchEnabled and whyRankEnabledproperties 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:


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

recordsPerPage

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

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:

sortOption

• label — A descriptive label that displays to the site visitor in the clientapplication

• value — A sort order specified in the format <key>|<direction>, wherekey is the name of the property or dimension on which to sort, and thedirection is 0 for ascending and 1 for descending. An empty string representsthe default sort order specified by the content administrator in ExperienceManager.

You can set this value via the Ns URL parameter.

A String that specifies the selected Sort.sortRequestPa¬rameter

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()methodreturn an empty list.

includePrecom¬putedSorts

(Optional) The Relevance Ranking Strategy. If you specify a Relevance RankingStrategy without setting relRankTerms, relRankKey, or relRankMatchMode,

relRankStrate¬gy

your Relevance Ranking strategy will apply to the results from the current searchfilter. This setting is ignored if an end user explicitly selects a sort.

(Optional) The Relevance Ranking key to use with the selected Relevance Rankingstrategy. This can be a search interface, dimension, or property set in the MDEX

relRankKey

Engine. You must set a relRankStrategy and relRankTerms if you specifya value for this property.

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

relRankTerms

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

relRankMatch¬Mode

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

boostStrata

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

buryStrata


Configuring Front-End Application Features | Results features104


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

subRecordsPer¬AggregateRe¬cord • ZERO — Sub-records are not returned.

• ONE — A single representative record is returned.• ALL — All sub-records are returned.

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

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

offset

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

fieldNames

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

subRecordField¬Names

If query debugging features are enabled, this property enables debugginginformation about why each record matched the search and navigation state. For

whyMatchEn¬abled

additional information, see "About query debugging results in the referenceapplication."

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

whyRankEnabled

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

MDEX Engine configuration for the Results List cartridgeYour MDEX Engine configuration for your application allows you to configure which properties anddimensions 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 anddimensions are returned for the record with the record list. This configuration can be overridden in thecartridge handler configuration. For more information about configuring the display of properties anddimensions 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 aproperty or dimension for sorting in Developer Studio. This controls the generation of a precomputedsort, which you can retrieve on the ResultsListConfig object by using the getPrecomputed¬Sorts() method. For more information about precomputed sorts, refer to the MDEX Engine BasicDevelopment Guide.



Dgidx flags

You can specify the default sort order for records as a flag in Dgidx. For more information about Dgidxflags and sorting, refer to the MDEX Engine Basic Development Guide.

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

Cartridge handler configuration for the Results List cartridgeThe Results List cartridge handler extends the NavigationCartridgeHandler. The application-widedefault configuration in the Assembler context file specifies default sort options, relevance rankingstrategy, and record and sub-record properties to pass through to the cartridge handler responsemodel. It also allows you to enable or disable debugging features if query debugging features areenabled.

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

Template configuration for the Results List cartridgeThe Results List template allows a content administrator to configure the main results of a search ornavigation 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 propertieson the configuration model:

• recordsPerPage

• sortOption

• relRank

• boostStrata

• buryStrata

URL request parameters for the Results List cartridgeEnd user configuration is passed to the configuration model as URL parameters. This allows applicationend users to specify how records should be displayed and sorted in order to customize their navigationexperience.

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


Property

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

NrpprecordsPerPage

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

NssortOption

This parameter enables you to control record display when paging.Nooffset


Configuring Front-End Application Features | Results features106


Property

(Optional) The Relevance Ranking key. You must set a rel¬RankStrategy on the cartridge to use this parameter. You mustalso specify relRankTerms.

NrkrelRankKey

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

NrtrelRankTerms

(Optional) The match mode that determines the subset of resultsto apply Relevance Ranking to. You must set a relRankStrate¬

NrmrelRankMatch¬Mode

gy, relRankKey, and relRankTerms if you specify a value forthis property.

If query debugging is enabled for the reference application, thisproperty enables you to include record matching information on aper-query basis, rather than at the cartridge handler level.

whymatchwhyMatchEn¬abled

If query debugging is enabled for the reference application, thisproperty enables you to include record ranking information on aper-query basis, rather than at the cartridge handler level.

whyrankwhyRankEnabled

Note: The Nrk, Nrt, and Nrm parameters take precedence over any relevance rankingdeclaration in the Ntk, Ntt, and Ntx parameters.

Enabling snippeting in record resultsThe Assembler can return snippets (an excerpt from a record property that contains the user's searchterms 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 moreproperties in a search interface, typically properties that contain multiple lines of text.

To enable snippeting:

1. Enable snippeting on one or more properties in the relevant search interface.For more information about configuring snippeting, refer to the Basic Developer's Guide.

2. In the Results List cartridge handler configuration, specify the relevant snippet property in the listof fieldNames.

For example, if you enabled the property product.short_desc for snippeting, you would specifythe property product.short_desc.Snippet, as in the following example: <bean id="CartridgeHandler_ResultsList" class="com.endeca.infront.car¬tridge.ResultsListHandler" parent="NavigationCartridgeHandler" scope="prototype"> <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.short_desc.Snippet</value> <value>product.price</value>



<value>product.min_price</value> <value>product.max_price</value> <value>product.img_url_thumbnail</value> </list> </property>

 </bean>

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

Record details featuresThe following section provides an overview of the configuration model for record detail features in thereference implementation.

Record details pageThe Record Details page displays detailed information about a specific record.

The response model for this cartridge is RecordDetails, which contains a single Record.

The rendering logic for a record details page is expected to be highly customized for each site, in orderto display the relevant record information and provide additional functionality such as bookmarking orinitiating a purchase transaction.

Configuration model for the Record Details cartridgeThe Record Details configuration model allows you to configure which properties on the record shouldbe passed through to the output model of the cartridge handler, so that the renderer can display them.

The configuration model for this cartridge is RecordDetailsConfig. It includes the followingproperties:


A list of record fields to pass through from the record to the Record outputmodel of the RecordDetailsHandler.

fieldNames

For aggregate records, a list of sub-record fields to pass through from eachsub-record to the Record output model of the RecordDetailsHandler.


MDEX Engine configuration for the Record Details pageNo special configuration is required the display of record details, but you can specify what informationyou want to display on the record page.


You can specify which properties and dimensions are returned with the record for a record detailspage in Developer Studio. For more information about configuring the display of properties anddimensions for record details, refer to the Developer Studio Help.


Configuring Front-End Application Features | Record details features108

Cartridge handler configuration for the Record Details cartridgeThe Record Details cartridge handler extends the NavigationCartridgeHandler, but otherwisedoes not require any additional configuration.

Template configuration for the Record Details cartridgeThe Record Details cartridge in the Discover Electronics application does not require any configurationin Experience Manager. The cartridge can be placed on a Record Details page to display detailedinformation about a record.

Content and spotlighting featuresThe following sections provide an overview of the configuration models for features that enable contentspotlighting in the reference implementation.

Record SpotlightThe Record Spotlight cartridge can promote either specific featured records or a set of dynamic recordsbased on a navigation state.

The response model for this cartridge is RecordSpotlight, which includes a list of Record objectsand an optional action to show all records (in the case of a dynamic record spotlight).

Configuration model for the Record Spotlight cartridgeThe Record Spotlight configuration model allows you to configure the selected records and "See All"link within a record spotlight, as well as the record fields to pass through to the cartridge responsemodel.

The configuration model for this cartridge is RecordSpotlightConfig. It includes the followingproperties:


A string representing the maximum number of records that this spotlight cancontain. If the content administrator designates specific records in the

maxNumRecords

Experience Manager, the number of records cannot exceed the value ofmaxNumRecords. If the content administrator specifies a query, theAssembler returns no more than this number of records.

A RecordSpotlightSelection object that represents the records selectedfor spotlighting. This includes the specified filter state, sort options, and resultlimit.

recordSelection

A Boolean that determines whether to display the "See All" link. The linkrequires a value for seeAllLinkText in order to display.

showSeeAllLink

A string representing the display text for a link that represents the navigationstate of a dynamic record spotlight. If this string is not configured, no link isgenerated for the client application.

seeAllLinkText

A list of record fields to pass through from the record to the Record outputmodel of the RecordSpotlightHandler.

fieldNames


109Configuring Front-End Application Features | Content and spotlighting features


For aggregate records, a list of sub-record fields to pass through from eachsub-record to the Record output model of the RecordSpotlightHandler.


MDEX Engine configuration for a spotlightYou can configure which properties and dimensions can be displayed in a spotlight.


Although the content administrator can designate the records for a spotlight either by specifying asearch and navigation query or by specifying individual record IDs, the Assembler query that fetchesthe spotlighted records is always a navigation query (using records in the specific record case).Therefore, the configuration that determines which properties and dimensions are returned with therecord for spotlighting is "show with record list." This configuration can be overridden in the cartridgehandler configuration. For more information about configuring the display of properties and dimensionsfor the record list, refer to the Developer Studio Help.

Related LinksMDEX Engine configuration for the Results List cartridge on page 105

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

Cartridge handler configuration for the Record Spotlight cartridgeThe Record Spotlight cartridge handler extends the NavigationCartridgeHandler. Theapplication-wide default configuration in the Assembler context file specifies record properties to passthrough to the cartridge handler response model.

Template configuration for a record spotlightA Record Spotlight cartridge enables a content administrator to specify a set of contextually relevantrecords to spotlight on a particular page.

The Record Spotlight cartridge template allows a content administrator to configure the followingproperties on the configuration model:

• maxNumRecords

• recordSelection

• showSeeAllLink

• seeAllLinkText

These properties are configured using the Spotlight Selection editor.



A title that the content administrator can specify to display for thiscartridge in the front-end application.

title


Configuring Front-End Application Features | Content and spotlighting features110

Media BannerThe Media Banner cartridge displays video or images to the site user and can be configured to link toa static page, a single record, or a specified navigation state.

The response model for this cartridge is MediaBanner, which includes a MediaObject and an Ac¬tionLabel that contains a destination link.

Configuration model for the Media Banner cartridgeThe configuration model for the Media Banner cartridge includes a media object and an associatedlink.

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


The MediaObject representing the image or video asset to display in theapplication.

media

The LinkBuilder object used to construct a link to a navigation state or astatic page within the application.

link

MDEX Engine configuration for a media bannerNo special configuration is required for the media banner, but your MDEX Engine configuration willaffect the display of records in the link selector when setting a navigation state or choosing a specifiedrecord.


You can specify how records are sorted and which properties and dimensions are returned with arecord in Developer Studio. For more information about configuring record sorting and display, referto the Developer Studio Help.

Cartridge handler configuration for the Media Banner cartridgeThe Media Banner cartridge handler extends the NavigationCartridgeHandler, but otherwisedoes not require any additional configuration.

Template configuration for the Media Banner cartridgeThe Media Banner enables the content administrator to use the media selector and link editor to createa media banner that links to a specified page, selected record, or dynamic navigation state.

The Media Banner cartridge template allows a content administrator to configure the following propertieson the configuration model:

• media

• link



(Optional) The alt-text to display when the end user hovers over the media assetin the application.

imageAlt


111Configuring Front-End Application Features | Content and spotlighting features

For detailed information on the properties within the media and link properties, consult the Javadocfor the MediaObject and LinkBuilder classes.

Dynamic triggering featuresThe following sections contain information about features related to triggering content items based onthe user's context.

The dynamic slot feature is typically used to trigger a cartridge independently from the page thatcontains it, although the Discover Electronics application uses the same mechanism to trigger entirepages by programmatically creating a content slot configuration and passing it to the Assembler.

About dynamic slotsA dynamic slot is a generic mechanism that enables content administrators to manage the content forspecific sections of an Experience Manager-driven page independently from the overall page.

There two main scenarios for using dynamic slots:• To share content across different pages. In this case, the triggers on the content items that

populate the slot are more general or orthogonal to the trigger criteria for the page. For example,a header cartridge may be shared across an entire site if it is referenced from every page and hasan "Applies at all locations" trigger. A promotion may be configured with a user segment triggerand display when a site visitor who belongs to the specified user segment browses to any of thepages that references the collection that contains the promotion.

• To create variants of a page. In this case, the triggers on the content items that populate the slotare more specific than the trigger criteria for the page. (Typically, they would "inherit" the parentcontent item's triggers and add additional criteria for the variable content.)

Following are some specific use cases for dynamic slots:• A brand manager needs to control the banner images that display throughout the site. This is a

different person from the merchandiser who typically manages pages in Experience Manager.• A brand manager needs to be able to specify the images that display at a particular navigation

state (for example, Digital Cameras > Samsung) even if there is no specific landing page for thatnavigation state.

• A merchandiser wishes to display promotions in the menu area based on more specific triggercriteria than those that apply to the page as a whole. For example, one could create a page to useas a base for all "Digital Cameras" pages, and populate the menu sections with more specificcontent based on the brand, price range, or other dimensions. This model enables content reusefor most of the content within a page with page-specific overrides for subsections as needed. Itremoves the need to create many individual pages for each specific combination of triggers.

• A merchandiser wishes to display promotions in the menu area based on trigger criteria that aresimply different from those on the page as a whole. For example, there might be a "Back to School"special for a particular time frame that applies to all pages within a category or even the entire site.This model enables content reuse for individual sections across a variety of pages. The reusablesections are managed in a central location so that updates immediately take effect across all thepages that include the reused content, rather than having to edit each one manually.

Dynamic slot prerequisites

The dynamic slot feature enables content administrators to populate a section of a content item withcontent from a different collection in Experience Manager. As a prerequisite, your application must


Configuring Front-End Application Features | Dynamic triggering features112

include a collection with the appropriate content type for populating an administrator's dynamic slotcartridge.

Note: If a content administrator attempts to populate a dynamic slot in a given collection witha content item from the same collection and creates a circular reference, the Assembler detectsthe conflict during preprocessing and returns the content item with an @error property.

Related LinksAbout content collections on page 16

Before a content administrator can configure dynamic content items within an application,you must create content collections to contain those items. Content items within the samecollection are evaluated against each other at runtime to determine which item (or items)should be returned to populate a defined section of the current page.


113Configuring Front-End Application Features | Dynamic triggering features

Chapter 8

Setting up the Preview Application for Workbench

If you are using Experience Manager, you can use a preview application to simulate sets of triggerconditions, such as time-based triggers, in order to determine which content items display when specificconditions are met. This section describes how to set up a custom Endeca application to function asthe preview application in Workbench.

About the preview applicationThe preview application is the end-user application that displays in a new browser tab or window whenselected. It allows content administrators to determine why each content item does or does not fire forspecified navigation query and trigger combinations. This chapter describes how to set up your owncustom application as the Workbench preview application.

You can launch the preview application for a specific page, or for an individual cartridge. A selectedcartridge will display in the context of a page that includes it.

It is not necessary for the preview application to be an exact representation of your final front-endapplication, as long as it is using the correct data. The business logic that is built into Workbench isnot tied to the physical representation of the front-end application. It is good practice, however, tomake sure that your preview application represents your final application closely enough so thatbusiness users know if their changes are correct.

By default, Workbench is configured to use the Discover Electronics reference application as thepreview application. This application is located under %ENDECA_TOOLS_ROOT%\reference\dis¬cover-electronics-authoring ($ENDECA_TOOLS_ROOT/reference/discover-electron¬ics-authoring on UNIX).

Workbench communicates with the preview application via settings you specify in the Preview Settingstool. The Preview URL field lets you specify the preview application URL.

Note: The preview application must not use frames, because they are likely to collide with theframes of the Workbench preview toolbar.

About auditing content using a preview applicationThe Workbench preview feature includes auditing functionality that enables business users to viewthe underlying triggers for the set of displayed content items. Instrumenting a custom application forpreview enables auditing.

If a content administrator wants to know which content items trigger for a specified navigation state,such as Category > Cameras, they can audit content by navigating to the desired state in the previewapplication. Clicking the Audit button for a content item displays the Audit Panel, which includes aStatus column as shown below:

Content Items can exist in any of the following states:

MeaningStatus

The content item triggers and displays for the current navigation and trigger states.Fired

The content item triggers for the current navigation and trigger states, but does notdisplay. This is due to one or more content items in the same collection having higher

Collection full

priority, causing the collection to reach its limit for the maximum number of allowablecontent items.

The content item does not trigger for the current navigation and trigger states.Notconsidered

The content item does not trigger. The navigation state conditions are met, butadditional trigger conditions (such as a schedule trigger) are not.

Navigationtrigger notsatisfied

About previewing specific devicesWorkbench preview functionality includes support for specifying a device to preview against for aspecified user agent.

The Preview Settings tool includes a Device Manager that allows you to map a user agent to a devicewith an associated preview skin. The Discover Electronics reference application includes the followingconfigured devices:

• Mobile (landscape and portrait orientations)• Tablet (landscape and portrait orientations)

Adding a device for previewYou can add additional device profiles and map them to the device skins included with Workbench.

To add a device for preview:

1. In Workbench, navigate to the Application Settings > Preview Settings tool.


Setting up the Preview Application for Workbench | About the preview application116

2. Click Add Device.The Add Device panel appears.

3. In the Device Name field, enter the device name to associate with your user agent.This is the unique name that appears in the Device dropdown when previewing your application.

4. Select the device skin from the Skin Name dropdown.5. In the User Agent field, enter the user agent string that you wish to add.6. Click Save.7. To confirm that your device is available for preview:

a) Navigate to the Experience Manager tool in Workbench.b) Navigate to a content item of your choosing.c) Mouseover the content item.

The Action dropdown button appears.d) Select Preview from the Action dropdown.

The preview application launches in a new browser tab.e) Click the arrow beside the Device: None entry in the Preview Toolbar:

The Preview Toolbar expands to show configuration options.f) Click the Device dropdown and confirm that your device is included in the dropdown list.g) Select the device name and click Submit.h) Confirm that the appropriate device skin displays.

Note: The preview application itself must have rendering logic for the selected user agentin order to display correctly.

Modifying a preview deviceYou can modify any of the fields for an existing preview device by clicking the device name in thePreview Settings tool.

To modify a preview device:

1. In Workbench, navigate to the Application Settings > Preview Settings tool.2. In the Device Name column, select the device you wish to edit.

The Edit Device panel appears.3. Modify the desired fields.4. Click Save.

Removing a preview deviceIf a device is not required for previewing your application, you can remove it from the preview toolbar.

To remove a preview device:

1. In Workbench, navigate to the Application Settings > Preview Settings tool.2. In the Delete column, click the X for the device you wish to remove.

A confirmation dialog appears.3. Click Delete.


117Setting up the Preview Application for Workbench | About the preview application

About instrumenting your application for previewIn order to enable auditing in your custom preview application, your rendering code must include logicfor adding preview frames and an "Audit" button to content items that your content administrator mousesover.

Your custom preview application should include tags that specify paths to the required JavaScript andCSS resources, as well as tags for enabling audit functionality. These are provided in the endeca taglibrary.

Note: These requirements assume an application that uses JSP files for cartridge renderers(as in the case of the Discover Electronics reference application). If you are using a differenttechnology stack to implement your Assembler application, you must write your own auditingfunctionality.

Adding Preview resources

All JSP files must include the endeca tag library, as shown below:<%@ taglib prefix="endeca" uri="/endeca-infront-assembler/utilityTags"%>

Each <head> tag must contain a reference to the pageHead tag. This includes paths to the PreviewJavaScript and CCS files:<head>

<endeca:pageHead rootContentItem="${rootComponent}"/> <title><c:out value="${component.title}"/></title> <meta name="keywords" content="${component.metaKeywords}" /> <meta name="description" content="${component.metaDescription}" /></head>

Enabling auditing

Each <body> tag must contain a reference to the pageBody tag. This wraps content slot componentsin a <div class="endeca-slot"> element and enables audit functionality:</head><body>

<endeca:pageBody rootContentItem="${rootComponent}"/> <div class="PageContent"...> <script type="text/javascript"...>

</endeca:pageBody></body></html>

Additionally, all JSP files that define a cartridge with content slots must include an includeSlot tag.This serves the same purpose as the reference to the pageBody tag for JSP files that do not containa <head> tag:<%@include file="/WEB-INF/views/include.jsp"%>

<endeca:includeSlot contentItem="${component}"> <c:forEach var="element" items="${component.contents}"> <discover:include component=${element}"/>


Setting up the Preview Application for Workbench | About instrumenting your application for preview118

</c:forEach></endeca:includeSlot>

Device-specific auditing

In order to handle preview for different devices, you must implement conditional rendering logic fordifferent user agent strings. The rendering code should include the tags described above.

You can retrieve the user agent String by getting a reference to the UserState object and callinggetUserAgent() on it. The UserState class is documented in the Javadoc for the com.endeca.in¬front.navigation package.

For example, the Discover Electronics reference application includes the following logic in theWEB-INF\services\assemble.jsp page:

UserState userState = webappCtx.getBean(properties.getProperty("us¬er.state.ref"), UserState.class);

String userAgent = userState.getUserAgent();

//If the userAgent is null, then no user-agent was specified and we need to get the user agent from the request header.if(userAgent == null){ userAgent = request.getHeader("user-agent");}

Enabling your preview applicationOnce you have finished instrumenting your preview application, you can enable it for use in Workbench.

Ensure that your application has been correctly instrumented before enabling it for preview inWorkbench.

All examples shown below are taken from the configuration files for the Discover Electronics authoringapplication, located in%ENDECA_TOOLS_ROOT%\reference\discover-electronics-authoring(on Windows) or $ENDECA_TOOLS_ROOT/reference/discover-electronics-authoring (onUNIX). The exact mechanisms used for configuring your Assembler and content sources will varydepending on your implementation details.

For a full description of the properties described below, see the Assembler API Javadoc for the Assem¬blerFactory and ContentSource interfaces and their corresponding implementations.

To enable your custom preview application:

1. In the constructor arguments for your AssemblerSettings, set the following:ValueProperty

truepreviewEnabled

http://localhost:8006/previewpreviewModuleUrl

In the Discover Electronics reference implementation, these are configured as properties inWEB-INF\assembler.properties:workbench.host=localhostworkbench.port=8006

# ... Additional settings removed from this example ...


119Setting up the Preview Application for Workbench | About instrumenting your application for preview

preview.enabled=true

These properties are then included in the Assembler context file,WEB-INF\assembler-context.xml:<bean id="assemblerFactory" class="com.endeca.infront.assembler.spring.SpringAssemblerFactory"scope="singleton"> <constructor-arg> <bean class="com.endeca.infront.assembler.AssemblerSettings">

<property name="previewEnabled" value="${preview.enabled}" /> <property name="previewModuleUrl" value="http://${work¬bench.host}:${workbench.port}/preview" /> </bean> </constructor-arg> <constructor-arg> <list> <bean class="com.endeca.infront.logger.SLF4JAssemblerEvent¬Logger" /> </list> </constructor-arg></bean>

2. In the constructor arguments for your WorkbenchContentSource, set isAuthoring to true.In the Discover Electronics reference implementation, isAuthoring takes the value of theis.authoring property:<bean id="contentSource" class="com.endeca.infront.content.source.Work¬benchContentSource" scope="singleton" init-method="init" destroy-method="destroy">

<property name="isAuthoring" value="${is.authoring}"/> <property name="appName" value="${workbench.app.name}" /> <property name="defaultSiteRootPath" value="/pages" /> <property name="host" value="${workbench.host}" /> <property name="workbenchPort" value="${workbench.port}" /> <property name="clientPort" value="${workbench.publishing.client¬Port}"/></bean>

3. Configure a link service for your application that returns a preview link as a JSONP response.

This service must construct a link to the page selected for preview; for example, if a contentadministrator previews the Brand - Canon Web Browse page in the reference application, theservice returns "/browse/_/N-25y6". Additionally, the response from the service is used toconstruct the links in the Audit Panel.

In Discover Electronics, the link service is configured as a link servlet that uses the com.ende¬ca.infront.web.spring.PreviewLinkServlet class. The servlet is defined inWEB-INF\web.xml:<servlet> <servlet-name>link</servlet-name> <servlet-class> com.endeca.infront.assembler.servlet.spring.SpringPre¬viewLinkServlet </servlet-class> <init-param> <description> The ID of the NavigationStateBuilder in the spring contextConfig file </description> <param-name>navigationStateBuilderBeanId</param-name> <param-value>navigationStateBuilder</param-value> </init-param> <init-param> <description> The ID of the MdexResource in the spring contextConfig file </description> <param-name>mdexResourceBeanId</param-name> <param-value>mdexResource</param-value> </init-param></servlet>

Changing the preview application in WorkbenchYou can set the preview application in Workbench by using the Preview Settings tool.

Once you have instrumented and enabled your application for preview, you can select it as the previewapplication in Workbench.

To change the preview application in Workbench:

1. In Workbench, navigate to the Application Settings > Preview Settings tool.2. Click the Edit link beside the Preview URL field.3. In the Preview URL field, enter the fully qualified URL of your preview application.

If you wish to revert to the default Discover Electronics preview application, recall that the URL ishttp://<host>:<port>/discover-electronics-authoring, orhttp://localhost:8006/discover-electronics-authoring by default.

4. Click Save.The application at the specified URL is now used for preview.

Changing the preview link serviceIf you have implemented your own link service for use with preview, you can specify the path to theservice in your application in the Preview Settings tool.

Once you have created your own preview link service, you can specify it for use with preview insteadof the default link service included with the Discover Electronics reference application.



Note: For information on the required inputs and outputs for a link service, see the Javadoc forthe AbstractPreviewLinkServlet class in the com.endeca.infront.assem¬bler.servlet package.

To change the preview link service:

1. Stop the Endeca Tools Service.2. Open your application's deployment descriptor file, web.xml.

For the Discover Electronics reference application, this file is located at%ENDECA_TOOLS_ROOT%\reference\discover-electronics-authoring\WEB-INF\web.xml.

3. Define the link servlet.The servlet definition for the Discover Electronics reference application is shown below:<servlet> <servlet-name>link</servlet-name> <servlet-class> com.endeca.infront.assembler.servlet.spring.SpringPre¬viewLinkServlet </servlet-class> <init-param> <description> The ID of the NavigationStateBuilder in the spring contextConfig file </description> <param-name>navigationStateBuilderBeanId</param-name> <param-value>navigationStateBuilder</param-value> </init-param> <init-param> <description> The ID of the ContentSource in the spring contextConfig file </description> <param-name>contentSourceBeanId</param-name> <param-value>contentSource</param-value> </init-param></servlet>

4. Define the link servlet mapping.For example:<servlet-mapping> <servlet-name>link</servlet-name> <url-pattern>/servlet/link.json/*</url-pattern></servlet-mapping>

5. Save and close the file.6. Start the Endeca Tools Service.7. Login to Workbench.8. In Workbench, navigate to the Application Settings > Preview Settings tool.9. Click the Edit link beside the Link Settings URL field.10. In the Link Settings URL field, enter the fully qualified URL of your link service within the application.

If you wish to revert to the default Discover Electronics reference application and link servlet, recallthat the URL for the link servlet is http://<host>:<port>/discover-authoring/link.json.

11. Click Save.



The link service at the specified URL is now used for preview.

Testing your preview applicationAfter instrumenting and enabling your preview application, you can test the preview and auditfunctionality in Endeca Workbench.

Your custom preview application must be fully instrumented and enabled in Workbench in order forthe preview option to display.

To test your custom preview application:

1. In Workbench, navigate to the Experience Manager tool.2. Navigate to a content item of your choosing.3. Mouseover the content item.

The Action dropdown button appears.4. Select Preview from the Action dropdown.

The preview application launches in a new browser tab.5. Optionally, specify the preview time instead of using the default indicated by the system clock for

the MDEX Engine:a) Click the arrow beside the selected Device in the Preview Toolbar:

The Preview Toolbar expands to show configuration options.b) Select a device from the Device dropdown and click Submit.Specifying a preview device lets you see how the application renders on that device.

6. To test audit functionality:a) Mouseover the cartridge you wish to audit.

The Audit button appears.b) Click the Audit button.

The Audit Panel appears with a list of all content items for the specified content collection:

c) Click any of the listed Locations to navigate to that location in the preview application.d) Click the name of any of the listed content items and confirm that you return to that item in

Experience Manager.



Chapter 9

Enabling Endeca Query Language in yourAssembler application

Endeca Query Language allows you to apply additional filters to an end user's search and navigationstate in your application.

About Endeca Query LanguageEndeca Query Language (EQL) enables you to filter the records returned from the MDEX Enginebased on your own criteria. By combining an EQL filter with an end user's search and navigation state,you can present a more relevant set of results.

Using EQL in your application enables you to develop for the following scenarios:• Your data set requires you to enable search against more than one search interface at a time —

For example, if you wish to enable both thesaurus expansion and wildcard search on an end user'ssearch terms, you must configure two separate search interfaces (since wildcard search is notcompatible thesaurus expansion). In this case, you can configure the wildcard search as an "or"in the EQL expression.

• You are dealing with a data set that requires record joins — This can be a product catalog whereeach "product" record contains different properties or properties with slightly differing values,depending on the location that entered the data. In this case, you may wish to configure a defaultEQL filter that performs a record join and executes a search against the combined recordinformation.

For a detailed overview of the syntax and capabilities of EQL, see "Using the Endeca Query Language"in the MDEX Engine Advanced Development Guide.

Applying an EQL filter in a Java applicationIf you are developing a Java Assembler application, you can apply an EQL filter to an end user's filterstate by creating the expression as an instance of the EqlFilter class, and calling the setEqlFil¬ter() method to apply it to your filter state.

Note: The approach outlined below is one suggested implementation of the EQL feature. If youare relying on the packaged services to interface with the Assembler, you must instead pass

EQL filters to your application through the Nrs URL parameter. You can also configure a single,default EQL filter that applies across your entire application.

To apply an EQL filter programatically:

1. Decide where to insert your EQL logic.Oracle recommends extending the UrlNavigationStateBuilder class.

2. Duplicate the current filter state in the application as an EQL expression://Retrieve the search key, terms, and match mode from the search filter in the parsed FilterStateif (filterState.getSearchFilters() != null && filterState.getSearchFil¬ters().size() > 0){ String searchTerms = filterState.getSearchFilters().get(0).getTerms();

String searchKey = filterState.getSearchFilters().get(0).getKey(); String matchMode = filterState.getSearchFilters().get(0).getMatch¬Mode().toString();

//Build the EQL expression using the first search filter String eqlExpression; if (matchMode == null){

eqlExpression = "collection()/record[endeca:matches(.,\"" + searchKey + "\",\"" + searchTerms + "\"); } else {

eqlExpression = "collection()/record[endeca:matches(.,\"" + searchKey + "\",\"" + searchTerms + "\",\"" + matchMode + "\"); };

3. Make any desired customizations to the EQL expression.For example, to execute a normal search but wildcard search terms when matching against the"product.id" dimension, you could use the following expression: if (matchMode == null){ eqlExpression = "collection()/record[endeca:matches(.,\"" + searchKey + "\",\"" + searchTerms + "\") or endeca:matches(.,\"product.id\",\"" + searchTerms + "*\")]"; } else { eqlExpression = "collection()/record[endeca:matches(.,\"" + searchKey + "\",\"" + searchTerms + "\",\"" + matchMode + "\") or endeca:matches(.,\"prod¬uct.id\",\"" + searchTerms + "*\")]"; };

4. Create your EQL filter as an instance of the EqlFilter class and set the EQL expression: //Create a EqlFilter and set it on the filterState EqlFilter eqlFilter = new EqlFilter(); eqlFilter.setExpression(eqlExpression);

5. Return the completed filter state to your application and handle it as necessary.


Enabling Endeca Query Language in your Assembler application | Applying an EQL filter in a Javaapplication

126

About configuring an EQL filter using the Nrs URLparameter

You can pass an EQL expression to your application through the Nrs URL parameter.

Once you have created an EQL expression, you can use the Nrs URL parameter pass it into theUrlNavigationStateBuilder, for example:Nrs=collection()/record[endeca:matches(.,"product.description",searchTerms)]

For additional information about the UrlNavigationStateBuilder and a full list of associated URLparameters, refer to the class documentation in the Assembler API Reference (Javadoc).

About configuring a default EQL filterYou can apply an EQL filter to your application's default filter state.

You may wish to apply a specific, consistent EQL expression to all queries in your application.

You can configure a default EQL filter for your application by specifying it as a eqlFilter propertyon the default FilterState.

In the Discover Electronics reference application, this is configured in the Assembler context file:<bean id="navigationStateBuilder" scope="request" class="com.endeca.infront.navigation.url.UrlNavigationStateBuilder"> <property name="defaultFilterState"> <bean scope="singleton" class="com.endeca.infront.navigation.mod¬el.FilterState">

<property name="eqlFilter"> <bean scope="request" class="com.endeca.infront.naviga¬tion.model.EqlFilter"> <property name="expression" value="collec¬tion()/record[...]" /> </bean> </property>

 </bean> </property>

</bean>

For additional information about search interfaces, see the MDEX Engine Basic Development Guide.

About applying Relevance Ranking to EQL resultsYou can apply Relevance Ranking to search keys, terms, and match modes other than those specifiedin the search filter.

You can specify your relevance ranking settings programatically through the ResultsListConfigobject, or through the relevance ranking URL parameters. To apply these to your EQL query ratherthan the end user's search filter, pass in the EQL-specific values when setting the relRankStrategy,relRankKey, and relRankTerms properties (or the associated URL parameters). You must useone of these two methods to set the properties if you wish to apply relevance ranking to the EQL searchresults rather than the results from the end user's search filter.


127Enabling Endeca Query Language in your Assembler application | About configuring an EQL filter usingthe Nrs URL parameter

For additional information, see the Assembler API Reference (Javadoc) and the documentation forthe Results List cartridge.

Related LinksConfiguration model for the Results List cartridge on page 104

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

About troubleshooting EQL performanceIf you wish to determine the impact of EQL expressions on your application, you should review theperformance of cartridge handlers that are EQL-enabled.

EQL-enabled queries are not categorized separately in application logs; instead, you should reviewthe performance metrics and behavior of cartridges that use EQL expressions. If you are modifying acartridge handler to use EQL or creating a new cartridge handler that includes the feature, Oraclerecommends supplementing the logging information for that cartridge to reflect the presence of EQL.


Enabling Endeca Query Language in your Assembler application | About troubleshooting EQLperformance

128

Chapter 10

Using an MDEX Engine to Manage Media Assets

If you are storing media resources in an independent content store, you can set up an MDEX Enginewhere records represent media assets and include asset metadata and URIs. Storing this informationas records enables Guided Navigation in the Experience Manager Media Browser, allowing contentadministrators to easily navigate across resources when selecting media assets for a content item.

Interaction between an Endeca application and the mediaMDEX Engine components

The interactions between a media MDEX Engine, Experience Manager, and Endeca Web applicationare summarized below.

Note that for simplicity, the MDEX Engine backing the Endeca Web application is not shown in thediagrams below.

Interaction between the media MDEX Engine and Experience Manager

Experience Manager retrieves media asset information as follows:

1. A CAS crawl and Forge pipeline populate the media MDEX Engine with media asset metadata andURIs from one or more content sources.

2. In Experience Manager, the Media Browser queries the media MDEX Engine for media records.This allows the content administrator to select media assets by navigating across them with GuidedNavigation.

3. The content administrator's configuration changes are published to the Endeca application eachtime a content item is saved.

Interaction between the media content source and an Endeca application

In a production environment, the Endeca Web application can be configured to retrieve media assetsfrom a content delivery network or another media delivery server:

1. Media assets are uploaded from the media content source to the runtime content delivery network.2. The Web application retrieves media from this content delivery network.

Note: The server hosting your media assets can differ between authoring and live environments,as long as the media path relative to the media root is consistent. In the case of the referencedata application, the Endeca Configuration Repository is used as the authoring content source.For more information on configuring content sources, see "About Media editor configuration" inthe "Template Property and Editor Reference" Appendix.

Related LinksAbout Media editor configuration on page 175

You can specify allowable media formats in the editor configuration file. You can also enableor disable the Media Browser, and specify the MDEX Engine that it should query for mediarecords.

About resolving media paths in content items on page 179


Using an MDEX Engine to Manage Media Assets | Interaction between an Endeca application and themedia MDEX Engine components

130

Links to media assets are resolved in the Media editor by combining configuration in theeditor configuration file with the media.path property on the selected record. At runtime,these links are resolved against the media sources specified in the Assembler context file.

Uploading media content for use in Experience ManagerAll applications created using the Deployment Template include a set_media script in the <appdir>\control directory. This script uploads media content from the <app dir>\config\mediadirectory to the Endeca Configuration Repository. You run the script after you locally add content to<app dir>\config\media. After uploading the content, it becomes available for use in ExperienceManager.

In general, you can store moderate amounts of media content in the Endeca Configuration Repository.Very roughly speaking, a moderate amount of media content is approximately thousands of mediafiles but not tens of thousands of media files. This storage mechanism is intended as a conveniencewhen you build an application in a development environment.

If you have larger amounts of media content, Oracle recommends employing a digital asset managementsystem rather than uploading the media content into the Endeca Configuration Repository.

Here are a few specific guidelines to keep in mind before you upload media content to the EndecaConfiguration Repository:

• Do not upload more than approximately 1 GB of media content per transaction. In this context, atransaction is one run of set_media.

• Do not upload more than approximately 5000 files in one transaction. This guideline essentiallymeans you should not have more than approximately 5000 files stored in <appdir>\config\media and its subdirectories.

• If you have more than approximately 1000 files to upload, create subdirectories under <appdir>\config\media and distribute the media files among the subdirectories. (One run ofset_media uploads all content in all subdirectories.)

To upload media content for use in Experience Manager:

1. Ensure any new media content is stored locally in <app dir>\config\media.This may include image files, video files, and so on.

2. Start a command prompt (on Windows) or a shell (on UNIX).3. Navigate to the <app dir>\control directory of your deployed application.

This is located under your application directory. For example: C:\Endeca\apps\<appname>\control.

4. Run the set_media script.

Overview of the reference data applicationThe Tools and Frameworks package includes a reference implementation of a media MDEX Enginethat includes a CAS crawl and Forge pipeline for crawling resources in the Endeca ConfigurationRepository and indexing the corresponding metadata and URIs. The Experience Manager can thenquery the MDEX Engine for record information.


131Using an MDEX Engine to Manage Media Assets | Uploading media content for use in ExperienceManager

Endeca software requirements

In addition to the hardware and software required for Oracle Endeca Tools and Frameworks, the dataingest process for the media MDEX Engine requires the Oracle Endeca Content Acquisition System.You must have CAS 3.1.1 installed on the machine on which you are hosting your media MDEX Engine.

Media MDEX CAS crawl

Below is a representation of the CAS crawl for the media MDEX Engine:

Important: A connector for the JSR-170 Compliant data source is provided for the referenceapplication, but requires a separate license for use. To obtain licensing information for thisconnector, contact your Oracle sales representative.

The crawl uses the following manipulators:

1. Directory Filter: This manipulator filters out directory records, so that only media files are outputto the MDEX Engine.

2. Property Renamer: This manipulator maps crawled property value names to the schema used bythe Media Browser in Experience Manager. For more information, see "Media MDEX Engine schemadefinition."

3. Application Property Generator: This manipulator analyzes record paths to determine whichapplication a record is associated with (if any) and assigns it to a media.site property. This allowsthe Media Browser to display only those media assets that are relevant to the application that thecontent administrator is currently modifying in Workbench.

4. Image Property Generator: This manipulator analyzes image binaries to determine their widthand height. It then adds corresponding height and width properties to each record.

Media MDEX Forge pipeline

The Forge pipeline for the reference data application reads data from the Endeca Record Storepopulated by the CAS crawl, and runs a baseline update to index records to the media MDEX Engine.


Using an MDEX Engine to Manage Media Assets | Overview of the reference data application132

Important: The reference media MDEX Engine and data application are provided as exampleimplementations. If you wish to connect to an external data source, you must configure a CAScrawl specific to your data set, including a custom repository adapter and custom recordmanipulators as necessary. Additionally, your MDEX Engine configuration must include certainproperties in order to function correctly with the Media editor in Experience Manager. For details,see "Media MDEX Engine schema definition."

Related LinksMedia MDEX Engine schema definition on page 134

In order for the Media Browser in Experience Manager to have sufficient information forforming content XML, any media MDEX Engine that you configure must define specificproperties and dimensions.

Deploying the media MDEX Engine data applicationThe media MDEX Engine data application assumes an environment where all required Oracle Endecacomponents are running on the same machine.

You must have the Oracle Endeca Content Acquisition System and Oracle Endeca Tools andFrameworks installed on the machine onto which you wish to deploy the media MDEX Engine.Additionally, your Discover Electronics reference application must be deployed and running.

To deploy the media MDEX Engine data application:

1. Include the CAS manipulators for the reference data application as server plugins:a) Navigate to the %CAS_ROOT%\lib\cas-server-plugins.b) Create a directory named mediaMDEX.c) Navigate to the

%ENDECA_TOOLS_ROOT%\reference\media-mdex-cas\cas\media-mdex-manipulatorsdirectory.

d) Copy the following JAR files to the %CAS_ROOT%\lib\cas-server-plugins\mediaMDEXdirectory you created in step 1b:

• media-mdex-manipulators-3.1.1.jar

• google-collections-1.0.jar

2. Set up CAS for crawling JSR-170/ 283 compliant Jackrabbit repositories:a) Navigate to the

%ENDECA_TOOLS_ROOT%\reference\media-mdex-cas\cas\dependencies directory.b) Copy the CAS dependencies to the %CAS_ROOT%\lib\server directory:

• jackrabbit-jcr-rmi-2.2.9.jar• jcr-2.0.jar

3. Restart the CAS Service.4. Deploy the reference data application:

a) Open a command prompt or command shell.

Note: If you are running the Tools and Frameworks from the included batch files,you must run <EndecaDirectory>/ToolsAndFrameworks/<version>/server/bin/setenv.batto set the environment variables for the current command window.


133Using an MDEX Engine to Manage Media Assets | Overview of the reference data application

b) Navigate to theC:\Endeca\ToolsAndFrameworks\<version>\deployment_template\bin directoryon Windows, or/usr/local/endeca/ToolsAndFrameworks/<version>/deployment_template/binon UNIX.

c) Run deploy.bat or deploy.sh with the following options:deploy --app <Endeca Directory>/ToolsAndFrameworks/<version>/refer¬ence/media-mdex-cas/deploy.xml

d) Confirm the Platform Services installation directory.e) Enter n to skip installation of a base application.f) Specify media as the application name.g) Specify the Endeca application directory.

Typically, this is C:\Endeca\apps on Windows, or /usr/local/endeca/apps on UNIX.h) Specify the EAC port previously used for the Discover Electronics reference application.

By default, this is port 8888.i) Specify the port that Workbench is running on.

By default, this is port 8006.j) Specify the Dgraph and LogServer ports for your reference data application.

Note: These must be different from those used for the Discover Electronics referenceapplication.

By default, this is port 17000 for the Dgraph and port 17010 for the LogServer. If you changethese values, you must also update the configuration for the MediaEditor in the <appdir>\config\editors_config\editors.xml file.

k) Specify the CAS installation directory.l) Enter the port that CAS runs on.m) Enter the hostname that Workbench runs on.

This information enables the data application to locate and query the Endeca ConfigurationRepository during the data ingest process.

n) Enter the name of the Discover Electronics application as specified during deployment.By default, this should be Discover.

5. Initialize and run a baseline update on the media MDEX Engine:a) Navigate to the control directory of your deployed data application.b) Run the initialize_services batch or shell script.c) Run the baseline_update batch or shell script.

Media MDEX Engine schema definitionIn order for the Media Browser in Experience Manager to have sufficient information for forming contentXML, any media MDEX Engine that you configure must define specific properties and dimensions.

Required properties

The following properties are required for the Media Browser to function correctly:


Using an MDEX Engine to Manage Media Assets | Media MDEX Engine schema definition134

DescriptionField

A unique identifier for each of the media items.record.id

The filename of the media asset.media.name

The file path, relative to the root of the content source.media.path

The logical host of the content source. The value of this property is mappedto configuration elements for the Media editor in the editor configuration

media.repository_id

file, which in turn contain the path to the content source. For additionalinformation, see "About Media editor configuration."

The EAC application that the specified media asset is associated with.The Media editor in Experience Manager filters entries in the Media

media.site

Browser based on which application the content administrator is currentlyediting.

The binary size of the media asset, in bytes.media.size

The height of the media asset, if it is an image. The renderer for the Mediaeditor uses this information to scale images appropriately.

image.height

The width of the media asset, if it is an image. The renderer for the Mediaeditor uses this information to scale images appropriately.

image.width

Properties and dimensions provided in the reference data application

Optionally, additional properties and dimensions can be displayed in the Media Browser. The referencemedia MDEX Engine includes the following such fields:

DescriptionTypeField

The MIME type of the media asset. This enables filteringby media type and file extension in the Media Browser.

Dimensionmedia.mime_type

The user who uploaded the specified asset to the EndecaConfiguration Repository. This enables filtering by authorin the Media Browser.

Dimensionmedia.author

The date and time that the file was created on the EndecaConfiguration Repository.

Propertymedia.creation_date

The date and time that the file was last modified prior tobeing crawled by the Content Acquisition System.

Propertymedia.last_modifica¬tion_date

If you configure your own media MDEX Engine that includes properties or dimensions not listed above,they become available for Guided Navigation in the Media Browser. However, any such propertiesare not saved in the content XML once a media asset has been selected.

Search interface requirements

The Media Browser requires a defined search interface named "All" that includes all searchableproperties and dimensions in the data set. Additionally, the Media Browser in the reference applicationuses the "MatchAllPartial" search mode.

Related LinksAbout the Media Browser on page 174


135Using an MDEX Engine to Manage Media Assets | Media MDEX Engine schema definition

The default asset browser for the Media editor can only be configured to browse media assetsin the Endeca Configuration Repository. If you are using another system for managing mediaassets, you must stand up a corresponding media MDEX Engine and enable the MediaBrowser in the editor configuration file.


Using an MDEX Engine to Manage Media Assets | Media MDEX Engine schema definition136

Chapter 11

Understanding and Debugging Query Results

The MDEX Engine provides several methods for understanding why certain results were returned fora query so that you can determine how to tune search features to provide the desired results.

About the query debugging featuresThe MDEX Engine query debugging features include Why Match, Word Interpretation, Why Rank, andWhy Precedence Rule Fired. Each feature provides information on a different aspect of search results.

DescriptionFeature

Augments record results with information about which record propertieswere involved in search matching.

Why Match

Augments record results with information about which relevance rankingmodules ordered the results and why a particular record was ranked inthe way that it was.

Why Rank

Augments root dimension values with information about how theprecedence rule was triggered (explicitly or implicitly), which dimension

Why Precedence Rule Fired

ID and name triggered the precedence rule, and the type of precedencerule (standard, leaf, or default).

Reports word or phrase substitutions made during text search processingdue to stemming, thesaurus expansion, or spelling correction.

Word Interpretation

About enabling query debugging featuresYou enable the query debugging features on an Endeca Assembler application via the debugEnabledconstructor argument on your MdexRequestBroker object. In the Discover Electronics referenceapplication, this is configured in the MDEX Resource section of the Spring context file for the Assembler.

When debugEnabled is set to true, it enables query debugging features to be applied to an Assemblerrequest. When set to false, debugging features are turned off for every request. Debugging featuresare disabled by default.

Important: Query debugging features are not optimized for performance and can be veryexpensive to process. For both performance and security reasons, the debug constructor argumentshould always be set to false in a production environment.

In addition to the corresponding object configuration, Word Interpretation must be enabled via the--wordInterp Dgraph flag.

The following shows the default MDEX resource configuration in the Discover Electronics application:<bean id="mdexRequestBuilder" scope="request" class="com.endeca.infront.nav¬igation.request.MdexRequestBroker"> <constructor-arg ref="mdexResource" /> 

<constructor-arg value="false"/></bean>

URL parameters for query debugging featuresAll query debugging features except for Word Interpretation may be enabled on a per-query basis viaURL parameters.

The following parameters take a value of 1 (for enabled) or 0 (for disabled):• whymatch

• whyrank

• whyprecedencerulefired

The Word Interpretation feature can only be enabled at the level of an individual cartridge handler.

Note: If the debug constructor argument on the MDEX resource bean is set to false, alldebugging features are disabled on every request regardless of URL parameters.

About query debugging results in the reference applicationIn Discover Electronics, query debugging results can be returned as part of the response model forthe Results List, Search Adjustments, and Refinement Menu cartridges as appropriate. In the DiscoverElectronics reference application, these results can be enabled by un-commenting the correspondingproperties in each cartridge handler.

The debugging results are returned as properties on returned records:

ResultsFeature

Returns information about why each record matched the query in aDgraph.WhyMatch property on the record.

Why Match

Returns information about why each record was ranked the way it wasin a Dgraph.WhyRank property on the record.

Why Rank

Returns information about precedence rules that fired on a query in aDGraph.WhyPrecedenceRuleFired property on each root dimensionvalue.

Why Precedence Rule Fired


Understanding and Debugging Query Results | URL parameters for query debugging features138

ResultsFeature

Returns information about word or phrase substitutions as a map thatcan be accessed via getInterpretedTerms() on the SearchAd¬justments model.

Word Interpretation

For details about the format of the debugging results, refer to the MDEX Engine Advanced Developer'sGuide.

Note: The renderers in the Discover Electronics application do not include rendering logic todisplay the query debugging properties, but the information is available from the JSON or XMLview.

The relevant configuration for the individual cartridge handlers in the Discover Electronics referenceapplication is shown below:

• Results List — Why Match, Why Rank<bean class="com.endeca.infront.cartridge.ResultsListConfig" scope="sin¬gleton">

 

</bean>

Enabling these settings overrides the default values specified for the setWhyMatchEnabled andsetWhyRankEnabledmethods on thecom.endeca.infront.cartridge.ResultsListCon¬fig object when the Endeca Tools Service is initialized.

• Refinement Menu — Why Precedence Rule Fired<bean class="com.endeca.infront.cartridge.RefinementMenuConfig" scope="singleton"> <property name="moreLinkText" value="More..."/> </bean>

Enabling this setting overrides the default value specified for the setWhyPrecedenceRuleFiredmethod on the com.endeca.infront.cartridge.RefinementMenuConfig object when theEndeca Tools Service is initialized.

• Search Adjustments — Word Interpretation<bean class="com.endeca.infront.cartridge.SearchAdjustmentsConfig" scope="singleton">

</bean>

Enabling this setting overrides the default value specified for the setShowWordInterp methodon the com.endeca.infront.cartridge.SearchAdjustmentsConfig object when theEndeca Tools Service is initialized.

Important: In order for interpreted word information to be available, you must start yourDgraph with the --wordInterp flag. This flag is not enabled in the deployment descriptorfile for the Discover Electronics reference application.


139Understanding and Debugging Query Results | About query debugging results in the reference application

Chapter 12

Configuring Logging for an Assembler Application

By default, the Assembler logs the search and navigation information associated with a request event.However, you can create custom cartridge handlers to collect and act on any information that isimportant to your application.

About request eventsEach invocation of the Assembler creates an associated RequestEvent object that tracks requestinformation.

Information on a RequestEvent is stored as key/value pairs. You can include arbitrary informationon an Assembler request by extending the RequestEvent object in a cartridge handler's processmethod. For example:/** * Cartridge Handler process method */public void process(ConfigType pContentType) {

// Create a new RequestEvent from the global RequestEvent object RequestEvent event = RequestEventFactory.getEvent();

// Store arbitrary information event.put("myKey","my arbitrary value");

...}

The NavigationEventWrapper class

The NavigationEventWrapper class provides convenience methods for getting and setting commonsearch and navigation information on a request event. It modifies the RequestEvent object specifiedin the constructor, as in the example below:/** * Cartridge Handler process method */public void process(ConfigType pContentType) {

// Create a new NavigationEventWrapper around the global RequestEvent object NavigationEventWrapper navigationEvent = new NavigationEventWrapper(Re¬

questEventFactory.getEvent());

// Store navigation event information navigationEvent.setAutocorrectTo("autocorrected term");

...}

For additional information about the RequestEvent and NavigationEventWrapper classes,including a full list of the convenience methods available for the NavigationEventWrapper, seethe Assembler API Reference (Javadoc).

About request event adaptersRequest event adapter classes perform some action based on information included with a requestevent.

A request event adapter class implements the handleAssemblerRequest()method in the abstractRequestEventListener class. This method is invoked at the end of the Assembler's assemble()method.

The following is an example of a simple request event adapter:/** * Add log information to root content item */public class SampleRequestEventAdapter extends RequestEventListener {

/** * Constructor * @param sessionIdProvider provides an ID for the current user session

*/ public SampleRequestEventAdapter(SessionIdProvider sessionIdProvider) { super(sessionIdProvider); }

/** * Prints the request event's session id and search term (if present) to the console * @param assemblerRequestEvent the event containing all of the * information about the Assembler request * @param rootContentItem the Assembler output */

public void handleAssemblerRequestEvent(RequestEvent event, ContentItem rootContentItem) { NavigationEventWrapper navigationEvent = new NavigationEventWrap¬per(assemblerRequestEvent); // Print Session ID - Note that the session Id has already been determined and set in the event object System.out.println("The current session is: "+event.getSessionId());

// Print Search Term if (navigationEvent.getSearchTerms() != null && !navigationEvent.get¬SearchTerms().trim().isEmpty()) { System.out.println("The current search terms are: "+navigation¬


Configuring Logging for an Assembler Application | About request event adapters142

Event.getSearchTerms()); } else { System.out.println("There were no search terms in the current request"); } }}

The SessionIdProvider interface

The example request event adapter above registers an implementation of SessionIdProvider inthe constructor. This enables it to retrieve the server session ID.

The Oracle Endeca Tools and Frameworks installation implements this interface in the includedSpringUtility class. You can create your own SessionIdProvider class by extending theSessionIdProvider interface and implementing the getSessionID() method.

Request event adapters in the reference application

The Discover Electronics reference application includes the following implementations of the Assem¬blerEventListener interface:

• AssemblerEventAdapter• ContentItemAugmentAdapter• LogServerAdapter• RequestEventListener

For additional information on these classes, see the Assembler API Reference (Javadoc).

About registering a request event adapterTo use a request event adapter, you must register it with your AssemblerFactory.

You can disable request event adapters by removing them from the AssemblerFactory configuration.

Request event adapter configuration in the reference application

In the reference application, the AssemblerFactory interface is implemented as SpringAssem¬blerFactory, and the AssemblerEventListener objects are specified as constructor argumentsin the Assembler context file:<bean id="assemblerFactory" class="com.endeca.infront.assem¬bler.spring.SpringAssemblerFactory" scope="singleton"> <constructor-arg> <bean class="com.endeca.infront.assembler.AssemblerSettings"> <property name="previewEnabled" value="${preview.enabled}" /> <property name="previewModuleUrl" value="http://${work¬bench.host}:${workbench.port}/preview" /> </bean>


143Configuring Logging for an Assembler Application | About request event adapters

</constructor-arg> <constructor-arg> <list> <bean class="com.endeca.infront.logger.SLF4JAssemblerEventLogger" />

<bean class="com.endeca.infront.assembler.event.request.Con¬tentItemAugmentAdapter"> <constructor-arg ref="springUtility"/> </bean> <bean class="com.endeca.infront.navigation.event.LogServer¬Adapter"> <constructor-arg ref="springUtility"/> <constructor-arg value="${logserver.host}"/> <constructor-arg value="${logserver.port}"/> </bean> </list> </constructor-arg></bean>

Request event adapters in the reference applicationThe reference application includes two request event adapters, ContentItemAugmentAdapter andLogServerAdapater.

DescriptionAdapter

Appends request event information to the ContentItem returned by the assemble() method.

com.endeca.infront.assembler.re¬quest.ContentItemAugmentAdapter

Information is included as a nested Content Itemof type AssemblerRequestEvent, with thekey endeca:assemblerRequestInforma¬tion. For a list of attributes that are availableout-of-the-box, see Request Event Attributes onpage 203.

Formats data from the request event and sendsit to the Oracle Endeca Log Server, which allows

com.endeca.infront.naviga¬tion.event.LogServerAdapter

Workbench users to generate reports using theReport Generator.

The adapter must be configured with the hostand port of the log server. In the referenceapplication, these values are configured in theWEB-INF\assembler.properties file.

Client side click eventsThe Oracle Endeca log server tracks the following click events from the client side of an Assemblerapplication:


Configuring Logging for an Assembler Application | Client side click events144

DescriptionTypeAttribute Key

Did the user select a dimension search result.BooleanIN_DIM_SEARCH

Did the user select the "did-you-mean" value.BooleanIN_DYM

Did the user select a merch rule (spotlight).BooleanIN_MERCH

Did an action cause a conversion.BooleanCONVERTED

You can include the information collected from these events in your application reports. For moreinformation about the Log Server and Report Generator components, refer to the Platform ServicesLog Server and Report Generator Guide.


145Configuring Logging for an Assembler Application | Client side click events

Appendix A

Template Property and Editor Reference

This section describes how to define basic content properties and associated editing interfaces inExperience Manager templates.

Editor property mapping referenceThis section provides an overview of which property types are associated with the different OracleEndeca Commerce Suite editors.

Oracle Endeca Commerce Core Editors

The following core editors are included with all installations of Oracle Endeca Commerce:

FunctionalityPropertyType

Editor

Displays as a checkbox that the content administrator selectsor de-selects. Optionally, the editor may be set to a read-onlystate.

<Boolean>BooleanEditor

Displays as a dropdown with an optional default value. Thecontent administrator selects from a set of pre-definedvalues.

<String>ChoiceEditor

Displays as a drop-down list for specifying a valid contentcollection, and a numeric stepper for setting the evaluationlimit for that collection.

<String>DynamicSlot Editor

Displays an image from a specified URL.(None)ImagePreview

Displays as a one-line text field with a pair of arrow buttonsfor increasing or decreasing the value by a set amount. The

<String>NumericStepperEdi¬tor

content administrator inputs or adjusts the value to anynumber within the minimum and maximum boundariesdefined in the editor.


Editor

Displays as a series of radio buttons with an optional defaultvalue. The content administrator selects from a set ofpre-defined values.

<String>RadioGroupEditor

<xavia:List>RecordListEditorImportant: This editor is deprecated. Use the Spot¬lightSelectionEditor instead.

Displays as a button that launches the microbrowser andallows the content administrator to select the list of recordsthat populates a<xavia:Item class="com.endeca.in¬front.cartridge.RecordSpotlightSelection"/>record selection property.

Displays as a slider bar. The content administrator selectsa value by moving the slider along specified intervals withinthe minimum and maximum boundaries defined in the editor.

<String>SliderEditor

Displays as a button that launches the Select Recordsdialog and allows the content administrator to select the

<xavia:Item>SpotlightSelec¬tionEditor

navigation state or list of records that populates a<xavia:Item class="com.endeca.infront.car¬tridge.RecordSpotlightSelection"/> recordselection property.

Displays as a text field or text area. The content administratorenters arbitrary string values. Optionally, the editor may beset to a read-only state to display a fixed, default value.

<String>StringEditor

Oracle Endeca Experience Manager Editors

The following editors are included in the Oracle Endeca Experience Manager package:


Editor

Displays as a three-pane, drag-and-drop interface consistingof a central pane that lists available dimension refinements,

<xavia:List>BoostBuryEditor

a left pane for boosted refinements, and a right pane forburied refinements. The content administrator can filter thelist of available dimensions by searching against a text string.

The editor populates two <xavia:List> properties, onefor boosted dimension refinements and one for burieddimension refinements.


Template Property and Editor Reference | Editor property mapping reference148


Editor

Displays as two panes, Boosted Records and BuriedRecords, each with an Edit List button that launches the

<xavia:List>BoostBuryRecordEdi¬tor

Select Records dialog. The content administrator uses theSelect Records dialog to populate the lists of boosted andburied records.

The editor populates two <xavia:List> properties, onefor boosted records and one for buried records.

Displays as two panels, one with a list of availabledimensions and one with a list of selected dimensions. The

<xavia:List>DimensionListEdi¬tor

content administrator can drag values back and forthbetween the two lists.

Displays as a dropdown. The content administrator selectsa value from the list of available dimensions retrieved fromthe MDEX Engine.

<String>DimensionSelec¬torEditor

The editor populates two <xavia:String> properties, onefor the dimension name and one for the ID.

Displays as two panels, one with a list of available dimensionrefinements and one with a list of selected refinements. The

<xavia:List>DimvalListEditor

content administrator can drag values back and forthbetween the two lists. Additionally, the list of availablerefinements includes a search box for finding specificrefinements in a large data set.

Displays as a button for launching the Generate GuidedNavigation wizard, which allows a content administrator to

<Con¬tentItem¬List>

GuidedNavigationEd¬itor

select and order a set of dimensions in order to createmultiple Refinement Menu cartridges at once.

Displays two radio buttons, one for specifying an Externallink via a text field, and one for specifying an Internal

<xavia:Item>LinkBuilderEditor

(Relative) link. The content administrator specifies a relativelink by selecting a servlet from a dropdown list, thenlaunching theSelect Records dialog to navigate to a specificrecord or a navigation state.

The editor populates a<xavia:Item class=com.ende¬ca.infront.cartridge.model.LinkBuilder/> itemproperty. For more information, see "Adding a Link Builder."

Displays as a Media URL field, with an associated previewbox and Select and Clear buttons for launching the media

<xavia:Item>MediaEditor

editor or clearing the current URL. The content administrator


149Template Property and Editor Reference | Editor property mapping reference


Editor

can browse through media in the configured sourcerepository, and generate a link to a selected asset.

<xavia:List>RecordStratifica¬tionEditor Important: This editor is deprecated. Use the

BoostBuryRecordEditor instead.

Displays as two panes, Boosted Records and BuriedRecords, each with an Edit List button that launches themicrobrowser. The content administrator uses themicrobrowser to populate the lists of boosted and buriedrecords.

The editor populates two <xavia:List> properties, onefor boosted records and one for buried records.

Displays as a text area with a configurable formatting toolbar.The content administrator enters arbitrary string values andcan include markup to add text formatting and hyperlinks.

<String>RichTextEditor

Displays as a dropdown. The content administrator selectsa sort order from those configured in the editor.

<xavia:Item>SortEditor

The editor includes multiple <xavia:Itemclass="com.endeca.infront.navigation.mod¬el.SortOption"/> item properties that each specify anavailable sort option. For more information, see "Adding aSort editor."

Related LinksBasic content properties on page 151

Content items properties must be one of several basic types. All configuration models arecomposed of the same primitive property types.

Complex property editors on page 165This section describes editors that are designed for specific aspects of Endeca featureconfiguration.

Editor label configuration referenceAll editors share a set of common attributes that can be used to configure the appearance of the editorin Experience Manager.

When adding an editor to a template, you can configure its appearance by setting the following attributes:


Template Property and Editor Reference | Editor label configuration reference150

DescriptionAttribute

This attribute enables you to specify a more descriptive label for theeditor in Experience Manager. If no label is specified, the value of theassociated propertyName is used by default.

label

The position of the label text. Valid values are "left" (the default) and"top".

labelPosition

This attribute allows you to specify a descriptive label that appears belowthe editor.

bottomLabel

This attribute allows you to specify mouseover text for the editor.tooltip

Basic content propertiesContent items properties must be one of several basic types. All configuration models are composedof the same primitive property types.

The basic content property types are:• <String>

• <Boolean>

• <xavia:List>

• <xavia:Item>

The following example shows a several properties of various types.<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008" xmlns:editors="editors" xmlns:xavia="http://endeca.com/schema/xavia/2010" type="MainContent" id="ResultsList">



<ContentItem> <Name>Results List</Name> <Property name="boostStrata"> <xavia:List/> </Property> <Property name="buryStrata"> <xavia:List/> </Property> <Property name="sortOption"> <xavia:Item class="com.endeca.infront.navigation.model.SortOption">

<xavia:Property name="label">Most Sales</xavia:Property> <xavia:Property name="sorts"> <xavia:List> <xavia:Item class="com.endeca.infront.navigation.mod¬el.SortSpec"> <xavia:Property name="key">product.analytics.to¬tal_sales</xavia:Property> <xavia:Property name="descending">false</xavia:Prop¬erty> </xavia:Item>


151Template Property and Editor Reference | Basic content properties

</xavia:List> </xavia:Property> </xavia:Item> </Property> <Property name="relRank">  <String>nterms,maxfield,exact,static(product.analytics.conver¬sion_rate,descending)</String> </Property> <Property name="recordsPerPage"> <String>10</String> </Property> </ContentItem>

</ContentTemplate>

Adding a string propertyString properties are very flexible and can be used to specify information such as text to display on apage, URLs for banner images, or meta keywords for search engine optimization.

To add a string property to a template:

1. Insert a <String> element inside a <Property> element.2. Optionally, specify the default value for the property as the content of the <String> element.

The following example shows a variety of string properties:

<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008" xmlns:xavia="http://endeca.com/schema/xavia/2010" xmlns:editors="editors" type="SidebarContent" id="DimensionNavigation">

 <ContentItem> <Name>Dimension Navigation</Name> <Property name="dimensionName"> <String/> </Property> <Property name="dimensionId"> <String/> </Property> <Property name="sort"> <String>default</String> </Property> <Property name="showMoreLink"> <Boolean>false</Boolean> </Property> <Property name="moreLinkText"> <String>Show More Refinements...</String> </Property> <Property name="numRefinements"> <String>10</String> </Property> <Property name="maxNumRefinements"> <String>200</String> </Property>

 </ContentItem>


Template Property and Editor Reference | Basic content properties152

</ContentTemplate>

Adding a string editorYou add a string editor to enable configuration of string properties. The string editor displays in theExperience Manager interface as a text field or text area depending on the configuration.

String editors enable content administrators to supply arbitrary values for a string property. If you wantto constrain the input to a specific enumeration of values, use a choice editor.

To add a string editor to a template:

1. Insert an <StringEditor> element within <BasicContentItemEditor>.2. Specify label attributes and additional attributes for the editor:


Required. The name of the string property that this editor is associated with. Thisproperty must be declared in the same template as the string editor.

propertyName

If set to false, this attribute makes the property read-only so that the value ofthe property displays in the Content Details Panel in Experience Manager, but

enabled

cannot be edited. Set this to false only if you specify a default value in thedefinition of the string property. Editors are enabled by default.

The width in pixels of the text field presented in the Experience Manager interface.The default width is 100% and scales with the screen width.

width

Note: You cannot specify a percent value in your editor configuration.You must specify the editor width in pixels.

The height in pixels of the text field presented in the Experience Managerinterface. The default height for a single-row field is 24 pixels. Setting the valueto 34 pixels or higher creates a multiline text area with word wrap enabled.

height

The following example shows a variety of editing options for string properties:<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008" xmlns:editors="editors" type="ResultsPage" id="ThreeColumnNavigationPage">

<ContentItem> <Name>Three-Column Navigation Page</Name> <Property name="title"> <String>Discover Electronics</String> </Property> <Property name="metaKeywords"> <String>camera cameras electronics</String> </Property> <Property name="metaDescription"> <String>Endeca eBusiness reference application.</String> </Property>

<EditorPanel> <BasicContentItemEditor> <GroupLabel label="Page metadata"/> <editors:StringEditor propertyName="title" label="Title" en¬abled="true"/> <editors:StringEditor propertyName="metaKeywords" label="Meta keywords"

enabled="true" height="72"/> <editors:StringEditor propertyName="metaDescription" label="Meta de¬scription" enabled="true" height="72"/> </BasicContentItemEditor> </EditorPanel></ContentTemplate>

Note: Neither Experience Manager nor the Assembler applies HTML escaping to strings. Thisenables content administrators to specify HTML formatted text in Experience Manager and haveit rendered appropriately. If you intend to treat a string property as plain text, be sure to addHTML escaping to your application logic in order to avoid invalid characters andnon-standards-compliant HTML.

Adding a choice editorA choice editor enables the user to select from predefined string values for a property that are presentedin a drop-down list.

Choice editors affect the value of a string property. For example, you might use a choice editor toprovide sorting options for dimension values in a Guided Navigation cartridge:

To add a choice editor:

1. Insert an <editors:ChoiceEditor> element within <BasicContentItemEditor>.2. Specify additional attributes for the editor:


Required. The name of the string property that this editor is associated with.This property must be declared in the same template as the choice editor.

propertyName

If set to true, this attribute allows Experience Manager users to specifycustom string values. By default, choice editors are not editable.

editable



If set to false, the choice editor displays in Experience Manager but thevalue cannot be changed by the user. By default, choice editors are enabled.

enabled

Specifies a custom prompt. The default prompt is an empty string.prompt

If present, specifies optional help text to display in a tool tip window. Thedefault behavior is no tool tip.

tooltip

The width, in pixels, of the choice editor. By default, the width of the editoradjusts to fit the longest choice in the editor. Use this attribute if you wantto set a fixed width for the editor.

width

3. Specify one or more menu options for the choice editor by adding <choice> elements. <choice>takes the following attributes:


Required. The string value to assign to the associated property if this <choice>is selected.

value

This attribute allows you to specify a more descriptive label for this option in thedrop down list. If no label is specified, the value is used by default. You must either

label

specify a label for all of the choices or none of them. You cannot have labels forsome choices and not others.

Note: If you choose to make a choice editor editable (so that users can enterarbitrary strings), you should not use the label attribute for choices. Instead,the choice editor should display the raw value of the string so that usersentering custom values can see the expected format of the string property.

4. Optionally, set a default value in the corresponding <ContentItem> property.For example, to specify the default sort order for a dimension as the default choice for a choiceeditor with propertyName="sort":<Property name="relrank">  <String>nterms,maxfield,exact,static(product.analytics.conver¬sion_rate,descending)</String> </Property>

Note: Ensure that the default value for the property is one of the options defined for thechoice editor in a <choice> element.

The following example shows a choice editor configured with a default value. The selected value whenthe editor is first instantiated is nterms,maxfield,exact,static(product.analytics.con¬

version_rate,descending), which displays with the label "Margin Bias" in the drop-down menu.Content administrators can select a different sort order.<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008" xmlns:editors="editors" xmlns:xavia="http://endeca.com/schema/xavia/2010" type="MainContent" id="ResultsList">

 <ContentItem> <Name>Results List</Name>

 <Property name="relrank">  <String>nterms,maxfield,exact,static(product.analytics.conver¬sion_rate,descending)</String> </Property>


<EditorPanel> <BasicContentItemEditor>

 <GroupLabel label="Search Result Settings (apply when user provides search terms)"/> <editors:ChoiceEditor propertyName="relrank" label="Relevance ranking">

<choice label="Margin Bias" value="nterms,maxfield,exact,stat¬ic(product.analytics.conversion_rate,descending)" /> <choice label="Inventory Bias" value="nterms,maxfield,exact,stat¬ic(product.inventory.count,descending)" /> <choice label="First" value="first" /> <choice label="By Price (Static)" value="static(product.price)" /> <choice label="Frequency" value="freq" /> </editors:ChoiceEditor>

 </BasicContentItemEditor> </EditorPanel></ContentTemplate>

Adding a radio group editorA radio group editor is similar to the choice editor in that it enables the user to select from predefinedstring values for a property. The choices are presented as a set of radio button controls.

Although radio buttons are often used for binary choices such as yes/no, the radio group editor canbe used for any scenario where the user must specify exactly one value out of a number of options.In order to enable the more general use case, the radio group editor affects the value of a stringproperty.

To add a radio group editor:

1. Insert an <editors:RadioGroupEditor> element within <BasicContentItemEditor>.2. Specify label attributes and the additional attributes for the editor:

Required. The name of the string property that this editor is associatedwith. This property must be declared in the same template as the choiceeditor.

propertyName

If set to false, the radio group editor displays in Experience Manager butthe value cannot be changed by the user. By default, radio group editorsare enabled.

enabled

3. Specify one or more radio button options by adding <choice> elements. <choice> takes thefollowing attributes:


Required. The string value to assign to the associated property if this<choice> is selected.

value

This attribute allows you to specify a more descriptive label for the radiobutton associated with this option. If no label is specified, the value is usedby default.

label

4. Optionally, set a default value in the corresponding <ContentItem> property.For example, to specify the default value for a radio group editor with propertyName="showDis¬abledRefinements": <Property name="showDisabledRefinements"> <String>false</String> </Property>

Note: Ensure that the default value for the property is one of the options defined for theeditor in a <choice> element.

The following example shows a radio group editor configured with a default value. The selected valuewhen the editor is first instantiated is false, which displays with the label "No."<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008" xmlns:xavia="http://endeca.com/schema/xavia/2010" xmlns:editors="editors" type="SidebarItem" id="ExampleRadioGroupCartridge">

 <ContentItem>

 <Property name="showDisabledRefinements"> <String>false</String> </Property>

 </ContentItem> <EditorPanel> <BasicContentItemEditor>

 <editors:RadioGroupEditor propertyName="showDisabledRefinements"

label="Show 'Disabled Refinements'" enabled="true"> <choice label="Yes" value="true"/> <choice label="No" value="false"/> </editors:RadioGroupEditor>


About numeric propertiesNumeric properties should be specified as string properties in the template.

Properties that are expected to have numeric values can be associated with editors that are designedto work with numbers. These editors guarantee that the property is assigned a numeric value.

Adding a numeric stepperA numeric stepper enables content administrators to select a numeric value from a set of possiblevalues by stepping through values or typing into an input field.

The numeric stepper provides a single-line input text field and a pair of arrow buttons for steppingthrough values. If a user enters number that is not a multiple of the stepSize property or is not in therange between the maximum and minimum properties, this property is set to the nearest valid value.

To add a numeric stepper to a template:

1. Insert an <editors:NumericStepperEditor> element within <BasicContentItemEditor>.2. Specify additional attributes for the editor:


Required. The name of the string property that this editor is associated with.This property must be declared in the same template as the string editor.

propertyName

The width, in pixels, of the editor. The default width is 60.width

The height, in pixels, of the editor. The default height is 24.height

The minimum value of the property bound to this editor. The minValuecan be any number, including a fractional value. The default minimum valueis 0.

minValue

The maximum value of the property bound to this editor. The maxValuecan be any number, including a fractional value. The default maximum valueis 10.

maxValue

The increment by which the property value is increased or decreased whena user clicks on the up or down arrows. The value must be a multiple ofthis number. The default step size is 1.

stepSize

The following example shows the configuration for a numeric stepper:<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008" xmlns:xavia="http://endeca.com/schema/xavia/2010" xmlns:editors="editors" type="SidebarContent" id="DimensionNavigation">



<ContentItem> <Name>Dimension Navigation</Name>

 <Property name="numRefinements"> <String>10</String> </Property> <Property name="maxNumRefinements"> <String>200</String> </Property>


 <editors:NumericStepperEditor propertyName="numRefinements" label="Max. Refinements" maxValue="10000" enabled="true"/>

 <editors:NumericStepperEditor propertyName="maxNumRefinements"

label="'More' Max. Refinements" maxValue="100000" en¬abled="true"/> </BasicContentItemEditor> </EditorPanel></ContentTemplate>

Adding a sliderA slider enables content administrators to select a numeric value by moving a slider between predefinedendpoint values.

The current value of the slider is determined by the relative location of the thumb between the endpoints of the slider, corresponding to the slider's minimum and maximum values.

To add a slider to a template:

1. Insert an <editors:SliderEditor> element within <BasicContentItemEditor>.2. Specify label attributes and additional attributes for the editor:


Required. The name of the string property that this editor is associated with.This property must be declared in the same template as the string editor.

propertyName

The width, in pixels, of the editor. The default width is 160.width

The height, in pixels, of the editor. The default height is 36.height

The default position of the slider thumb. By default, the thumb is set to 0.default

The minimum value of the property bound to this editor. The minValue canbe any number, including a fractional value. The default minimum value is0.

minValue

The maximum value of the property bound to this editor. The maxValuecan be any number, including a fractional value. The default maximum valueis 10.

maxValue

Specifies the increment value of the slider thumb as the user moves thethumb. A value of 0 means that the slider moves continuously between theminimum and maximum values. The default value is 0.

snapInterval

The spacing of the tick marks. A value of 0 displays no tick marks. Thedefault value is 0.

tickInterval

Number of decimal places to use for the property value and data tip text. Avalue of 0 means all values are rounded to the nearest integer. The defaultvalue is 0.

precision

An array of strings to use for the slider labels. These labels display at thebeginning and end of the track and, if there are more than two values, spaced

labels

evenly between the two ends. By default, the beginning and end of the slidertrack are labeled in Experience Manager with the minimum and maximumvalues.

The following example shows the configuration for a slider:<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008" xmlns:editors="editors" type="SidebarItem" id="ExampleSliderCar¬tridge">

<ContentItem>

<Property name="numRefinements"> <String>10</String> </Property> </ContentItem>


 <editors:SliderEditor propertyName="numRefinements" label="Number of refinements" minValue="10" maxValue="30" snapInterval="5" tickInterval="5" labels="10,15,20,25,30"/> </BasicContentItemEditor> </EditorPanel></ContentTemplate>

Adding a Boolean propertyBoolean properties represent a true or false value and can be used to enable or disable features inyour application.

To add a Boolean property to a template:

1. Insert a <Boolean> element inside a <Property> element.2. Optionally, you can specify the default value for the property.

<Property name="eligibleFreeShipping"> <Boolean>true</Boolean> </Property>

Any value other than the string "true" (case insensitive) defaults to a value of false.

The following example shows the configuration of a Boolean property:

<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008" xmlns:editors="editors" type="HeaderContent" id="SearchBox">

 <ContentItem> <Name>Search Box</Name> <Property name="autoSuggestEnabled"> <Boolean>false</Boolean> </Property>



Adding a Boolean editorA Boolean editor provides a checkbox for Experience Manager users to specify the value of a Booleanproperty.

To add a Boolean editor:

1. Insert a <editors:BooleanEditor> element within <BasicContentItemEditor>.2. Specify additional attributes for the editor:


Required. The name of the Boolean property that this editor is associatedwith. This property must be declared in the same template as the Booleaneditor.

propertyName

If set to false, the checkbox displays in Experience Manager but thevalue cannot be changed by the user. By default, checkboxes are enabled.

enabled

The following example illustrates a checkbox for specifying whether auto-suggest search results shouldbe enabled, with a default value of false:<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008" xmlns:editors="editors" type="HeaderContent" id="SearchBox">

 <ContentItem> <Name>Search Box</Name> <Property name="autoSuggestEnabled"> <Boolean>false</Boolean> </Property>

 </ContentItem> <EditorPanel> <BasicContentItemEditor> <GroupLabel label="Auto-Suggest Configuration"/> <editors:BooleanEditor propertyName="autoSuggestEnabled" label="Enable Auto-Suggest" enabled="true"/>

</BasicContentItemEditor> </EditorPanel></ContentTemplate>

Adding a list propertyA property can consist of an ordered list of strings, Booleans, items, or other lists.

Because lists can be used for a variety of purposes, Oracle Endeca Guided Search does not includeany generic editors for working with lists. However, editors intended for specific purposes may storetheir values in list properties.

To add a list property to a template:

1. Insert a <xavia:List> element inside a <Property> element.2. Optionally, specify a default value by inserting either <String>, <Boolean>, <xavia:List>, or

<xavia:Item> elements.

Following is an example of a template that uses lists both with and without default values:<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008" xmlns:editors="editors" xmlns:xavia="http://endeca.com/schema/xavia/2010" type="MainContent" id="ResultsList">

<ContentItem> <Name>Results List</Name> <Property name="boostStrata"> <xavia:List/> </Property> <Property name="buryStrata"> <xavia:List/> </Property> <Property name="sortOption"> <xavia:Item class="com.endeca.infront.navigation.model.SortOption"> <xavia:Property name="label">Most Sales</xavia:Property> <xavia:Property name="sorts"> <xavia:List> <xavia:Item class="com.endeca.infront.navigation.model.SortSpec">

<xavia:Property name="key">product.analytics.to¬tal_sales</xavia:Property> <xavia:Property name="ascending">true</xavia:Property> </xavia:Item> </xavia:List> </xavia:Property> </xavia:Item> </Property>

Adding an item propertyA property can consist of a collection of properties (key-value pairs) of any valid type.

Because item properties can be used for a variety of purposes, InFront does not include any genericeditors for working with items. However, editors intended for specific purposes may store their valuesin item properties.

To add an item property to a template:

1. Insert a <xavia:Item> element inside a <Property> element.2. Specify the class attribute with the fully qualified class name of the configuration model class that

corresponding to this item property.3. Optionally, specify a default value by inserting a <xavia:Property> of type <String>,

<Boolean>, <xavia:List>, or <xavia:Item>. (A <Property>with no type specified is treatedas a string by default.)

Note: Properties defined within <xavia:Item> must declare the Xavia namespace (i.e.,<xavia:Property> instead of <Property>.

Following is an example of a template that uses an item with a default value:<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008" xmlns:editors="editors" xmlns:xavia="http://endeca.com/schema/xavia/2010" type="MainContent" id="ResultsList">

<ContentItem> <Name>Results List</Name>

 <Property name="sortOption"> <xavia:Item class="com.endeca.infront.navigation.model.SortOption"> <xavia:Property name="label">Most Sales</xavia:Property> <xavia:Property name="sorts"> <xavia:List> <xavia:Item class="com.endeca.infront.navigation.model.SortSpec">

Following is an example of a template that uses an item without a default value:<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008" xmlns:editors="editors" xmlns:xavia="http://endeca.com/schema/xavia/2010" type="SidebarContent" id="RecordSpotlight">

 <ContentItem>

 <Property name="recordSelection"> <xavia:Item class="com.endeca.infront.cartridge.RecordSpotlight¬Selection" /> </Property>



Adding a group labelIn the Experience Manager interface, group labels can serve as a visual cue that several propertiesare related.

Group labels are only used to provide additional context in the editing interface of Experience Managerand do not affect rendering in the front-end application. Group labels are optional.

One use of group labels is to give the content administrator information about properties that theyneed to configure the cartridge. For example, if a template defines properties that are required in orderto render the content properly, you can indicate these with a descriptive group label so that the contentadministrator can easily identify the required fields in Experience Manager.

The editor panel in Experience Manager includes a default heading of "Section settings." This headingincludes the required Name field and the read-only type of a template, as well as any properties thatare defined before the first group label.

To add a group label to the editor panel:

Insert the <GroupLabel> element inside <BasicContentItemEditor> as in the followingexample:<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008" xmlns:editors="editors" xmlns:xavia="http://endeca.com/schema/xavia/2010" type="SidebarContent" id="RecordSpotlight">

 <EditorPanel> <BasicContentItemEditor> <GroupLabel label="Define Spotlight"/> <editors:StringEditor propertyName="title" label="Spotlight Title" enabled="true"/> <editors:StringEditor propertyName="maxNumRecords" label="Max Number Of Records" enabled="false"/> <editors:RecordListEditor propertyName="recordSelection" la¬


Template Property and Editor Reference | Adding a group label164

bel="Spotlight Records"> <PreviewProperty name="product.name"/> </editors:RecordListEditor> <editors:StringEditor propertyName="seeAllLink" label="See All Link" enabled="true"/> </BasicContentItemEditor> </EditorPanel></ContentTemplate>

<GroupLabel> is an empty tag that allows you to specify the label text with the label attribute.

Complex property editorsThis section describes editors that are designed for specific aspects of Endeca feature configuration.

About the microbrowserThe microbrowser is used in several editors in the core cartridges to enable a content administratorto specify a set of records. It is deprecated in this release; use the Select Records dialog instead.

Important: The microbrowser is deprecated. Use the Select Records dialog instead.

The microbrowser is a lightweight search and Guided Navigation application that enables a contentadministrator to browse to a particular location in the data set (which may include search terms,dimension refinements, or a combination of both). The content administrator can then do one of twothings:

• Save the current filter state to designate a dynamic set of records.• Select specific records from that filter state (or other filter states) to designate a set of specific

featured records.An instance of a microbrowser is usually bound to a list property, which contains items that representeither refinements or record IDs.

The microbrowser communicates with the MDEX Engine to retrieve search and navigation results.

Note: In order to enable the microbrowser, ensure that you have enabled communicationbetween Experience Manager and the MDEX Engine. For instructions, see "Communicatingwith the MDEX Engine" in the Tools and Frameworks Installation Guide.

Data service configuration referenceThe Discover Electronics reference application makes MDEX Engine configuration information availablethrough a data service. The data service configuration file is used by editors that need to query theauthoring MDEX Engine used in the reference application, such as those that use the microbrowser.

Important: The microbrowser is deprecated. Use the Select Records dialog instead.

The data service configuration file, <appdir>\config\editors_config\services\dataservice.json, is shown below:{ "jcr:primaryType": "endeca:unstructured",


165Template Property and Editor Reference | Complex property editors

"host": "myhost.mydomain.com", "port": "15002", "recordSpecName": "common.id", "aggregationKey": "product.code", "recordFilter": "", "wildcardSearchEnabled": false, "recordNameField": "", "fields": { "product.id": "", "product.name": "plain", "product.price": "currency", "product.short_desc": "" }}

It specifies the following:

ValueKey

The hostname or IP address of your MDEX Engine server. By default, this ispopulated with the same host as the authoring MDEX Engine when you deploy

host

the Discover Electronics reference application and run theinitialize_services script.

The port that the MDEX Engine server listens on. By default, this is populatedwith the same port as the authoring MDEX Engine.

port

The dimension used as the record specifier. This must be a unique identifier.recordSpecName

Optional. Enables aggregated records mode in the microbrowser, using thespecified property or dimension as the aggregation key when displaying and

aggregationKey

sorting records. All records with the same value in the selected dimension orproperty are treated as a single record.

Optional. The property used to filter records for record boost and bury.recordFilter

Optional. Wildcard search is enabled by default. If your configuration does notindex dimensions by wildcard index, you must explicitly set this property to false.

wildcard¬SearchEnabled

Optional. The property that should be used to represent the name of a record.recordName¬Field

Each key in the array of key/value pairs specifies a property or dimension todisplay as a column in the microbrowser. Optionally, you may specify a formattingvalue from among the following:

fields

• plain — no formatting. Used as the default if no format value is present.• currency — adds a dollar ($) symbol before the value.• integer— removes the decimal point and any trailing digits, if present. This

setting does not round the integer value.• html — attempts to handle markup tags within the content returned from the

MDEX Engine.


Template Property and Editor Reference | Complex property editors166

Running <app dir>\control\set_editors_config pushes changes to the Discover Electronicsreference application and updates all editors that rely on the data service.

About the Select Records dialogThe Select Records dialog is used in several editors in the core cartridges to enable a contentadministrator to specify a set of records.

The Select Records dialog is a lightweight search and Guided Navigation application that enables acontent administrator to browse to a particular location in the data set (which may include search terms,dimension refinements, or a combination of both). The content administrator can then do one of twothings:

• Save the current filter state to designate a dynamic set of records.• Select specific records from that filter state (or other filter states) to designate a set of specific

featured records.

An instance of a Select Records dialog is usually bound to a <List> property in a cartridge template,which contains <Item> properties that represent either dimension refinements or record IDs. Thedialog communicates with the MDEX Engine to retrieve search and navigation results.

Note: In order to enable theSelect Records dialog, ensure that you have enabled communicationbetween Experience Manager and the MDEX Engine. For instructions, see "Communicatingwith the MDEX Engine" in the Tools and Frameworks Installation Guide.

The following editors launch the Select Records dialog:• Link Builder editor• Boost-Bury Record editor• Spotlight Selection editor

Select Records data service configuration referenceTo make MDEX Engine configuration information available to editors, you must configure a dataservice. In the Discover Electronics reference application, the data service configuration file is usedby editors that need to query the authoring MDEX Engine used in the reference application, such asthose that use the Select Records dialog.

The configuration file, <appdir>\config\editors_config\services\endecaBrowserService.json, is shown below:{ "host": "myhost.mydomain.com", "port": "15002", "recSpecProp": "common.id", "recAggregationKey": "product.code", "recFilter": "", "recImgUrlProp" : "product.img_url_thumbnail", "recDisplayProps": [ "product.name", "product.price", "product.short_de¬sc" ], "textSearchKey": "All", "textSearchMatchMode" : "ALLPARTIAL"}

It specifies the following:



ValueKey

The hostname or IP address of your MDEX Engine server. By default, this ispopulated with the same host as the authoring MDEX Engine when you deploy

host

the Discover Electronics reference application and run theinitialize_services script.

The port that the MDEX Engine server listens on. By default, this is populatedwith the same port as the authoring MDEX Engine.

port

The dimension used as the record specifier. This must be a unique identifier.recSpecProp

Optional. Enables aggregated records mode in the Select Records dialog usingthe specified property or dimension as the aggregation key when displaying and

recAggregation¬Key

sorting records. All records with the same value in the selected dimension orproperty are treated as a single record.

Optional. The property used to filter records for record boost and bury.recFilter

Optional. The property used to retrieve the URL for the record thumbnail image.recImgUrlProp

An array of record properties to display in the dialog.recDis¬playProps

Optional. Specifies the search key to apply to text searches in the Select Recordsdialog.

textSearchKey

Optional. Specifies the match mode to apply to text searches in the SelectRecords dialog.

textSearch¬MatchMode

You can modify these values as necessary. Running <app dir>\control\set_editors_configpushes changes to the Discover Electronics reference application and updates all editors that rely onthe data service.

About the Dynamic Slot editorThe Dynamic Slot editor enables the content administrator to configure a section of an applicationpage at query time by specifying a content collection and number of content items with which to populatethat section.

The dynamic slot editor takes a single property, zoneType. When the content administrator edits thiscartridge in Experience Manager, the editor queries the Endeca Configuration Repository for contentcollections of the appropriate type. The evaluation limit of the selected collection determines themaximum possible evaluation limit for the dynamic slot, though the slot may be configured to returnfewer content items than this maximum.



Creating a cartridge template with a dynamic slotYou should configure a separate cartridge template for each template type into which you wish toinclude a dynamic slot.

To create a cartridge template with a dynamic slot:

1. Insert a ContentItem that includes a contentCollection and ruleLimit property, as in thefollowing example:<ContentItem> <Name>Search Box Slot</Name> <Property name="contentCollection"/> <Property name="ruleLimit"></Property></ContentItem>

2. Within the ruleLimit property, insert a String element that specifies the maximum number ofmatching content items to return for a query:<ContentItem> <Name>Search Box Slot</Name> <Property name="contentCollection"/>

<Property name="ruleLimit"><String>1</String></Property></ContentItem>

3. Insert a corresponding<editors:DynamicSlotEditor>element within<BasicContentItemEd¬itor>.

4. Specify the zoneType attribute for the editor. This value must match the id attribute for thecorresponding template type:<EditorPanel> <BasicContentItemEditor> <editors:DynamicSlotEditor zoneType="SearchBox"/> </BasicContentItemEditor></EditorPanel>

5. Upload the template to your application:a) Navigate to your <app dir>\control directory.

For the Discover Electronics reference application, this isC:\Endeca\apps\Discover\control on Windows, or/usr/local/endeca/apps/discover/control on UNIX.

b) Run the set_templates batch or shell script.

Note: You must configure a cartridge handler for your template in order to use it inExperience Manager.

The following shows the sample template in the Discover Electronics application for a dynamic slotSearch Box cartridge. Note that although the content type for this cartridge is HeaderContent, thezone type for items in the Search Box Content collection is SearchBox, which is a more specificconstraint on what content items can populated the dynamic slot:<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008" xmlns:editors="editors"type="HeaderContent"

id="SearchBoxSlot"><ContentItem>

<Name>Search Box Slot</Name> <Property name="contentCollection"/> <Property name="ruleLimit"><String>1</String></Property> </ContentItem>


<editors:DynamicSlotEditor zoneType="SearchBox"/> </BasicContentItemEditor> </EditorPanel></ContentTemplate>

If the content administrator wishes to change the specified collection, they are restricted to collectionsof the appropriate zoneType, in this case, SearchBox.

You must specify a cartridge handler for each cartridge template that you configure as a dynamic slot.

Specifying a cartridge handler for a dynamic slot templateAll dynamic slot cartridges can share the same cartridge handler, but each unique cartridge must beconfigured separately.

Once you have created a cartridge template that uses a dynamic slot, you must specify a cartridgehandler for that template. Your cartridge handler should inherit the CartridgeHandler_ContentSlothandler.

The response model for a dynamic slot cartridge is a ContentItem that includes a contents propertycontaining a list of content items. The ContentItem also returns its contentCollection andruleLimit.

The examples below use the cartridge handler configuration in the Assembler context file of the DiscoverElectronics application, located in%ENDECA_TOOLS_ROOT%\reference\discover-electronics-authoring\WEB-INF\assembler-context.xml.

To add a cartridge handler for your dynamic slot template:

1. Stop the Endeca Tools Service.2. Open your Spring context configuration file.

In the Discover Electronics reference application, this is located in%ENDECA_TOOLS_ROOT%\reference\discover-electronics-authoring\WEB-INF\assembler-context.xml.

3. Locate the CartridgeHandler_ContentSlot bean:<bean id="CartridgeHandler_ContentSlot" class="com.endeca.infront.car¬tridge.ContentSlotHandler" scope="prototype"> <property name="contentManager" ref="cartridgeManager" /></bean>

4. Add a new CartridgeHandler bean for your dynamic slot cartridge.

Set the id attribute to correspond to the ID of your dynamic slot cartridge template, and set theparent attribute to the CartridgeHandler_ContentSlot handler:<bean id="CartridgeHandler_MyPageSlot" parent="CartridgeHandler_Con¬tentSlot" scope="prototype"/>

5. Save and close the file.6. Start the Endeca Tools Service.

Adding a Link BuilderThe Link Builder editor allows the content administrator to specify a link to a static page, a singleselected record, or a navigation state.

The Link Builder uses the Select Records dialog to enable the content administrator to browse to asingle record or a particular navigation state in the data set (which may include search terms, dimensionrefinements, or a combination of both). Alternately, the Link Builder also supports entering an absoluteURL to a static resource.

To add a Link Builder to a template:

1. Insert an Item property named link, of class com.endeca.infront.cartridge.mod¬el.LinkBuilder, as in the following example:<Property name="link"> <Item class="com.endeca.infront.cartridge.model.LinkBuilder" xmlns="http://endeca.com/schema/xavia/2010"> </Item></Property>

2. Within the Item property, insert three empty Property elements named path, linkType, andqueryString:<Property name="link"> <Item class="com.endeca.infront.cartridge.model.LinkBuilder" xmlns="http://endeca.com/schema/xavia/2010">

<Property name="path"></Property> <Property name="linkType"></Property> <Property name="queryString"></Property> </Item></Property>

These properties are populated by the Select Records dialog and processed by the cartridge handlerinto an action string.

3. Insert a corresponding<editors:LinkBuilderEditor>element within<BasicContentItemEd¬itor>.

4. Specify the propertyName attribute for the editor:<editors:LinkBuilderEditor propertyName="link" enabled="true"/>

5. Specify any additional label attributes for the editor:<editors:LinkBuilderEditor propertyName="link" label="Link Destination" enabled="true"/>



The following shows an example of a template that includes a link builder editor:<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008" xmlns:editors="editors" xmlns:xavia="http://endeca.com/schema/xavia/2010" type="MainContent" id="MediaBanner">

 <ContentItem> <Name>Media banner</Name>

<Property name="link">

<Item class="com.endeca.infront.cartridge.model.LinkBuilder" xmlns="http://endeca.com/schema/xavia/2010"> <Property name="path"></Property> <Property name="linkType"></Property> <Property name="queryString"></Property> </Item> </Property>



 <GroupLabel label="Link Settings"/>

<editors:LinkBuilderEditor propertyName="link" label="Link Desti¬nation" enabled="true"/>


About configuring the Link BuilderThe Link Builder must be configured with a path to a data service in order to display the Select Recordsdialog.

Below is the configuration for the Link Builder in the editor configuration file for the Discover Electronicsreference application, located at <app dir>\config\editors_config\editors.xml:<?xml version="1.0" encoding="UTF-8"?><EditorConfig xmlns="http://endeca.com/schema/editor-config/2010"> <EditorModule url="/ifcr/tools/pbx/modules/editors.swf">

<Editor name="editors:LinkBuilderEditor">

<EditorConfig resourcePath="/configuration/tools/xmgr/services/en¬decaBrowserService.json" /> </Editor>

 </EditorModule> <GlobalEditorConfig></GlobalEditorConfig></EditorConfig>

To publish and view changes to the editor configuration file, run the <appdir>\control\set_editors_config script and clear your browser cache.

Deprecated configuration

The Link Builder formerly supported multiple nested configuration properties that applied to all instancesof the editor in an application. This configuration model is deprecated in the current release:

DescriptionProperty

The hostname or IP address of the MDEX Engine server to use for the SelectRecords dialog.

host

The port on which the specified MDEX Engine server listens.port

The name of the property that serves as the record spec in the data set. Thismust be a unique identifier.

spec

The name of a property, dimension, or search interface against which searchesare performed.

searchKey

The rollup key (used for aggregated records) to apply to all queries made viathis MDEX.

rollupKey

The match mode to use for text searches. Valid values for this property followthe syntax of URL parameters for search mode, without the mode+matchprefix.

matchMode

The property that specifies the location of the thumbnail image for a record.imgUrlProperty

A comma separated list of record properties that display for each record returnedby the content administrator's search and navigation state in the link builderAssembler application.

properties

Specifying a path to a data service overrides these settings.

Related LinksSelect Records data service configuration reference on page 167

To make MDEX Engine configuration information available to editors, you must configure adata service. In the Discover Electronics reference application, the data service configurationfile is used by editors that need to query the authoring MDEX Engine used in the referenceapplication, such as those that use the Select Records dialog.

About the Select Records dialog on page 167The Select Records dialog is used in several editors in the core cartridges to enable a contentadministrator to specify a set of records.

About the Media editorThe Media editor allows the content administrator to select and link to media assets stored in a contentrepository.

The media editor consists of an Experience Manager editor and a lightweight Web application thatenables the content administrator to browse and navigate across a set of media assets in order tomore easily find specific files.

The default Discover Electronics reference application stores media directly in the Endeca ConfigurationRepository and uses a built-in asset browser to present these assets to the content administrator. Youmay also initialize an MDEX Engine to index media asset metadata and URIs as records, making themavailable for Guided Navigation in an enhanced Media Browser.



Note: The configuration repository provides an acceptable store for media files when used forpreview purposes in an authoring environment, but Oracle recommends serving media assetsfrom a media or content delivery server for production environments.

About the Media BrowserThe default asset browser for the Media editor can only be configured to browse media assets in theEndeca Configuration Repository. If you are using another system for managing media assets, youmust stand up a corresponding media MDEX Engine and enable the Media Browser in the editorconfiguration file.

Adding a Media editorA Media editor allows a content administrator to link media into a cartridge. It can be combined withthe Link Builder in order to create images that link to destinations in your application, such as thoseused in site banners.

To add a Media editor to a template:

1. Insert an Item property named media, of class com.endeca.infront.cartridge.model.Me¬diaObject, as in the following example:<Property name="media"> <Item class="com.endeca.infront.cartridge.model.MediaObject" xmlns="http://endeca.com/schema/xavia/2010"> </Item></Property>

2. Within the Item property, insert six empty Property elements:

• uri

• contentWidth

• contentHeight

• contentBytes

• contentType

• contentSrcKey

<Property name="media"> <Item class="com.endeca.infront.cartridge.model.MediaObject" xmlns="http://endeca.com/schema/xavia/2010">

<Property name="uri"></Property> <Property name="contentWidth"></Property> <Property name="contentHeight"></Property> <Property name="contentBytes"></Property> <Property name="contentType"></Property> <Property name="contentSrcKey"></Property> </Item></Property>

These properties are populated by the Select Records dialog and processed by the cartridgehandler.

3. Insert a corresponding <editors:MediaEditor> element within <BasicContentItemEditor>.4. Specify the propertyName attribute for the editor:

<editors:MediaEditor propertyName="media" enabled="true"/>



5. Specify any additional label attributes for the editor:<editors:MediaEditor propertyName="media" label="Media Url" en¬abled="true"/>

The following shows an example of a template that includes a media editor as part of a media bannercartridge:<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008" xmlns:editors="editors" xmlns:xavia="http://endeca.com/schema/xavia/2010" type="MainContent" id="MediaBanner">

<ContentItem> <Name>Media banner</Name>

 <Property name="media"> <Item class="com.endeca.infront.cartridge.model.MediaObject" xmlns="http://endeca.com/schema/xavia/2010"> <Property name="uri">/</Property> <Property name="contentWidth"></Property> <Property name="contentHeight"></Property> <Property name="contentBytes"></Property> <Property name="contentType"></Property> <Property name="contentSrcKey"></Property> </Item> </Property> </ContentItem>


 <GroupLabel label="Media"/> <editors:MediaEditor propertyName="media" label="Media Url" en¬abled="true"/> </BasicContentItemEditor> </EditorPanel></ContentTemplate>

In order to use the Media editor, if you are using the Endeca Configuration Repository as your mediastore, you must upload any media files to the repository. If you are using an external digital assetmanagement system with a corresponding MDEX Engine, the matching Endeca application must beconfigured and running and the Media Browser must be enabled.

Related LinksUploading media to the Endeca Configuration Repository on page 178

The set_media script uploads any media assets in your application's local config\mediadirectory to the Endeca Configuration Repository.

About Media editor configurationYou can specify allowable media formats in the editor configuration file. You can also enable or disablethe Media Browser, and specify the MDEX Engine that it should query for media records.

The Discover Electronics reference application uses the Endeca Configuration Repository to storemedia and accesses these resources through a default asset browser, rather than relying on the MediaBrowser and an accompanying media MDEX Engine.

Below is the configuration for the Media editor in the editor configuration file, located at <appdir>\config\editors_config\editors.xml:<?xml version="1.0" encoding="UTF-8"?><EditorConfig xmlns="http://endeca.com/schema/editor-config/2010"> <EditorModule url="/ifcr/tools/pbx/modules/editors.swf">

 <Editor name="editors:MediaEditor"> <EditorConfig> <useMediaBrowser>false</useMediaBrowser> <mediaRoots> <default>http://myhost.mydomain.com:8006/ifcr/sites/Dis¬cover/media/</default> <IFCRSource>http://myhost.mydo¬main.com:8006/ifcr/sites/Discover/media/</IFCRSource> </mediaRoots> <mdexPort>17000</mdexPort> <mdexHost>myhost.mydomain.com</mdexHost> <videoFormats>flv|f4v|3pg|mov|mp4</videoFormats> <imageFormats>jpg|jpeg|png|gif</imageFormats> <mediaURI>/ifcr/sites/Discover/media/</mediaURI> </EditorConfig> </Editor>

 </EditorModule> <GlobalEditorConfig></GlobalEditorConfig></EditorConfig>

This sets the following properties across all instances of the media editor in the application:

DescriptionProperty

This property enables or disables the media browser. By default, it is set tofalse.

useMediaBrowser

This property specifies the absolute URLs to available media repositories. Itincludes a nested default property that points to the Endeca Configuration

mediaRoot

Repository, and an additional property for each repository indexed by the mediaMDEX Engine. For more information, see "About resolving media paths incontent items."

The absolute URL to the Endeca Configuration Repository, used by the defaultasset browser. The specified host and port should match those used by EndecaWorkbench.

default

The absolute URL to the media repository used by the Media Browser. Theproperty name is the same as that of the associated CAS crawl name used bythe media MDEX Engine.

IFCRSource

For applications using the Media Browser, this is the hostname or IP addressof the media MDEX Engine server.

mdexPort

For applications using the Media Browser, this is the port on which the specifiedmedia MDEX Engine server listens.

mdexHost

A pipe-delineated list of valid video formats. Any videos not matching a listedformat do not display in either the default asset browser or Media Browser.

videoFormats

A pipe-delineated list of valid image formats. Any images not matching a listedformat do not display in either the default asset browser or Media Browser.

imageFormats

DescriptionProperty

The location of the media node within the Endeca Configuration Repository.This is only used by the default asset browser.

mediaURI

Note: The default list of video and image formats includes only those that are supported by theincluded renderers for the Discover Electronics reference application. If you wish to extend thislist for your own application, ensure that your cartridge renderers can handle additional formats,and that your application includes logic for displaying them.

Related LinksMedia MDEX Engine schema definition on page 134

In order for the Media Browser in Experience Manager to have sufficient information forforming content XML, any media MDEX Engine that you configure must define specificproperties and dimensions.

Enabling the Media BrowserThe default browser for the Media editor can only be configured to browse media assets in the EndecaConfiguration Repository. If you are serving media assets from an external content source, you mustenable the Media Browser and configure it to use your media MDEX Engine.

You can enable and configure the Media Browser by modifying the editor configuration file for yourapplication.

To enable the Media Browser in the Media editor:

1. Navigate to the editor configuration file at <app dir>\config\editors_config\editors.xml.2. Locate the <EditorConfig> element for the Media editor:

<Editor name="editors:MediaEditor"> <EditorConfig> <useMediaBrowser>false</useMediaBrowser> <mediaRoots> <default>http://myhost.mydomain.com:8006/ifcr/sites/Discov¬er/media/</default> <IFCRSource>http://myhost.mydomain.com:8006/ifcr/sites/Dis¬cover/media/</IFCRSource> </mediaRoots> <mdexPort>17000</mdexPort> <mdexHost>mymediahost.mydomain.com</mdexHost> <videoFormats>flv|f4v|3pg|mov|mp4</videoFormats> <imageFormats>jpg|jpeg|png|gif</imageFormats> <mediaURI>/ifcr/sites/Discover/media/</mediaURI>

</EditorConfig></Editor>

3. Within the <EditorConfig> element, change the value of the <useMediaBrowser> propertyto true:<useMediaBrowser>true</useMediaBrowser>

4. Include a content source element under <mediaRoots>that points to your media host.The element name is a unique key that identifies your media host and corresponds to the value ofthe media.repository_id property assigned to each record. For example, in the CAS crawl



configuration for the reference data application, each record is assigned a media.repository_idproperty with a value of IFCRSource:<mediaRoots> <default>http://myhost.mydomain.com:8006/ifcr/sites/Discover/media/</de¬fault>

<IFCRSource>http://myhost.mydomain.com:8006/ifcr/sites/Discover/me¬dia/</IFCRSource></mediaRoots>

Note: The <default> value is only used by the default asset browser. For more information,see "About Media editor configuration" and "Media MDEX Engine schema definition."

5. Modify the <mdexPort> and <mdexHost> elements to point to the host and port of the MDEXEngine backing your media host.

6. Save and close the file.7. Navigate to the <app dir>\control directory.8. Run the set_editors_config script to publish your changes to the Endeca Configuration

Repository.

Related LinksUsing an MDEX Engine to Manage Media Assets on page 129

If you are storing media resources in an independent content store, you can set up an MDEXEngine where records represent media assets and include asset metadata and URIs. Storingthis information as records enables Guided Navigation in the Experience Manager MediaBrowser, allowing content administrators to easily navigate across resources when selectingmedia assets for a content item.

Media MDEX Engine schema definition on page 134In order for the Media Browser in Experience Manager to have sufficient information forforming content XML, any media MDEX Engine that you configure must define specificproperties and dimensions.

Uploading media to the Endeca Configuration RepositoryThe set_media script uploads any media assets in your application's local config\media directoryto the Endeca Configuration Repository.

These steps are based on local copies of your files being up to date and located in the <appdir>\config\media directory.

To upload images to the Endeca Configuration Repository:

1. Confirm that local copies of the images you wish to upload have been copied to the <appdir>\config\media directory, for example, C:\Endeca\apps\Discover\config\media.

2. From a command prompt, navigate to the <app dir>\control directory, for example,C:\Endeca\apps\Discover\control.

3. Run the set_media batch or shell script.This script uploads media assets to the /ifcr/sites/<App_Name>/media node in the EndecaConfiguration Repository, where they become available to the Media editor.

4. To verify that your media assets are available:a) Log in to Workbench.b) Open Experience Manager.c) Select a cartridge that includes the Media editor.



In the Discover Electronics reference application, navigate to Web > Web Browse Pages >Category - Camerasand select the Media banner template.

d) Click the Select button to launch the Media editor and confirm that your media assets display.

About resolving media paths in content itemsLinks to media assets are resolved in the Media editor by combining configuration in the editorconfiguration file with the media.path property on the selected record. At runtime, these links areresolved against the media sources specified in the Assembler context file.

About media root elements

You identify authoring content sources as nested elements within the <mediaRoots> element in theeditor configuration file. The name of each such element corresponds to the value of the media.repos¬itory_id property assigned to each record in your media MDEX Engine. The value of each elementidentifies the root location of the authoring content source.

When a content administrator opens the Media Browser in Experience Manager, media assets areretrieved for preview by appending the value of the media.path property on the record to thecorresponding content source element within <mediaRoots>. The media.path is then saved to thecontent item when the content administrator saves the cartridge configuration.

By keeping the relative location of your media assets consistent across environments, you can maintainseparate content sources for authoring and live environments without requiring content administratorsto reconfigure content items.

For example, assume the following element within <mediaRoots> in the editor configuration file:<myMediaSource>http://myhost.mydomain.com:8006/myCMS/Discover/media/</my¬MediaSource>

A media record with a media.repository_id value of "myMediaSource" and a media.pathvalue of "images/foo.jpg" would resolve to:http://myhost.mydomain.com:8006/myCMS/Discover/media/images/foo.jpg

At runtime, the value of the media.path property is instead appended to the appropriate mediasource configured in assembler-context.xml:

<bean id="authoringMediaSources" class="java.util.ArrayList" lazy-init="true"> <constructor-arg> <list> <bean class="com.endeca.infront.cartridge.model.MediaSourceCon¬fig">

<property name="sourceName" value="MyMediaSource" /> <property name="sourceValue" value="http://myhost.mydo¬main.com:8006/myCMS/Discover/media/" /> </bean> <bean class="com.endeca.infront.cartridge.model.MediaSourceCon¬fig"> <property name="sourceName" value="default" /> <property name="sourceValue" value="http://myhost.mydo¬

main.com:8006/myCMS/Discover/media/" /> </bean> </list> </constructor-arg></bean>

<bean id="liveMediaSources" class="java.util.ArrayList" lazy-init="true"> <constructor-arg> <list> <bean class="com.endeca.infront.cartridge.model.MediaSourceCon¬fig">

<property name="sourceName" value="MyMediaSource" /> <property name="sourceValue" value="http://myhost.mydo¬main.com:8006/myBiggerFasterCMS/Discover/media/assets/" /> </bean> <bean class="com.endeca.infront.cartridge.model.MediaSourceCon¬fig"> <property name="sourceName" value="default" /> <property name="sourceValue" value="http://myhost.mydo¬main.com:8006/myBiggerFasterCMS/Discover/media/assets/" /> </bean> </list> </constructor-arg></bean>

In a live environment, the aforementioned media record would resolve to:http://myhost.mydomain.com:8006/myBiggerFasterCMS/Discover/media/assets/im¬ages/foo.jpg

Note: While the tooling, authoring, and live content sources can all differ, Oracle recommendsconfiguring the Media Browser to use the authoring content source.

Related LinksInteraction between an Endeca application and the media MDEX Engine components on page 129

The interactions between a media MDEX Engine, Experience Manager, and Endeca Webapplication are summarized below.

Adding a Boost-Bury Record editorThe Boost-Bury Record editor enables a content administrator to specify certain records to displayeither at the top or bottom of the list of results for a page.

The Boost-Bury Record editor uses the Select Records dialog to enable the content administrator tospecify either an ordered list of record IDs or a set of refinements that define the set of records to beboosted or buried.

Note: The Boost-Bury Record editor communicates with the MDEX Engine. In order to enablethe editor, ensure that you have enabled communication between Experience Manager and theMDEX Engine.

To add a Boost-Bury Record editor:

1. Insert an <editors:BoostBuryRecordEditor> element within <BasicContentItemEditor>.2. Specify additional attributes for the editor:



Required. The name of the item property that represents the records to beboosted to the top of the results. This property must be declared in thesame template as the Record Stratification editor.

propertyName

Required. The name of the list property that represents the records to beburied at the bottom of the results. This property must be declared in thesame template as the Record Stratification editor.

buryProperty

The following shows an example of a template that includes a Boost-Bury Record editor:<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008" xmlns:editors="editors" xmlns:xavia="http://endeca.com/schema/xavia/2010" type="MainContent" id="ResultsList">


<Property name="boostStrata"> <xavia:List/> </Property> <Property name="buryStrata"> <xavia:List/> </Property>



<editors:editors:BoostBuryRecordEditor propertyName="boostStrata"

buryProperty="buryStrata" label="Customize Results List" />





Adding a Guided Navigation editorThe Guided Navigation editor enables a content administrator to quickly create a navigation menuthrough the use of the Generate Guided Navigation wizard.

Note: The Guided Navigation editor communicates with the MDEX Engine. In order to enablethe editor, ensure that you have enabled communication between Experience Manager and theMDEX Engine.

A content administrator can use the Generate Guided Navigation button to trigger the GenerateGuided Navigation wizard. The wizard allows them to select and order a set of dimensions to add asRefinement Menu cartridges. Alternately, they can choose to add, order, and configure the cartridgesmanually.

To add a Guided Navigation editor:

1. Insert an<editors:GuidedNavigationEditor> element within<BasicContentItemEditor>.2. Set a propertyName attribute on the <editors:GuidedNavigationEditor> element.

This must be set to the name of the ContentItemList property that represents the list ofRefinement Menu content items. The property must be declared in the same template.

3. Insert an <editors:ContentItemMapping> element within the editor.4. Map the content item name to the dimension property that should populate it.

This determines the name of the Refinement Menu content items created by the Generate GuidedNavigation wizard.a) Include an <endeca:Name/> element within </endeca:ContentItemMapping>:

<endeca:ContentItemMapping> <endeca:Name/></endeca:ContentItemMapping>

b) Specify the dimension property to use for the content item name in a dimensionPropertyattribute:<endeca:ContentItemMapping> <endeca:Name dimensionProperty="display_name" /></endeca:ContentItemMapping>

c) Specify the dimension name as a fallback value.The Generate Guided Navigation wizard uses the first non-null value when naming anewly-created content item.<endeca:ContentItemMapping> <endeca:Name dimensionProperty="display_name" /> <endeca:Name dimensionProperty="endeca:name" /></endeca:ContentItemMapping>

5. Map the dimensionName and dimensionID properties to the dimension properties that populatethem:<endeca:ContentItemMapping> <endeca:Name dimensionProperty="display_name" /> <endeca:Name dimensionProperty="endeca:name" /> <endeca:Property name="dimensionName" dimensionProperty="endeca:name" /> <endeca:Property name="dimensionId" dimensionProperty="endeca:identi¬fier" /></endeca:ContentItemMapping>



The following shows an example of a template that includes a guided navigation editor:<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008" xmlns:endeca="editors" type="SecondaryContent" id="GuidedNavigation"> <Description>Creates a container for navigation cartridges.</Description>

<ThumbnailUrl>/ifcr/tools/xmgr/img/template_thumbnails/Secondary_Guid¬edNav.png</ThumbnailUrl>

<ContentItem> <Name>Navigation Container</Name>

<Property name="navigation"> <ContentItemList type="Navigation" /> </Property> </ContentItem>


<endeca:GuidedNavigationEditor propertyName="navigation" label=""> <endeca:ContentItemMapping>

 <endeca:Name dimensionProperty="display_name" /> <endeca:Name dimensionProperty="endeca:name" /> <endeca:Property name="dimensionName" dimensionProper¬ty="endeca:name" /> <endeca:Property name="dimensionId" dimensionProper¬ty="endeca:identifier" /> </endeca:ContentItemMapping> </endeca:GuidedNavigationEditor> </BasicContentItemEditor> </EditorPanel></ContentTemplate>

Adding a Dimension SelectorA Dimension Selector enables a content administrator to specify a dimension by name.

Note: The Dimension Selector communicates with the MDEX Engine. In order to enable theDimension Selector, ensure that you have enabled communication between Experience Managerand the MDEX Engine.

To add a Dimension Selector:

1. Insert an <editors:DimensionSelectorEditor> element within <BasicContentItemEdi¬tor>.

2. Specify additional attributes for the editor:DescriptionAttribute

Required. The name of the string property that represents the dimensionname. This property must be declared in the same template as the DimensionSelector.

propertyName


Required. The name of the string property that represents the dimension id.This property must be declared in the same template as the DimensionSelector.

idProperty

If set to false, this attribute makes the property read-only so that the valueof the property displays in the Content Details Panel in Experience Manager,

enabled

but cannot be edited. Use this option only if you specify a default value in thedefinition of the dimension name and dimension ID properties. Editors areenabled by default.

The following shows an example of a template that includes a dimension selector:<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008" xmlns:xavia="http://endeca.com/schema/xavia/2010" xmlns:editors="editors" type="Navigation" id="RefinementMenu"> <Description>Displays Endeca Facet Navigation in a Text Link Rendering. For Flat Dimensions only.</Description> <ThumbnailUrl>/ifcr/tools/xmgr/img/template_thumbnails/dimension_navi¬gation.jpg</ThumbnailUrl> <ContentItem> <Name>Dimension Navigation</Name>

<Property name="dimensionName"> <String/> </Property>


<editors:DimensionSelectorEditor propertyName="dimensionName" idProperty="dimensionId" label="Dimension Name" enabled="true"/>





Adding a Dimension List editorThe Dimension List editor enables a content administrator to select a list of dimensions from theapplication data set. The templates included with the reference application use this editor to specify



which dimensions should be available for display in a dimension search auto-suggest panel or adimension search results panel.

Note: The Dimension List editor communicates with the MDEX Engine. In order to enable theeditor, ensure that you have enabled communication between Experience Manager and theMDEX Engine.

To add a Dimension List editor:

1. Insert an <editors:DimensionListEditor> element within <BasicContentItemEditor>.2. Specify additional attributes for the editor:


Required. The name of the List property that represents the selecteddimension values. The property must be declared in the same template.

propertyName

The following shows an example of a template that includes a dimension list editor:<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008" xmlns:xavia="http://endeca.com/schema/xavia/2010" xmlns:editors="editors" type="MainContent" id="DimensionSearchResults">

<Description>Displays dimension search results.</Description> <ThumbnailUrl>/ifcr/tools/xmgr/img/template_thumbnails/Main_Dimension¬SearchResults.png</ThumbnailUrl> <ContentItem> <Name>Dimension Search Results</Name>

<Property name="dimensionList">

<xavia:List/> </Property>



<editors:DimensionListEditor propertyName="dimensionList"

label="Dimensions Searched" enabled="true"/>


Adding a Dimension Value Boost-Bury editorThe boost-bury editor enables a content administrator to specify certain dimension values to displayeither at the top or bottom of the list of refinements for a particular dimension.

In order to enable a Dimension Value Boost-Bury editor, the cartridge template must include a dimen¬sionId property with an associated editor or a default value. This specifies the dimension to whichthe boost-bury editor applies.

Note: The Dimension Value Boost-Bury editor makes use of an auto-suggest dimension searchcomponent to enable the content administrator to quickly find the relevant dimension values. Inorder for this component to display partial matches as the user types in the search box, ensurethat wildcard search is enabled for dimension searches in your MDEX Engine configuration.

To add a Dimension Value Boost-Bury editor:

1. Insert an <editors:BoostBuryEditor> element within <BasicContentItemEditor>.2. Specify additional attributes for the editor:


Required. The name of the list property that represents the list of dimensionvalues to be boosted to the top of the list of refinements. This property mustbe declared in the same template as the boost-bury editor.

propertyName

Required. The ID of the dimension that contains the dimension refinementsto boost or bury.

dimensionId

Required. The name of the list property that represents the list of dimensionvalues to be boosted to the top of the refinement list. This property must bedeclared in the same template as the boost-bury editor.

boostProperty

Required. The name of the list property that represents the list of dimensionvalues to be buried at the bottom of the list of refinements. This property mustbe declared in the same template as the boost-bury editor.

buryProperty

If set to false, this attribute makes the property read-only so that the valueof the property displays in the Content Details Panel in Experience Manager,

enabled

but cannot be edited. Use this option only if you specify a default value forthe boostList and buryList properties. Editors are enabled by default.

The following shows an example of a template that includes a dimension value boost-bury editor:<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008" xmlns:xavia="http://endeca.com/schema/xavia/2010" xmlns:editors="editors" type="Navigation" id="RefinementMenu"> <Description>Displays Endeca Facet Navigation in a Text Link Rendering. For Flat Dimensions only.</Description> <ThumbnailUrl>/ifcr/tools/xmgr/img/template_thumbnails/dimension_navi¬gation.jpg</ThumbnailUrl> <ContentItem> <Name>Dimension Navigation</Name> <Property name="dimensionName"> <String/> </Property>

<Property name="dimensionId"> <String/> </Property>

<Property name="boostRefinements">

<xavia:List/> </Property> <Property name="buryRefinements"> <xavia:List/> </Property> </ContentItem>

<editors:BoostBuryEditor propertyName="boostRefinements"

buryProperty="buryRefinements" label="Boost and Bury" dimensionIdProperty="dimensionId" en¬abled="true"/>


Adding a Dimension Value List editorThe Dimension Value List editor enables a content administrator to select a list of dimension valuesfrom the application data set.

Note: The Dimension Value List editor communicates with the MDEX Engine. In order to enablethe editor, ensure that you have enabled communication between Experience Manager and theMDEX Engine.

To add a Dimension Value List editor:

1. Insert an <editors:DimvalListEditor> element within <BasicContentItemEditor>.2. Specify additional attributes for the editor:


Required. The name of the List property that represents the selecteddimension values. The property must be declared in the sametemplate.

propertyName

Required. The ID of the dimension that the editor applies to.dimensionId

The following shows an example of a Refinement Menu template that uses two Dimension Value Listeditors to specify boosted and buried refinements, instead of a Dimension Value Boost-Bury editor:<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008" xmlns:xavia="http://endeca.com/schema/xavia/2010" xmlns:editors="editors" type="Navigation" id="RefinementMenu"> <Description>Displays Endeca Facet Navigation in a Text Link Rendering. For Flat Dimensions only.</Description> <ThumbnailUrl>/ifcr/tools/xmgr/img/template_thumbnails/dimension_navi¬gation.jpg</ThumbnailUrl> <ContentItem> <Name>Dimension Navigation</Name>

<Property name="dimensionId">

<String/> </Property>

<Property name="boostRefinements">

<xavia:List/> </Property> <Property name="buryRefinements">

<xavia:List/> </Property> </ContentItem> <EditorPanel> <BasicContentItemEditor>


<GroupLabel label="Boost and Bury Dimension Refinements"/><editors:DimvalListEditor dimensionIdProperty="dimensionId"

propertyName="boostRefinements" label = "Boost Records"/> <editors:DimvalListEditor dimensionIdProperty="dimensionId" propertyName="buryRefinements" label = "Bury Records"/>


Adding an Image PreviewAn image preview retrieves an image from a URL and displays it in the Experience Manager interface.

You can construct an image preview URL from a hard-coded value, or from any number of Stringproperties. Image preview supports JPEG, GIF, and PNG image formats.

Note: If images are hosted on a different server from Workbench, you may have to configurea cross-domain policy file to enable Flash player to access those resources.

To add an image preview to a template:

1. Insert an <ImagePreview> element within <BasicContentItemEditor>.2. Specify attributes for the image preview:


Required. The source of the image URL. You can construct urlExpres¬sion from any number of string properties, or you can enter a staticvalue.

urlExpression

The height in pixels of the image preview presented in the ExperienceManager interface. The default value is 100.

maxHeight

The width in pixels of the image preview presented in the ExperienceManager interface. The default value is 300.

maxWidth

A Boolean indicating whether to display the resolved URL. The defaultvalue is true.

displayUrl

If you are using more than one string property to compose the URL, you may want to use a<GroupLabel> to indicate to Experience Manager users that these properties are related.

The following examples show options for constructing an image preview.



Example: Specifying the URL by using a configurable String property

Add an <ImagePreview> to the cartridge template:<ContentTemplate ... > <ContentItem> <Name>Dimension Navigation</Name> ... </ContentItem> <EditorPanel> <BasicContentItemEditor> ...

<ImagePreview urlExpression="" label="Banner Image" maxWidth="200" maxHeight="100" /> ... </BasicContentItemEditor> </EditorPanel></ContentTemplate>

Add an image_src String property to the template:<ContentTemplate ... > <ContentItem> <Name>Dimension Navigation</Name>

<Property name="image_src"> <String/> </Property> </ContentItem> <EditorPanel> <BasicContentItemEditor> ... <ImagePreview urlExpression="" label="Banner Image" maxWidth="200" maxHeight="100" /> ... </BasicContentItemEditor> </EditorPanel></ContentTemplate>

Add a corresponding <StringEditor> to the <EditorPanel>, and set the value of urlExpressionto the image_src property:<ContentTemplate ... > <ContentItem> <Name>Dimension Navigation</Name> <Property name="image_src"> <String/> </Property> </ContentItem> <EditorPanel> <BasicContentItemEditor> ...

<StringEditor propertyName="image_src" label="Image name" en¬abled="true"/> <ImagePreview

urlExpression="http://localhost:8006/Discover/{image_src}" label="Banner Image"



maxWidth="200" maxHeight="100" /> ... </BasicContentItemEditor> </EditorPanel></ContentTemplate>

Adding a Record List editorThe Record List editor uses the microbrowser to enable a content administrator to designate specificrecords to spotlight in a section, or to specify a query to return a dynamic list of records. This editor isdeprecated.

Important: This editor is deprecated. Use the SpotlightSelectionEditor instead.

Note: The Record List editor communicates with the MDEX Engine. In order to enable the editor,ensure that you have enabled communication between Experience Manager and the MDEXEngine.

A Record List editor is bound to a RecordSpotlightSelection property, which can contain eithera list of record IDs (for featured records) or a set of refinements (for dynamic records).

To add a Record List editor to a template:

1. Insert an Item property of class com.endeca.infront.cartridge.RecordSpotlightSe¬lection named recordSelection as in the following example:<Property name="recordSelection"> <xavia:Item class="com.endeca.infront.cartridge.RecordSpotlightSelection" /></Property>

2. Insert an <editors:RecordListEditor> element within <BasicContentItemEditor>.3. Specify label attributes and the additional attributes for the editor:


Required. The name of the record selection property that represents therecords to be spotlighted. This property must be declared in the sametemplate as the Record Stratification editor.

propertyName

4. Insert a <PreviewProperty> element within <editors:RecordStratificationEditor>with the following attribute:


The name of the record property to display in the Content Details Panelindicating which records have been selected for boost or bury.

name

The following shows an example of a template that includes a record list editor:<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008" xmlns:editors="editors" xmlns:xavia="http://endeca.com/schema/xavia/2010" type="SidebarContent"



id="RecordSpotlight">

<ContentItem> <Name>Spotlight records</Name>

<Property name="recordSelection">

<xavia:Item class="com.endeca.infront.cartridge.RecordSpotlight¬Selection" /> </Property>


<EditorPanel> <BasicContentItemEditor> <GroupLabel label="Define Spotlight"/>

<editors:RecordListEditor propertyName="recordSelection"

label="Spotlight Records"> <PreviewProperty name="product.name"/> </editors:RecordListEditor>


Specifying record sort optionsThe sortOption property of the results list cartridge enables the content administrator to specify adefault sort order to apply to the results list when a site visitor reaches the page via navigation.

The available default sort options are defined in the Sort editor definition, which enables the contentadministrator to select from a predefined set of sort orders. The sort options that are available to thesite visitor to apply to the results list are configured in the cartridge handler for this cartridge.

To specify sort options for the record list:

1. Insert an item property of class com.endeca.infront.navigation.model.SortOptionnamed sortOption: <Property name="sortOption"> <xavia:Item class="com.endeca.infront.navigation.model.SortOption"/>

</Property>

2. Optionally, specify a default value for the property. The SortOption model includes the followingproperties:

DescriptionProperty Name

A descriptive label that displays in a drop-down menu in Experience Manager.label

A list of one or more items of class com.endeca.infront.naviga¬tion.model.SortSpec. Each SortSpec has two properties:

sorts

• key — A string representing the name of an Endeca property ordimension on which to sort

• descending — A Boolean value representing the sort direction

The following shows an example of a template that specifies a default sort option:<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008" xmlns:editors="editors" xmlns:xavia="http://endeca.com/schema/xavia/2010" type="MainContent" id="ResultsList">




 </ContentItem>

</ContentTemplate>

Related LinksCartridge handler configuration for the Results List cartridge on page 106

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

Adding a Record Stratification editorThe Record Stratification editor enables a content administrator to specify certain records to displayeither at the top or bottom of the list of results for a page.

Important: This editor is deprecated. Use the BoostBuryRecordEditor instead.

The Record Stratification editor uses the microbrowser to enable the content administrator to specifyeither an ordered list of record IDs or a set of refinements that define the set of records to be boostedor buried.

Note: The Record Stratification editor communicates with the MDEX Engine. In order to enablethe editor, ensure that you have enabled communication between Experience Manager and theMDEX Engine.

To add a Record Stratification editor:

1. Insert an<editors:RecordStratificationEditor> element within<BasicContentItemEd¬itor>.

2. Specify additional attributes for the editor:DescriptionAttribute

Required. The name of the item property that represents the records to beboosted to the top of the results. This property must be declared in thesame template as the Record Stratification editor.

propertyName

Required. The name of the list property that represents the records to beburied at the bottom of the results. This property must be declared in thesame template as the Record Stratification editor.

buryProperty

The following shows an example of a template that includes a record stratification editor:<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008" xmlns:editors="editors" xmlns:xavia="http://endeca.com/schema/xavia/2010" type="MainContent" id="ResultsList">


<Property name="boostStrata"> <xavia:List/> </Property> <Property name="buryStrata"> <xavia:List/> </Property>



<editors:RecordStratificationEditor propertyName="boostStrata"

buryProperty="buryStrata" label="Customize Results List" />


Adding a Rich Text editorThe Rich Text editor provides a text field and formatting toolbar that allows a content administrator toinclude formatted text and hyperlinks in a content item.

To add a Rich Text editor to a template:

1. Insert a <String> element inside a <Property> element.2. Optionally, specify the default value for the property as the content of the <String> element.3. Insert a corresponding <editors:RichTextEditor> element within <BasicContentItemEd¬

itor>.4. Specify the propertyName attribute for the editor:

<editors:RichTextEditor propertyName="description" enabled="true"/>

5. Specify any additional label attributes for the editor:<editors:RichTextEditor propertyName="description" label="Description"enabled="true"/>

6. Specify the height and toolbar configuration for the editor:<editors:RichTextEditor propertyName="description" label="Description" enabled="true" height="200" toolbar="[ { name: 'document', items : [ 'Source'] }, { name: 'clipboard', items : [ 'Cut','Copy','Paste','PasteText','Paste¬FromWord','-','Undo','Redo' ] }, { name: 'insert', items : [ 'Image','Table','HorizontalRule','Spe¬cialChar'] }, { name: 'paragraph', items : [ 'NumberedList','BulletedList','-','Outdent','Indent','-','JustifyLeft', 'JustifyCenter','JustifyRight','Justi¬fyBlock' ] }, { name: 'links', items : [ 'Link','Unlink','Anchor' ] }, '/', { name: 'basicstyles', items : [ 'Bold','Italic','Under¬line','Strike','Subscript','Superscript' ] }, { name: 'styles', items : [ 'Styles','Format','Font','FontSize' ] }, { name: 'colors', items : [ 'TextColor'] }]"/>

Note: The Rich Text editor is an implementation of the open source CKEditor WYSIWYGRich Text editor. For a full list of toolbar buttons and their functionality, see the documentationfor version 3.x of the CKEditor athttp://docs.cksource.com/CKEditor_3.x/Developers_Guide/Toolbar.

The following shows an example of a template that includes a rich text editor:<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008" xmlns:editors="editors" xmlns:xavia="http://endeca.com/schema/xavia/2010" type="MainContent" id="MediaBanner">

 <ContentItem> <Name>CategoryDescription</Name>

<Property name="description"> <String></String> </Property> </ContentItem>

<EditorPanel> <BasicContentItemEditor> <GroupLabel label="Contents"/>

<editors:RichTextEditor propertyName="description" label="De¬scription" enabled="true" height="200" toolbar="[ { name: 'document', items : [ 'Source'] }, { name: 'clipboard', items : [ 'Cut','Copy','Paste','PasteText','PasteFromWord','-','Undo','Redo' ] }, { name: 'insert', items : [ 'Image','Table','Horizon¬talRule','SpecialChar'] }, { name: 'paragraph', items : [ 'NumberedList','Bullet¬



http://docs.cksource.com/CKEditor_3.x/Developers_Guide/Toolbar

edList','-','Outdent','Indent','-', 'JustifyLeft','JustifyCen¬ter','JustifyRight','JustifyBlock' ] }, { name: 'links', items : [ 'Link','Unlink','Anchor' ] }, '/', { name: 'basicstyles', items : [ 'Bold','Italic','Under¬line','Strike','Subscript','Superscript' ] }, { name: 'styles', items : [ 'Styles','For¬mat','Font','FontSize' ] }, { name: 'colors', items : [ 'TextColor'] } ]"/> </BasicContentItemEditor> </EditorPanel></ContentTemplate>

Adding a Sort editorA Sort editor enables the content administrator to choose a sort order (sort key and direction) to applyto a list of records.

Within the results list cartridge, this sort order (along with any boost/bury that is configured for thepage) is applied to the results list by default when the end user first arrives at a page. If additional sortoptions are specified for this cartridge, the end user can select an alternate sort order and later returnto the default ordering as specified by the content administrator.

To add a Sort editor:

1. Insert an <editors:SortEditor> element within <BasicContentItemEditor>.2. Specify additional attributes for the editor:


Required. The name of the item property that represents the defaultsort option. This property must be declared in the same template asthe Sort editor.

propertyName

3. Specify one or more items of class com.endeca.infront.navigation.model.SortOptionfrom which the content administrator can select.

The following shows an example of a template that includes a sort editor:<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008" xmlns:editors="editors" xmlns:xavia="http://endeca.com/schema/xavia/2010" type="MainContent" id="ResultsList">

<GroupLabel label="Navigation Result Settings (apply when user does not provide search terms)"/> <editors:SortEditor propertyName="sortOption" label="Default Sort"> <xavia:Item class="com.endeca.infront.navigation.model.SortOption">

<xavia:Property name="label">Default</xavia:Property> <xavia:Property name="sorts"> <xavia:List /> </xavia:Property> </xavia:Item> <xavia:Item class="com.endeca.infront.navigation.model.SortOption">

<xavia:Property name="label">Most Sales</xavia:Property> <xavia:Property name="sorts"> <xavia:List> <xavia:Item class="com.endeca.infront.navigation.model.Sort¬Spec"> <xavia:Property name="key">product.analytics.to¬tal_sales</xavia:Property> <xavia:Property name="ascending">true</xavia:Property> </xavia:Item> </xavia:List> </xavia:Property> </xavia:Item> <xavia:Item class="com.endeca.infront.navigation.model.SortOption">

<xavia:Property name="label">Best Conversion Rate</xavia:Property>

<xavia:Property name="sorts"> <xavia:List> <xavia:Item class="com.endeca.infront.navigation.model.Sort¬Spec"> <xavia:Property name="key">product.analytics.conver¬sion_rate</xavia:Property> <xavia:Property name="ascending">true</xavia:Property> </xavia:Item> </xavia:List> </xavia:Property> </xavia:Item> <xavia:Item class="com.endeca.infront.navigation.model.SortOption">

<xavia:Property name="label">Price (Ascending)</xavia:Property> <xavia:Property name="sorts"> <xavia:List> <xavia:Item class="com.endeca.infront.navigation.model.Sort¬Spec">

<xavia:Property name="key">product.price</xavia:Property> <xavia:Property name="ascending">true</xavia:Property> </xavia:Item> </xavia:List> </xavia:Property> </xavia:Item> <xavia:Item class="com.endeca.infront.navigation.model.SortOption">

<xavia:Property name="label">Price (Descending)</xavia:Property>

<xavia:Property name="sorts"> <xavia:List> <xavia:Item class="com.endeca.infront.navigation.model.Sort¬Spec"> <xavia:Property name="key">product.price</xavia:Property> <xavia:Property name="ascending">false</xavia:Property> </xavia:Item> </xavia:List> </xavia:Property> </xavia:Item> </editors:SortEditor> </BasicContentItemEditor> </EditorPanel></ContentTemplate>

Adding a Spotlight Selection editorThe Spotlight Selection editor uses the Select Records dialog to enable a content administrator todesignate specific records to spotlight in a section, or to specify a query to return a dynamic list ofrecords.

Note: The Spotlight Selection editor communicates with the MDEX Engine. In order to enablethe editor, ensure that you have enabled communication between Experience Manager and theMDEX Engine.

A Spotlight Selection editor is bound to a RecordSpotlightSelection property, which can containeither a list of record IDs (for featured records) or a set of dimension refinements (for dynamic records).

To add a Spotlight Selection editor to a template:

1. Insert an Item property of class com.endeca.infront.cartridge.RecordSpotlightSe¬lection.In the following example, this is the recordSelection property:<Property name="recordSelection"> <xavia:Item class="com.endeca.infront.cartridge.RecordSpotlightSelec¬tion" /></Property>

2. Insert a String property that stores the maximum number of records to display in the spotlight.In the following example, this is the maxNumRecords property:<Property name="maxNumRecords"> <String>10</String></Property>

3. Insert a Boolean property that controls the display of the "See All" link.



In the following example, this is the showSeeAllLink property:<Property name="showSeeAllLink"> <Boolean>false</Boolean></Property>

4. Insert a String property to contain the text for the "See All" link.In the following example, this is the seeAllLinkText property:<Property name="seeAllLinkText"> <String /></Property>

5. Insert an <editors:RecordSpotlightSelectionEditor> element within <BasicCon¬tentItemEditor>.

6. Specify label attributes and map the editor to the associated properties:DescriptionAttribute

Required. The name of the record selection property that representsthe selected records or navigation state. This property must bedeclared in the same template as the record selection editor.

propertyName

Required. Specifies the maximum number of records to display inthe spotlight.

maxNumRecords

Required. Controls the display of the "See All" link.showSeeAllLink

Required. Specifies the text for the "See All" link.seeAllLinkText

The following shows an example of a template that includes a spotlight selection editor:<ContentTemplate xmlns="http://endeca.com/schema/content-template/2008" xmlns:editors="editors" xmlns:xavia="http://endeca.com/schema/xavia/2010" type="SecondaryContent" id="RecordSpotlight"> <Description>Displays selected records in seconday content area.</De¬scription> <ThumbnailUrl>/ifcr/tools/xmgr/img/template_thumbnails/Sec¬ondary_RecordSpotlight.png</ThumbnailUrl> <ContentItem> <Name>Spotlight Records</Name> <Property name="title"> <String>Featured Cameras</String> </Property>

<Property name="maxNumRecords"> <String>10</String> </Property> <Property name="recordSelection"> <xavia:Item class="com.endeca.infront.cartridge.RecordSpotlight¬Selection" /> </Property> <Property name="showSeeAllLink"> <Boolean>false</Boolean> </Property> <Property name="seeAllLinkText"> <String /> </Property> </ContentItem>



<EditorPanel> <BasicContentItemEditor> <GroupLabel label="Define Spotlight"/> <editors:StringEditor propertyName="title" label="Spotlight Title" enabled="true"/>

<editors:SpotlightSelectionEditor propertyName="recordSelection" label="Spotlight Records" maxNumRecords="maxNumRecords" showSeeAllLink="showSeeAllLink" seeAllLinkText="seeAllLinkText" /> </BasicContentItemEditor> </EditorPanel></ContentTemplate>




Application feature property referenceThis is an overview of the mappings between features in a front-end application and their associatedconfiguration properties.

Query configuration mappings

Global configuration for the features below is typically set in the Assembler context file on the classand property specified in the table.

Cartridge Handler(s)Global Configuration<class>.<property>

URLParameter

Feature

UrlNavigationState¬Builder

FilterState.navigation¬Filters

NNavigation query

RefinementMenuRefinementMenuConfig.re¬finementsShown

NrmcRefinement displayin menu

RefinementMenuRefinementMenuCon¬fig.showMore

Enable "Show MoreRefinements" link

NavigationContainerNavigationContainer.show¬MoreIds

"Show More"dimension IDs


DefaultResultsListConfigRRecord details

ResultsListResultsListConfig.offsetNoRecord offset


199Template Property and Editor Reference | Application feature property reference


URLParameter

Feature

ResultsListResultsListConfig.sub¬RecordsPerAggregatRecord

- -Records to show peraggregate record


FilterState.recordFil¬ters

NrRecord filter

ResultsListResultsListCon¬fig.recordsPerPage

NrppRecords per page

ResultsList, Dimension¬SearchResult

FilterState.SearchFil¬ters.key

NtkRecord search key


- -AAggregate recordselection

ResultsListResultsListConfig.offsetNaoAggregate recordoffset


FilterState.rollupKey- -Aggregate recordrollup key

ResultsListResultsListCon¬fig.whyRankEnabled

whyrankWhy Rank

ResultsListResultsListConfig.why¬MatchEnabled

whymatchWhy Match

RefinementMenu, Naviga¬tionContainer

RefinementMenu.whyPrece¬denceRuleFired, Naviga¬tionContainer.whyPrece¬denceRuleFired

whyprece¬dencerule¬fired

Why PrecedenceRule Fired


FilterState.rangeFiltersNfRange filter


FilterState.rangeFiltersNfgGeocode range filter

- -UserState.dateEnde¬ca_Time

Set preview time

ResultsListFilterState.SearchFil¬ters.MatchMode

NrmRelevance rankingMatch Mode

ResultsListResultsListConfig.rel¬RankStrategy, Dimension¬

- -Relevance rankingstrategy

SearchResultsConfig.rel¬RankStrategy

- -- -NrtRelevance rankingsearch terms

ResultsList- -NrkRelevance rankingsearch key


Template Property and Editor Reference | Application feature property reference200


URLParameter

Feature


FilterState.eqlFilterNrsEQL filter

ResultsList, Refinement¬Menu

ResultsListConfig.sortOp¬tion, RefinementMenu.sort

NsSort key

Sort order


SearchAdjustmentsCon¬fig.phraseSuggestionEn¬abled

NtpCompute phrasings

Rewrite query withalternate phrasing


FilterState.SearchFil¬ters.terms

NttSearch terms


FilterState.SearchFil¬ters.matchMode

NtxSearch mode


SearchAdjustmentsCon¬fig.spellSuggestionEn¬abled

Nty"Did You Mean"

DySignal dimensionsearch

See NttSee NttNtt withDy=1

Dimension searchterm

See NfSee NfNf withDy=1

Dimension searchrange filter

DimensionSearchRe¬sultHandler

DimensionSearchResultCon¬fig.relRank

- -Enable dimensionsearch relevanceranking

See NSee NNwith Dy=1Dimension searchscope

- -- -- -Dimension searchresult offset


DimensionSearchResultCon¬fig.maxResultsPerDimen¬sion

- -Dimension searchdimVal count

See NrSee NrNr withDy=1

Dimension searchrecord filter


DimensionSearchResultCon¬fig.showCountsEnabled

- -Dimension searchrefinementconfiguration

See NrsSee NrsNrs withDy=1

Dimension searchEQL filter

- -- -- -Dimension searchoptions


201Template Property and Editor Reference | Application feature property reference

Appendix B

Request Event Attributes

The RequestEvent and NavigationEventWrapper classes support getting and setting commonsearch and navigation information on a request event. This Appendix provides a reference table ofout-of-the-box attributes that you can retrieve or set on a RequestEvent object.

Base request event attributesThe following describes the base schema for an Assembler request event.

The RequestEvent class includes getter and setter methods for each of these attributes.

DescriptionTypeAttribute

The unique identifier for a browser session. To retrieve thisinformation, you must register an implementation of Session¬IdProvider in the request event adapter constructor.

Stringendeca:sessionId

The time (in milliseconds from POSIX Epoch) that the assem¬ble() method started

longendeca:assemblyStart¬Timestamp

The time (in milliseconds from POSIX Epoch) that the assem¬ble() method finished

longendeca:assemblyFinish¬Timestamp

Navigation request event attributesThe following describes the schema for an Assembler navigation request event. These fields are inaddition to those described for the base request.

The NavigationEventWrapper class includes getter and setter methods for each of these attributes.


The suggested auto-correct term, if it triggers for the request.Stringendeca:autocorrectTo


The content path of the page corresponding to the request.Stringendeca:contentPath

The suggested "Did You Mean" term, if it triggers for therequest.

List<String>

endeca:didYouMeanTo

The dimension names selected for navigation.List<String>

endeca:dimensions

The dimension value names selected for navigation.List<String>

endeca:dimensionVal¬ues

The time, in milliseconds, that it takes the MDEX Engine torun the query.

Longendeca:eneTime

The number of records returned for the request.Longendeca:numRecords

The number of selected refinements.Integerendeca:numRefine¬ments

The names of the records returned by the request.List<String>

endeca:recordNames

To populate this attribute, the recordDisplayFieldNameproperty on the ResultsListConfig object must be setto the name of the field that contains record names.

The record specifier for a selected record.Stringendeca:recordSpec

The type of request. Possible values are:Request¬Type

endeca:requestType

• T - Root navigation• N - Navigation only• S - Search only• SN - Search, then navigation• R - Record detail• UNKNOWN - Unknown

The search key for the current navigation state.Stringendeca:searchKey

The search mode for the request.Stringendeca:searchMode

The search terms for the request.Stringendeca:searchTerms

The site root path of the page corresponding to the request.Stringendeca:siteRootPath

The sort keys for the request. Each key is a String withthe format fieldName|<Descending|Ascending> .

List<String>

endeca:sortKey


Request Event Attributes | Navigation request event attributes204


The list of spotlights triggered for the request.List<String>

endeca:spotlights


205Request Event Attributes | Navigation request event attributes

Index

AActions

about 65Action fields 66, 67using 66, 67using with packaged services 67

application URLsabout 65Actions 65configuration 68

AssemblerAssembler Service 49configuration 42content include query 47content slot query 48dependencies 41deploying 41dynamic content query 48error handling 63event listeners 60eventing framework 60invoking in Java 46libraries 41processing content by URI 47rendering the response 58requirements 41Spring configuration 42

Assembler APIActionPathProvider interface 65

Assembler libraries 41Assembler service

about 46configuring 46

Assembler Service 41querying 49

Assembler services 14Assembler servlet

error handling 63response format 50

Auto-suggest cartridges 84Auto-Suggest Dimension Search Results cartridge

cartridge handler configuration 85configuration model 84template configuration 85

Auto-Suggest paneltemplate configuration 84

automatic phrasingexample scenarios 92, 93implementing 91

Bboost and bury 103Breadcrumbs cartridge 102

cartridge handler configuration 103

Ccanonical link 72cartridge

default configuration 80instance configuration 81MDEX Engine configuration 80request configuration 82

cartridge handlers 45configuring 43, 80

checkbox editor 161choice editor 154combo box editor 154content collections

creating 21example 17moving 22overview 16

content itemproperty type 31type 26

content item list 32content items

container 31content properties

editor mappings 147primitive types 151

content slotnested in other content items 48

content type 13, 26core cartridges

Auto-Suggest Dimension Search Results cartridge84Auto-Suggest panel 84Breadcrumbs 102Dimension Search Results 85Media Banner 111Record Details 108Record Spotlight 109Refinement Menu 97Results List 103Search Adjustments 88Search Box 82

Ddata application 132, 133, 134

interaction with Experience Manager 129device detection

reference application 76Dimension List editor 185Dimension Search Results cartridge 85

cartridge handler configuration 87configuration model 86MDEX Engine configuration 86template configuration 87URL parameters 87

dimension value list editor 187Discover Electronics

handling of renderers 57sample templates 23

dynamic content 54dynamic slot editor 170dynamic slots 45, 112, 168

about 112adding 169Assembler configuration 170configuration 170editor 170use cases 112

Eeditor configuration

data service 165, 167editors

configuring 30dimension list editor 185dimension selector 183dimension value boost-bury 185dimension value list editor 187dynamic slots 168, 169editor-specific configuration 30editors.xml 30guided navigation editor 182image preview 188label configuration 150Link Builder 171media editor 173, 174, 175, 177, 178record list editor 190, 197record stratification 180, 192rich text editor 193sort editor 195

emgr_updateremove_templates 39

Endeca Query Languageabout 125applying a default filter 127applying a filter 126relevance ranking 127troubleshooting 128URL parameters 127

EQL 125

See also Endeca Query Languageevent listeners

creating 61registering 62

Experience Managerinteraction with media MDEX Engine 129

Ffeature configuration

sources of 79

Ggroup labels 164guided navigation editor 182Guided Search Service

dynamic content 55handling the response 55

Guided Search services 50, 67Dimension Search Service 51Guided Search Service 53, 54Record Details Service 52

HHTTP servlet request 43

JJSP

example 55, 58

Kkeyword redirects

about 93Assembler response 95Assembler service 95cartridge handler configuration 93content XML 94

LLink Builder

adding 171configuration 172

Log Serverclient side click events 145

loggingrequest event adapters 142, 143, 144request events 141

Oracle Endeca Commerce208

Index

MMDEX Engine

configuration for Experience Manager editors 165, 167data service configuration 165, 167media MDEX Engine 132, 134using to index media

MDEX request builder 43MDEX resource 43Media Banner cartridge 111

cartridge handler configuration 111configuration model 111MDEX Engine configuration 111template configuration 111

media browserenabling 177

Media Browser 174, 175media editor 175Media editor 173, 174, 179

media browser 177uploading media 178

media MDEX Engine 177interaction with Experience Manager 129

media paths 179microbrowser 165multichannel applications

about 75

NNavigation Container

about 101cartridge handler configuration 102configuration model 101URL parameters 102

navigation state builder 43NavigationCartridgeHandler

and navigation state 45and subclasses 45

Ppackaged services

Actions 67page types

content structure 13overview 12with services 14

pagescreating 16

preview applicationabout 115about previewing mobile devices 116adding a device 116auditing 116changing 121changing the link service 121enabling 119

preview application (continued)instrumenting 118modifying a device 117removing a device 117testing 123

preview link service 121properties

and configuration in Experience Manager 29Boolean 160content item 31content item list 32defining 28editor mappings 147item 163list 162numeric 158overview 28sort options 191string 152template section 31, 32

property editorscartridge selector 33checkbox 161choice 154default value 153grouping 164introduced 29numeric stepper 158radio group 156section 33slider 159string 153

Qquery debugging

about 137enabling 137, 138results 138URL parameters 138

Rradio button editor 156Record Details cartridge 108

cartridge handler configuration 109configuration model 108MDEX Engine configuration 108template configuration 109

Record Spotlight cartridge 109cartridge handler configuration 110configuration model 109MDEX Engine configuration 110template configuration 110

RecordDetailsHandlerand record state 45

reference applicationdevice detection

reference application 76

209

Index

reference application (continued)request event adapters 144

reference data applicationconfiguring 133overview 132requirements 132

Refinement Menu cartridge 97cartridge handler configuration 99configuration model 97MDEX Engine configuration 99template configuration 100URL parameters 100

relevance ranking 103renderers 57request event adapters

registering 143request events

attributes 203navigation attributes 203

response format 50Results List cartridge 103


Rich Text editor 193rule groups, See content collections

SSearch Adjustments cartridge 88


Search Box cartridge 82MDEX Engine configuration 83template configuration 83

Select Records dialog 167services, See Assembler servicessitemap

planning 11snippeting 107

sorting 103structural properties 31

Ttemplates

and Discover Electronics 23creating 23defining editors 29

See also property editorsdefining properties 28defining sections 31, 32description, specifying 26id 26mobile channel templates 75Name property 27naming conventions 25pages based on missing templates 38properties 28

See also propertiesremoving from Experience Manager 39saving 25schema 25structure 24troubleshooting 35troubleshooting default values 37type 26updating 37validation 25, 35

thumbnail imagesspecifying 26using 27

UURL formatter class

basic URLs 70optimized URLs 70

URL parameters 68

Zzones, See content collections

Oracle Endeca Commerce210

Index

oracle endeca commerce: assembler application developer's ......• default • christmas •...

Documents