Retrieving breadcrumbs in a navigation query

An initial Conversation Web Service request that is made in response to a user-initiated navigation query (in which no selections have been made in the navigation state) does not yet return breadcrumbs. However, a subsequent request (in which the user made selections within the available attribute values) returns breadcrumbs.

The request for breadcrumbs is implemented with the ContentElementConfig element with the BreadcrumbHandler:
<ContentElementConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:type="BreadcrumbConfig" 
  ReturnFullPath="false"
  HandlerFunction="BreadcrumbHandler"
  HandlerNamespace="http://www.endeca.com/MDEX/conversation/1/0"
  Id="Breadcrumbs"/>
This element includes:
ReturnFullPath Specifies whether to return the full path of hierarchical refinements with the response. This setting is relevant only in navigation queries that request breadcrumbs; it is ignored in search or range filter queries requesting breadcrumbs.

If set to true, the returned breadcrumb contains the full path to its parent refinement values, as in Wine > Red > Merlot.

If set to false, returns only the refinement, without the path to its ancestors. The default is false.

BreadcrumbHandler Is the function that facilitates breadcrumb generation in the response. This function is required to return breadcrumbs.

If spelling is enabled in the data store configuration, and in addition to breadcrumbs, you want the Conversation Web Service response to contain supplemental information about spelling suggestions and DYM, a second ContentElementConfig with SearchAdjustmentHandler is required. If this element is included, spelling correction or DYM suggestions are returned with the breadcrumbs in the response.

Note: If spelling is enabled, spelling correction occurs for breadcrumb results even if ContentElementConfig with SearchAdjustmentHandler is not included; however, while spelling correction takes place, the spelling correction and DYM suggestions are not returned in the response.

In the response, breadcrumbs are returned in the order in which they were added (requested).

To request breadcrumbs for a navigation query:

In the Conversation Web Service request, specify the following:

In this example, the navigation state includes a selection of the NumberOfDigits refinement, and two ContentElementConfig elements, one for BreadcrumbHandler and one for SearchAdjustmentHandler:

<Request xmlns="http://www.endeca.com/MDEX/conversation/1/0">
  <State/>
  <Operator xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:type="RefinementOperator" Spec="/2" 
    Name="NumberOfDigits"/>
  <ContentElementConfig
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:type="BreadcrumbConfig" 
    ReturnFullPath="true" HandlerFunction="BreadcrumbHandler" 
    HandlerNamespace="http://www.endeca.com/MDEX/conversation/1/0" Id="Breadcrumbs"/>
  <ContentElementConfig
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="SearchAdjustmentConfig" 
    HandlerFunction="SearchAdjustmentHandler"
    HandlerNamespace="http://www.endeca.com/MDEX/conversation/1/0"
    Id="SearchAdjustments"/>
  <PassThrough> ...</PassThrough>
</Request>

The Conversation Web Service result includes the original request with operators for BreadcrumbHandler and SearchAdjustmentHandler applied, followed by the ContentElementConfig element that lists attribute values identified as breadcrumbs, based on the user-selected navigation state.

Note: The result also includes the GeneralizationOperator. It enables the removal of the refinement (and thus the breadcrumb) in the user interface of the front-end application powered by the Oracle Endeca Server (such as Studio), if the user chooses to remove the previously selected refinement from the breadcrumb list.
The first half of the response repeats the request, as follows:
<cs:Results xmlns:cs="http://www.endeca.com/MDEX/conversation/1/0" 
  xmlns:mdex="http://www.endeca.com/MDEX/XQuery/2009/09">
  <cs:Request>
  <cs:State>
  <cs:SelectedRefinementFilter Name="NumberOfDigits" Spec="/2"/>
  </cs:State>
  <ContentElementConfig xmlns="http://www.endeca.com/MDEX/conversation/1/0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:type="BreadcrumbConfig" ReturnFullPath="true"  
    HandlerFunction="BreadcrumbHandler" 
    HandlerNamespace="http://www.endeca.com/MDEX/conversation/1/0" Id="Breadcrumbs"/>
  <ContentElementConfig xmlns="http://www.endeca.com/MDEX/conversation/1/0" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:type="SearchAdjustmentConfig" HandlerFunction="SearchAdjustmentHandler" 
    HandlerNamespace="http://www.endeca.com/MDEX/conversation/1/0" 
    Id="SearchAdjustments"/>
  </cs:Request>
The second half of the response includes breadcrumbs:
<cs:ContentElement xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
   xsi:type="cs:Breadcrumbs" Id="Breadcrumbs">
  <cs:RefinementBreadcrumb Name="NumberOfDigits"
   DisplayName="Number Of Digits" Spec="/2">
  <cs:DimensionValue>
  <cs:DimensionValue DimensionName="NumberOfDigits" Spec="/">
   NumberOfDigits
  </cs:DimensionValue>
  <cs:Operator xsi:type="cs:GeneralizationOperator" Name="" Spec="/"/>
  </cs:DimensionValue>
  <cs:DimensionValue>
  <cs:DimensionValue DimensionName="NumberOfDigits" Spec="/2">2
  </cs:DimensionValue>
  <cs:Operator xsi:type="cs:GeneralizationOperator" Name="" Spec="/2"/>
  </cs:DimensionValue>
  <cs:Operator xsi:type="cs:GeneralizationOperator"
   Name="NumberOfDigits" Spec="/2"/>
  </cs:RefinementBreadcrumb>
  </cs:ContentElement>
 <cs:ContentElement xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:type="cs:SearchAdjustments" Id="SearchAdjustments"/>
</cs:Results>