Step 1: Obtaining and exposing attributes that have refinements

The first step in displaying refinements is to retrieve those attributes that potentially have refinements.

You can retrieve refinements in two ways, depending on whether their attributes are included in groups:

If you are using attribute groups, you retrieve refinements on groups with RefinementGroupConfig.
If you are not using attribute groups, you retrieve individual refinements with RefinementConfig.
As an alternative to using RefinementConfig, to retrieve refinements that are not explicitly included in any user-configured attribute groups, you can request a group system-navigation_InternalGroup. This group exists in the Oracle Endeca Server and includes all refinements that are not members of any other groups.

Refinements are returned in a NavigationMenu content element. If your attributes belong to groups, this element contains a NavigationMenuItemGroup element with NavigationMenuItem elements for each managed attribute with refinements.

Note: If you have precedence rules configured, they will suppress attributes that have valid refinements until a trigger for the precedence rule is met. For information on precedence rules, see Using Precedence Rules.

Retrieving refinements for attribute groups

Consider this request in which the WineType refinement is requested and exposed:

<Request xmlns="http://www.endeca.com/MDEX/conversation/2/0">
 <State/>
 <ContentElementConfig xsi:type="NavigationMenuConfig"
  Id="NavigationMenu"
  HandlerFunction="NavigationMenuHandler"
  HandlerNamespace="http://www.endeca.com/MDEX/conversation/2/0" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <RefinementGroupConfig Name="Wine Characteristics" Expose="true">   
    <RefinementConfig Name="WineType" Expose="true"/>
   </RefinementGroupConfig>
  </ContentElementConfig>
</Request>

It returns the following query results. Notice that the query results show the WineType refinement and the refinement values on it — Red, White, and Sparkling.

<cs:Results xmlns:cs="http://www.endeca.com/MDEX/conversation/2/0" 
xmlns:mdex="http://www.endeca.com/MDEX/XQuery/2009/09">
 <cs:Request>
  <State xmlns="http://www.endeca.com/MDEX/conversation/2/0">
  <ContentElementConfig xsi:type="NavigationMenuConfig" 
Id="NavigationMenu" 
HandlerFunction="NavigationMenuHandler" 
HandlerNamespace="http://www.endeca.com/MDEX/conversation/2/0" 
xmlns="http://www.endeca.com/MDEX/conversation/2/0" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <RefinementGroupConfig Name="Wine Characteristics" Expose="true">     
    <RefinementConfig Name="WineType" Expose="true" 
xmlns:ns="http://www.endeca.com/MDEX/conversation/2/0">
   </RefinementGroupConfig>  
  </ContentElementConfig>
  </cs:Request>
  <cs:ContentElement xsi:type="cs:NavigationMenu" Id="NavigationMenu" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <cs:NavigationMenuItemGroup Name="Wine Characteristics" 
  HasRefinablePRoperties="true">
    <cs:NavigationMenuItem Name="WineType" DisplayName="WineType" 
     MultiSelect="Or" HasMore="false">
        <cs:ExposureControl Exposed="true">
          <cs:Operator OwnerId="NavigationMenu" 
          xsi:type="cs:RefinementHideOperator" 
              Name="WineType"
              Spec="/" 
              Group="Wine Characteristics"/>
         </cs:ExposureControl>
         <cs:Refinement Name="WineType" Spec="/Red" Label="Red" 
          Count="18">
          <cs:Operator xsi:type="cs:RefinementOperator" 
          Name="WineType" Spec="/Red"/>
         </cs:Refinement>
         <cs:Refinement Name="WineType" Spec="/White" Label="White" 
          Count="40">
          <cs:Operator xsi:type="cs:RefinementOperator" 
          Name="WineType" Spec="/White"/>
         </cs:Refinement>
         <cs:Refinement Name="WineType" Spec="/Sparkling" 
         Label="Sparkling" Count="50">
          <cs:Operator xsi:type="cs:RefinementOperator" 
          Name="WineType" Spec="/Sparkling"/>
         </cs:Refinement>
      <cs:RootDimensionValue DimensionName="WineType" Spec="/"/>
    </cs:NavigationMenuItem>
   </cs:NavigationMenuItemGroup>
  </cs:ContentElement>
</cs:Results>

In this example, the NavigationMenuItem element is used for the managed attribute included in a group:

<cs:NavigationMenuItemGroup Name="Wine Characteristics" HasRefinablePRoperties="true">
  <cs:NavigationMenuItem Name="WineType" DisplayName="WineType" MultiSelect="Or" HasMore="false">
   <cs:ExposureControl Exposed="true">
    <cs:Operator OwnerId="NavigationMenu" xsi:type="cs:RefinementHideOperator" 
       Name="WineType" Spec="/" Group="Wine Characteristics"/>
   </cs:ExposureControl>

Important:

Notice the RefinementOperator, such as this one from the previous example of the response:

<cs:Operator xsi:type="cs:RefinementOperator" 
          Name="WineType" Spec="/Red"/>

This operator will be used in the subsequent Conversation Web Service request to retrieve refinements.

Notice also the ExposureControl operator:

<cs:ExposureControl Exposed="true">
   <cs:Operator OwnerId="NavigationMenu" xsi:type="cs:RefinementHideOperator" 
       Name="WineType"
       Spec="/" 
       Group="Wine Characteristics"/>
</cs:ExposureControl>

The <cs:ExposureControl Exposed=""true"> statement indicates the current exposure status of a top-level refinement included in NavigationMenuItem. The ExposureControl operator can include two complex types — RefinementExposeOperator and RefinementHideOperator. These operators are used for exposing (or hiding) individual refinements. To use these operators, you must specify the OwnerId value, which should be the same as the content element to which the operators are applied. In the example: OwnerId="NavigationMenu".

Further examining this example, each refinement in this group is returned in a Refinement element, as shown in this example for the Red managed attribute value:

<cs:Refinement Name="WineType" Spec="/Red" Label="Red" Count="18">
   <cs:Operator xsi:type="cs:RefinementOperator" Name="WineType" Spec="/Red"/>
</cs:Refinement>

The Count element indicates that eighteen records would be in the result set if you were to refine on the Red refinement.

Retrieving refinements for attributes not included in groups

Consider the following request for a Region refinement:

<Request xmlns="http://www.endeca.com/MDEX/conversation/2/0">
  <State/>
  <ContentElementConfig xsi:type="NavigationMenuConfig"
    Id="NavigationMenu"
    HandlerFunction="NavigationMenuHandler"
    HandlerNamespace="http://www.endeca.com/MDEX/conversation/2/0" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">   
    <RefinementConfig Name="Region" Expose="true"/>
  </ContentElementConfig>
</Request>

This request will return individual refinements from a record set, listing all records for which values exist in the Region attribute.