Refinement Widget Configuration Options

The refinement widget lets the user restrict the search results on a page to the selected facet or facets.

The following options can be configured when creating the refinement widget.
Type Description
Refine by > Formula The field to facet by when making refinements. This is used instead of an identifier. For example facets see the Common Application Builder Faceting API Examples section of the documentation.

Default: none
Refine By > Preconfigured Refinement When selected, you can choose to create a refinement widget that contains one of the following search result refinements:
  • Tag - The user can restrict the results to only those that contain the selected tag.
  • Entity Types - The user can restrict the results to only those associated with the selected Entity.
  • Repositories - The user can select which data source the results come from.

Default: none
Display as The display method for this refinement widget.
Important: Nested and hierarchical facets are only supported with the List display method.
Options are:
  • List - The refinement is displayed as a list of text items with the number of items matching the refinement as a suffix.
    • Enable expand/collapse on nested facets - When on, users can expand groups of nested or hierarchical facets. When off, facets will be expanded by default.

      Default: on

  • Pie - The refinement is displayed as a pie chart with the size of each wedge representing the number of items in each refinement.
    • Tooltip value suffix - The suffix that is applied to the refinement value when the result information is displayed (on mouse hover).

      Default: none

  • Bar - The refinement is displayed as a bar chart with the length of each bar representing the number of items in each refinement.
    • X axis label - The value that will be displayed on the X axis of the refinement (the label for each individual refinement). It may be useful to modify this label to give measurement indicators to numerical labels. For example, to add "km" as a suffix, enter {value} km. Similarly, to indicate the labels are dollar values, enter ${value}

      Default: the value of the refinement label

    • Y axis label value suffix - The value that will be displayed on the Y axis of the refinement (the number of results for each individual refinement). If you want the axis to be unmarked, enter a space in this field.

      Default: the number of results for each individual refinement

    • Tooltip value suffix - The suffix that is applied to the refinement value when the result information is displayed (on mouse hover).

      Default: none

  • Column - The refinement is displayed as a column chart with the height of each column representing the number of items in each refinement.
    • X axis label - The value that will be displayed on the X axis of the refinement (the label for each individual refinement). It may be useful to modify this label to give measurement indicators to numerical labels. For example, to add "km" as a suffix, enter {value} km. Similarly, to indicate the labels are dollar values enter ${value}

      Default: the value of the refinement label

    • Y axis label value suffix - The value that will be displayed on the Y axis of the refinement (the number of results for each individual refinement). If you want the axis to be unmarked, enter a space in this field.

      Default: the number of results for each individual refinement

    • Tooltip value suffix - The suffix that is applied to the refinement value when the result information is displayed (on mouse hover).

      Default: none

  • Time - The refinement is displayed as a time series chart with the time series representing a time range facet.
    Note: To display a refinement as a time series chart it must be a facet with numerical values defined using the with_intervals_of faceting option.
    • X axis label - The value that will be displayed on the X axis of the refinement (the date). This value can be set to the date formats that are implemented by Highcharts, which are a subset of the formats from the PHP strftime function.

      Default: the date in MM/DD/YYYY format, where YYYY is the year, MM is the month, and DD is the day

    • Y axis label - The value that will be displayed on the Y axis of the refinement (the number of results for each individual refinement). If you want the axis to be unmarked, enter a space " " in this field.

      Default: the number of results for each individual refinement

    • Tooltip value suffix - The suffix that is applied to the refinement value when the result information is displayed (on mouse hover).

      Default: none

    • Tooltip date format - The date format that is applied to the tooltip when the result information is displayed (on mouse hover). This value can be set to the date formats that are implemented by Highcharts, which are a subset of the formats from the PHP strftime function. For example, %A, %m/%d/%Y would display the date as: weekday name, MM/DD/YYYY.

      Default: Selected automatically based on the data
Enable Toggling When on, the user can expand groups of nested or hierarchical facets. When off, these facets will be expanded by default.

Default: on
Refinements to show per level: The number of refinements to show for a tree level. When active,the top ranked refinements are listed and a link to a "show all" page appears at the bottom of the widget.

Default: 10
Refinements to show per level on the "show all" page The maximum number of refinement options to show on the "show all" refinements page, this includes all collapsed nested refinements. The highest value for this option is 500. This value should be carefully selected and well tested when refining by file path or URL to ensure a good user experience

Default: 100
Parent topic: Creating Widgets