Use the RefinementGroupConfig and RefinementConfig elements of the Conversation Web service request to expose refinement values for attributes. These elements allow you to perform operations on many attributes at once without enumerating all of them.
By default, attributes in groups and refinements are collapsed. If you would like to expose attributes that have refinements, either use RefinementConfig on each attribute whose refinements you want to expose, or use ExposeAllPropertyRefinements and expose refinements for all attributes at once.
The RefinementGroupConfig element returns a list of refinements from those attributes that are included in groups. It contains the RefinementConfig element.
Attribute | Description |
---|---|
Expose | Required. Indicates whether to evaluate
attributes in the group as potential refinements at all.
Using the Expose attribute is important when you have groups of attributes and would like to be able to "expand" and "collapse" them in the user interface of the front-end application. For example, if you wanted country name refinements, then in order to obtain them, you use Expose in the initial request which enables the expand/collapse options in the UI. Next, you request these refinements in a separate Conversation Web Service request. |
ExposeAllPropertyRefinements | Optional. Indicates whether to expose refinements (that is, whether to compute refinement values) for all attributes in the group. |
Name | Required. The name of the group. |
<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="Sales-Transaction" Expose="true"> <RefinementConfig Name="OrderQuantity" Expose="true" MaximumCount="100" /> </RefinementGroupConfig> </ContentElementConfig> </Request>
To perform operations on individual attributes in a group, instead of performing operations on all of them (for example, to override settings for an individual attribute), you can use multiple RefinementConfig elements in a RefinementGroupConfig.
The RefinementConfig element controls the behavior of an individual attribute in a NavigationMenu. It specifies which attributes, out of all valid refinements returned with a navigation query, should return actual refinement values, and includes specifications about the order and number of refinement values. You can omit RefinementConfig in your request if you do not need any of its optional items.
<RefinementConfig Name="OrderQuantity" Spec="/" Expose="false" OrderByRecordCount="false" MaximumCount="100"> </RefinementConfig>
For a given attribute, you can use only one RefinementConfig element.
Attribute | Description |
---|---|
Name | Required. The name of the attribute. |
Spec | Optional. Used for walking down a
hierarchy, without following the refinements as you navigate down the
refinement tree. The Spec identifies the refinement parent for the query.
For example, in an empty state, a NavMenu for the initial navigation state shows managed attribute ProductCategory to be available. The user expands ProductCategory; this puts a RefinementConfig Name="ProductCategory" into the RefinementConfig and sends it in to the Endeca Server. The NavMenu shows ProductCategory refinements, including Electronics, which is expandable. The user expands Electronics; this puts a RefinementConfig Name="ProductCategory" Spec="Electronics" into the RefinementConfig and sends it to the Endeca Server. Next, the response received from the Endeca Server contains NavMenu with the ProductCategory refinement starting at Electronics. For a refinement with hierarchy (which is based on values from a managed attribute), refinement values will be returned for any child managed attribute values of this spec. For example, Spec="/" refers to a root managed value (such as for WineType), while Spec="Merlot" refers to a child managed value. |
Expose | Optional. Specify false (the default) to compute whether this attribute is a refinement at all, or true to compute whether it is a refinement and also to retrieve and expose individual refinements (if any are present). |
OrderByRecordCount | Optional. Specify true to order by record count based on the individual query (dynamic ordering), or false (the default) to use the default order from the Oracle Endeca Server, specified by the system-navigation_Sorting attribute in the PDR. |
MaximumCount | Optional. An integer that specifies a
maximum limit on the number of refinements returned per standard or managed
attribute.
If this setting is not specified, the number of refinements returned per attribute in the Conversation Web Service response is dictated by the value of the MaximumRefinementCount attribute in the NavigationMenuConfig element in the Conversation Web Service request. If that value is not specified, the default is 10. |
The Expose attribute is also optional and defaults to false. Expose="false" helps improve performance.
<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="Sales-Characteristics" Expose="false"/> </ContentElementConfig> </Request>
will return information in HasRefineableProperties, but will not return refinements themselves. This is faster for the Oracle Endeca Server to compute. (To retrieve all attributes in the group, Expose should be set to true).
<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="Sales-Characteristics" Expose="true"> <RefinementConfig Name="ProductType" Expose="true" /> </RefinementGroupConfig> </ContentElementConfig> </Request>
will return all three managed attributes (since they are included in the Sales-Characteristics group), as well as the top-level refinement attribute values for the ProductType managed attribute. This is slightly more expensive for the Oracle Endeca Server to compute, and returns the three root managed attribute values as well as the top-level managed attribute values for ProductType, but is necessary for selecting a valid refinement.
<Request xmlns="http://www.endeca.com/MDEX/conversation/2/0"> <State/> <ContentElementConfig xsi:type="NavigationMenuConfig" HandlerFunction="NavigationMenuHandler" HandlerNamespace="http://www.endeca.com/MDEX/conversation/2/0" Id="NavigationMenu" ExposeAllRefinements="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <RefinementGroupConfig Name="Sales-Characteristics" Expose="true"/> </ContentElementConfig> </Request>
will return three managed attributes, as well as all valid top-level managed attribute values for each of these attributes.
<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="Sales-Characteristics" Expose="true"> <RefinementConfig Name="UnitPrice" Expose="true" /> <RefinementConfig Name="OrderQuantity" Expose="true" /> <RefinementConfig Name="CustomerPONumber" Expose="true" /> </RefinementGroupConfig> </ContentElementConfig> </Request>
This is the most expensive type of query for the Oracle Endeca Server to compute, and returns three root managed attribute values as well as all the top-level managed attribute values, creating a larger network and page size strain. This method, however, is effective for creating custom navigation solutions that require all possible refinement values to be displayed at all times.