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. For its format, see RefinementGroupConfig.
If you are not using attribute groups, you retrieve individual refinements with RefinementConfig. For its format, see 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 Endeca Server and includes all refinements that are not members of any other groups.

In the request, either you are using RefinementGroupConfig, or RefinementConfig, you include them in a NavigationMenuConfig. For its format, see NavigationMenuConfig.

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.

Retrieving suggested refinements for attribute groups

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

<Request xmlns="http://www.endeca.com/MDEX/conversation/3/0">
 <State/>
 <NavigationMenuConfig Id="NavigationMenu" IncludeAllExplicitSelections="false"
IncludeAllImplicitSelections="false">
   <RefinementGroupConfig Name="WineCharacteristics" Expose="true">   
     <RefinementConfig Name="WineType" Expose="true"/>
   </RefinementGroupConfig>
  </NavigationMenuConfig>
</Request>

Notice that IncludeAllExplicitSelections and IncludeAllImplicitSelections are set to false. This is the default — the request asks to retrieve only those refinements that are still available for navigation (known as suggested refinements), and does not return refinements that have already been applied (which include explicitly-selected and implicit). For information on how to retrieve a full list of refinements, see Retrieving the full list of refinements (applied and suggested).

The request 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/3/0" 
    xmlns:mdex="http://www.endeca.com/MDEX/XQuery/2009/09">
  <State xmlns="http://www.endeca.com/MDEX/conversation/3/0">
  <cs:NavigationMenu" Id="NavigationMenu">
    <cs:NavigationMenuItemGroup Name="WineCharacteristics" HasRefinablePRoperties="true">
      <cs:NavigationMenuItem Name="WineType" DisplayName="Wine Type" MultiSelect="None" HasMore="false">
         <cs:ExposureControl Exposed="true"/>
         <cs:Refinement Name="WineType" Spec="Red" Label="Red" Count="31021"/>
         <cs:Refinement Name="WineType" Spec="White" Label="White" Count="23031"/>
         <cs:Refinement Name="WineType" Spec="Sparkling" Label="Sparkling" Count="3020"/>
         <cs:RootDimensionValue DimensionName="WineType" Spec="/"/>
         <cs:FullPath>
           <cs:DimensionValue DimensionName="WineType" Spec="/">WineType</cs:DimensionValue>
         </cs:FullPath>
      </cs:NavigationMenuItem>
    </cs:NavigationMenuItemGroup>
  </cs:NavigationMenu>
</cs:Results>

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

<cs:NavigationMenuItem Name="WineType" DisplayName="Wine Type" MultiSelect="None" HasMore="false">
   <cs:ExposureControl Exposed="true"/>

Notice the ExposureControl type:

<cs:ExposureControl Exposed="true"/>

The <cs:ExposureControl Exposed=""true"> statement indicates the current exposure status of a top-level refinement included in NavigationMenuItem.

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="31021"/>

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

Retrieving suggested refinements for attributes not included in groups

Consider the following request for a Region refinement:

<Request xmlns="http://www.endeca.com/MDEX/conversation/3/0">
  <State/>
  <NavigationMenuConfig Id="NavigationMenu" IncludeAllExplicitSelections="false"
IncludeAllImplicitSelections="false">   
    <RefinementConfig Name="Region" Expose="true" IncludeExplicitSelections="false" 
  IncludeImplicitSelections="false"/>
  </NavigationMenuConfig>
</Request>

This request will return individual suggested refinements from a record set, listing all records for which values exist in the Region attribute. In addition to suggested refinements, you can also optionally return applied refinements for this attribute. For information, see Retrieving applied refinements per attribute.

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 Precedence Rules.