Skip to Main Content

Interface: facetsRegion

QuickNav

Properties

Events

Methods

Type Definitions

facetsRegion

The facetsRegion interface is used to access the properties and methods of the facets API which is used by both the Faceted Search and Smart Filters regions. You get access to the facetsRegion interface with the apex.region function when passed the regionId (static ID) of either a Faceted Search Region or Smart Filters Region. The terms facet and filter (when used as a noun) are often used interchangeably.

The facetsRegion provides the user interface used to search and filter an associated report. The Faceted Search and Smart Filters regions have a great deal of overlap in their functionality; both allow searching and filtering a report. The biggest difference is in the UI and this is controlled by the facetsRegion#uiMode property. A number of properties are only supported in one mode or the other as noted in the description of each property.

Report region plug-in developers use the facetsRegion API to support the client side of faceted search for their plug-in. The plug-in server-side render code must pass the static ID of the Faceted Search or Smart Filter region to the client as part of its configuration. The plug-in region must listen for the facetsRegion#event:change event and refresh the report in response. Before sending the ajax request to refresh the report it must call facetsRegion#lock and after the response completes it must call facetsRegion#unlock.

Facet Items

Users filter the report by choosing or entering value(s) for as many facets as needed. The facet value is used to match a specific column. Users can also enter a search term that matches any of the searchable columns of the report. Each facet value and the search term(s) is stored in a hidden page item and has a corresponding session state value. The item name is the filter or facet name.

For example, if there is a facet or filter with name P1_PROJECT_STATUS that has LOV return values: 'OPEN', 'IN_PROGRESS', 'CLOSED', and 'REOPENED'. Setting the page item will cause the facets region and the report region to be updated to reflect the new facet value(s). After executing the following code the report will show any records that have project status of OPEN or REOPENED.

apex.item( "P1_PROJECT_STATUS" ).setValue( "OPEN:REOPENED" );

Note that multiple values are separated by a colon ":" and facet values that represent a range use vertical bar "|" to separate the min and max range values.

Flexible Operators

When using facets of type "Input Field" and "User can Choose Operator" is activated then the operator can be set by changing the facet value.

For example, if there is a facet or filter with name P1_POPULATION, then report region can be filtered for all countries where population is equal to a specific value. After executing the following code the report will show any records that have equals to 1000.

apex.item( "P1_POPULATION" ).setValue( "EQ:1000" );

The following operators are available:

  • General
    • EQ: Equals
    • NEQ: Not equals
  • NUMBER
    • LT: Less than
    • LTE: Less than or equal to
    • GT: Greater than
    • GTE: Greater than or equal to
  • VARCHAR2
    • STARTS": Starts with
    • NSTARTS: Does not start with
    • C: Contains
    • NC: Does not contain
Since:
  • 21.2

Extends

Properties

batch :boolean

Batch facet control changes or not. Batching changes allows the user to make a number of selections before the report refreshes. In some cases this can make searching more efficient.

When true, the facetsRegion#event:change event is delayed until an "apply" button is pressed. When facetsRegion#uiMode is "F" (faceted search mode) there will be an apply button shown (unless facetsRegion#externalApply is true). When facetsRegion#uiMode is "S" (smart filter mode) changes are applied when the the facet popup is closed.

When false, the facetsRegion#event:change event is fired as soon as any facet control value changes.

Type:
  • boolean
Default Value:
  • true
Example

Get or set option batch after initialization.

// get
var value = apex.region( "myRegionId" ).batch;
// set
apex.region( "myRegionId" ).batch = false;

chartTopNValues :number

The default maximum number of values to show in a facet chart.

Type:
  • number
Default Value:
  • 10
Example

Get or set option chartTopNValues after initialization.

// get
var value = apex.region( "myRegionId" ).chartTopNValues;
// set
apex.region( "myRegionId" ).chartTopNValues = 20;

clearOnHide :boolean

Controls if facet values are cleared when hidden by the facet configuration popup (More Filters). This option is not applicable when facetsRegion#uiMode is "S" (smart filter mode)

Type:
  • boolean
Default Value:
  • true
Example

Get or set option clearOnHide after initialization.

// get
var value = apex.region( "myRegionId" ).clearOnHide;
// set
apex.region( "myRegionId" ).clearOnHide = false;

collapsibleSearchBar :boolean|null

This determines if the search bar is collapsible. If null (the default) the search bar is collapsible on mobile sized screens but not on desktop (larger) screens. If true the searchbar is always collapsible. If false the searchbar is not collapsible. When collapsible and there are no filters the search input field is not shown and the suggestions, if any, are on one line. This only applies when facetsRegion#uiMode is "S" (smart filter mode) and facetsRegion#maxChips is not 0.

Type:
  • boolean | null
Default Value:
  • null
Example

Get or set option collapsibleSearchBar after initialization.

// get
var value = apex.region( "myRegionId" ).collapsibleSearchBar;
// set
apex.region( "myRegionId" ).collapsibleSearchBar = true;

controls :Array.<facetsRegion.control>

An array of facet control objects. Required. The controls are set according to the region facet or filter configuration.
Type:

currentFacets :string|boolean

Controls if and where the list of current (applied) facet choices are shown. This is known as the current facets area. If a string, it is the selector of an element to render the list of current facet values in. If true the list of current facets is added at the top of the facets region. If false or not present there is no list of current facets.

This option can only be set during initialization. When facetsRegion#uiMode is "S" (smart filter mode) this option is forced to be false because applied facets are always shown in the search bar.

Type:
  • string | boolean
Default Value:
  • true
Example

Get option currentFacets after initialization.

var value = apex.region( "myRegionId" ).currentFacets;

element :jQuery

The jQuery object for the region element.

Type:
  • jQuery
Inherited From:
Example

Get option element after initialization.

var value = apex.region( "myRegionId" ).element;

externalApply :boolean

Only applies if facetsRegion#batch is true and facetsRegion#uiMode is "F" (faceted search mode). If true no apply button is shown. Used when facets are in a dialog or popup or otherwise have some other external way to apply the changes. See the facetsRegion#apply method.

Type:
  • boolean
Default Value:
  • false
Example

Get or set option externalApply after initialization.

// get
var value = apex.region( "myRegionId" ).externalApply;
// set
apex.region( "myRegionId" ).externalApply = true;

feedback :boolean

If true the facet control values give feedback (counts) about how many resources match the facet value. If false there is no feedback. Feedback can also be configured on a per facet basis with the hasFeedback property of a control. See facetsRegion.control.

This option can only be set during initialization.

Type:
  • boolean
Default Value:
  • true
Example

Get option feedback after initialization.

var value = apex.region( "myRegionId" ).feedback;

filterRegionId :string

For region plug-ins which support Faceted Search / Smart Filters it is possible to pass in the DOM ID of the facetsRegion region in order for APEX to bind the two together. If provided, the region will be automatically refreshed as the filters change. Further, if the region's refresh callback returns a Promise, APEX will also automatically perform the appropriate locking and unlocking of the facetsRegion region during refresh.

Type:
  • string
Inherited From:

maxChips :number

The maximum number of suggestion filter chips to show at a time. If 0 the suggestion filter chips area is not shown. If -1 then all available facet suggestions are shown. The facetsRegion#moreFiltersChip option is only useful when this value is positive.

This only applies when facetsRegion#uiMode is "S" (smart filter mode) and is ignored otherwise.

Type:
  • number
Default Value:
  • 5
Example

Get or set option maxChips after initialization.

// get
var value = apex.region( "myRegionId" ).maxChips;
// set
apex.region( "myRegionId" ).maxChips = 6;

moreFiltersChip :boolean

Determine if a special "more filters" chip is shown in the suggestion filter chips area. When clicked this chip shows a list of available filers to choose and filer the report on.

This only applies when facetsRegion#uiMode is "S" (smart filter mode) and is ignored otherwise. See also facetsRegion#maxChips.

Type:
  • boolean
Default Value:
  • true
Example

Get or set option moreFiltersChip after initialization.

// get
var value = apex.region( "myRegionId" ).moreFiltersChip;
// set
apex.region( "myRegionId" ).moreFiltersChip = false;

multipleSearches :boolean

Specify if multiple searches are allowed. If true the report can be filtered by multiple search terms. Each search term must match some part of a record for it to be included in the report. (This means that search term conditions are combined with AND.) If false only a single search term is allowed. When facetsRegion#uiMode is "S" (smart filter mode) this option is forced to be true and cannot be changed.

Type:
  • boolean
Default Value:
  • false
Example

Get or set option multipleSearches after initialization.

// get
var value = apex.region( "myRegionId" ).multipleSearches;
// set
apex.region( "myRegionId" ).multipleSearches = true;

numberFormat :string|boolean

Controls if and how numbers for facet value counts and total count are formatted. If false the numbers are not formatted. If true the numbers are formatted using compact format (with no fractional digits) for numbers greater than or equal to the facetsRegion#numberFormatThreshold and a default format model with group separators otherwise. The facetsRegion#numberFormatOptions are not used. If a string: it is a database number format model or the keyword "compact".

Type:
  • string | boolean
Default Value:
  • true
Example

Get or set option numberFormat after initialization.

// get
var value = apex.region( "myRegionId" ).numberFormat;
// set
apex.region( "myRegionId" ).numberFormat = "999G999G999G999";

numberFormatOptions :object

Options to pass to the number formatting function. The available option properties depend on the value of facetsRegion#numberFormat. See apex.locale.formatNumber and apex.locale.formatCompactNumber.

Type:
  • object
Default Value:
  • null
Example

Get or set option numberFormatOptions after initialization.

// get
var value = apex.region( "myRegionId" ).numberFormatOptions;
// set
apex.region( "myRegionId" ).numberFormatOptions = {
    maximumFractionDigits: 1
};

numberFormatThreshold :number

See facetsRegion#numberFormat. Only applies if facetsRegion#numberFormat is true. If null and numberFormat is true then the default format model with group separators is used.
Type:
  • number
Default Value:
  • null
Example

Get or set option numberFormatThreshold after initialization.

// get
var value = apex.region( "myRegionId" ).numberFormatThreshold;
// set
apex.region( "myRegionId" ).numberFormatThreshold = 1000;

persistState :boolean

Persist facet control collapsed state and chart state in browser session storage or not.

Type:
  • boolean
Default Value:
  • true
Example

Get or set option persistState after initialization.

// get
var value = apex.region( "myRegionId" ).persistState;
// set
apex.region( "myRegionId" ).persistState = false;

searchButton :string

The id of a button that initiates the search. Only applies if facetsRegion#searchField is a string page item id. If this value is changed call facetsRegion#refreshView.

Type:
  • string
Default Value:
  • null
Example

Get or set option searchButton after initialization.

// get
var value = apex.region( "myRegionId" ).searchButton;
// set
apex.region( "myRegionId" ).searchButton = "P1_SEARCH_BUTTON";

searchField :string|boolean

This controls the search field. If true a search field is included in the facets area. If false there is no search field. If a string it is the ID of a page item input field to use as the search field When facetsRegion#uiMode is "S" (smart filter mode) this option is forced to be true and cannot be changed.

Type:
  • string | boolean
Default Value:
  • false
Example

Get or set option searchField after initialization.

// get
var value = apex.region( "myRegionId" ).searchField;
// set
apex.region( "myRegionId" ).searchField = "P1_SEARCH";

searchItem :string

Name of the search item. Required if facetsRegion#searchField is not false.

Type:
  • string
Default Value:
  • null
Example

Get option searchItem after initialization.

var value = apex.region( "myRegionId" ).searchItem;

showCharts :string|boolean

Determines if facets can have a button to show a chart of facet counts. If true a chart for a single facet can be shown in a dialog (or popup). If false no charts can be shown. If a string it is the selector of an element to render the charts in.

Charts can also be shown with the facetsRegion#addChart method unless this option is false. When facetsRegion#uiMode is "S" (smart filter mode) there is no built-in UI for the user to show charts. The require and JET chart libraries and JET CSS must be available. This is done automatically by the Faceted Search region but not the Smart Filters region.

Type:
  • string | boolean
Default Value:
  • false
Example

Get or set option showCharts after initialization.

// get
var value = apex.region( "myRegionId" ).showCharts;
// set
apex.region( "myRegionId" ).showCharts = true;

showTotalCount :string|boolean

Controls if and where the total count is shown. If a string, it is a selector of an element to display the current total resources count in. If true show the total count in the current facets area or if there is no current facets area show it where the current facets area would be if it were true. If false don't show the total count. This is forced to false if feedback is false.

Type:
  • string | boolean
Default Value:
  • true
Example

Get option showTotalCount after initialization.

var value = apex.region( "myRegionId" ).showTotalCount;

text :object

Object containing translatable strings. All required.

Type:
  • object
Properties:
Name Type Description
searchLabel string Accessible label for the search input field or search button. Only used when facetsRegion#searchField is true.
searchPlaceholder string Placeholder text for the search input field. Only used when facetsRegion#searchField is true.
totalCountLabel string Label to show before the total results count. Only used when facetsRegion#showTotalCount is true.
Example

Get option text after initialization.

var value = apex.region( "myRegionId" ).text;

type :string

The facetsRegion type is "Facets".

Type:
  • string
Overrides:

uiMode :string

Controls the UI mode of the region. It is one of the following values:

  • "F" This is traditional faceted search mode. This is the value set by the Faceted Search region.
  • "S" This is smart filter search mode. This is the value set by the Smart Filters region.

This option property cannot be changed after initialization. A number of other options and methods are affected by this property setting.

Type:
  • string
Default Value:
  • "F"
Example

Get option uiMode after initialization.

var value = apex.region( "myRegionId" ).uiMode;

Events

afterRemoveChart

Triggered just after a chart is removed from the charts dashboard area. This is the same as the Dynamic Action event: After Remove Chart [Faceted Search].

Properties:
Name Type Description
event Event jQuery event object.
data Object
Properties
Name Type Description
count number Number of active charts now that this one is removed.
chartName string The name of the chart. It is the same as the facet item.
Example

In this example charts are shown in a collapsible dashboard region. When the last chart is removed the collapsible region needs to be collapsed.

apex.region( "myRegionId" ).on( "facetsafterremovechart", function( event, data ) {
    if ( data.count === 0 ) {
        apex.theme.closeRegion( "myDashboardRegionId" );
    }
} );

beforeAddChart

Triggered just before a new chart is added to the charts dashboard area. This is the same as the Dynamic Action event: Before Add Chart [Faceted Search].

Properties:
Name Type Description
event Event jQuery event object.
data Object
Properties
Name Type Description
count number Number of active charts after this one is added.
chartName string The name of the chart. It is the same as the facet item.
chart Element The chart Element added. This is the wrapping element that contains the title, buttons, and chart.
Example

In this example charts are shown in a collapsible dashboard region. When the first chart is added the collapsible region needs to be expanded.

apex.region( "myRegionId" ).on( "facetsbeforeaddchart", function( event, data ) {
    if ( data.count === 1 ) {
        apex.theme.openRegion( "myDashboardRegionId" );
    }
} );

change

Triggered when one or more facet control values have changed. It has no additional data. This is the same as the Dynamic Action events: Facets Change [Faceted Search] and Filters Change [Smart Filters].

Properties:
Name Type Description
event Event jQuery event object.
Example

The report region associated with the Smart Filter or Faceted Search region will automatically refresh when facet values change but if you have other regions on the page that also need to refresh listen for this event. The following will refresh region "extraReport" when facet values change.

apex.region( "myRegionId" ).on( "facetschange", function( event ) {
    apex.region( "extraReport" ).refresh();
} );

Methods

addChart(pFacetName, pAppendTo$opt, pConfigopt)

Add/show a chart for the given facet.

See also facetsRegion#removeChart.

Parameters:
Name Type Attributes Description
pFacetName string The facet to add a chart for.
pAppendTo$ jQuery <optional>
 The element to append the chart to. If not specified then the chart is shown according to the facetsRegion#showCharts property. The facetsRegion#showCharts option must not be false if appendTo$ is not specified.
pConfig object <optional>
 Optional chart configuration.
Properties
Name Type Description
type string The chart type. One of "bar", "pie".
topN number Maximum number of values to show in the chart
Examples

This example shows a chart for the P1_SAL facet in a non-modal dialog.

apex.region( "myRegionId" ).addChart( "P1_SAL" );

This example adds a pie chart for the P1_JOB facet in dashboard area div with id "#chartDashbord".

apex.region( "myRegionId" ).addChart( "P1_JOB", $( "#chartDashboard" ), {type: "pie"});

apply()

Apply any outstanding changes to facet values. This method is intended for when both facetsRegion#batch and facetsRegion#externalApply are true.

Example

In this example the batch and externalApply properties are true and the page has a button with id "myApplyButton". The user clicks this button to apply facet choices.

$( "#myApplyButton" ).on( "click", function() {
    apex.region( "myRegionId" ).apply();
}

clear()

Clear all the current (applied) facet values and any search terms.

See also facetsRegion#clearFacets.

Example

This example clears all the facet and search term values when the button with id CLEAR_BUTTON is pressed.

$("#CLEAR_BUTTON").on( "click", function() {
    apex.region( "regionId" ).clear();
} );

clearFacets()

Clear all the current (applied) facet values. Search terms if any are not cleared.

See also facetsRegion#clear.

Example

This example defines an action that will clear all the facet values when the keyboard shortcut Ctrl+/,X is pressed. The action could also be associated with a menu item and/or button. See also actions#add.

apex.actions.add( [ {
    name: "clear-search",
    label: "Clear Filters",
    shortcut: "Ctrl+/,X",
    action: function() {
        apex.region( "regionId" ).clearFacets();
    }
} ] );

fetchCounts()

Refreshes the counts for all the facets. This is useful if the report is also filtered by controls, such as page items, that are external to the facets region and those external control values have changed.

See also facetsRegion#refresh.

Example

In this example there is an input element with id P1_EXTERNAL_FILTER and when it changes the report is refreshed so the facet counts must also be refreshed.

$("#P1_EXTERNAL_FILTER").on( "change", function() {
    apex.region( "regionId" ).fetchCounts();
} );

focus()

Focus the first tabbable element. In faceted search mode (facetsRegion#uiMode is "F") the search input field is focused if facetsRegion#searchField is true or the first facet control body otherwise. In smart filter mode (facetsRegion#uiMode is "S") the search bar search input field or search button is focused.

Overrides:
Example

This example puts focus in the Faceted Search or Smart Filters region.

apex.region( "myRegionId" ).focus();

getFacetCount(pIncludeSearchTerms) → {number}

Returns the number of facets that have a non-empty value. This is useful when the facet UI is not always visible (for example it is in a collapsible or dialog region) and you wish to display how many filters are applied.

Parameters:
Name Type Description
pIncludeSearchTerms boolean If true the search terms are included in the count.
Returns:
Type
number

getFacetValueCounts() → {object}

Returns an object structure with all the counts displayed by the facets UI.

Returns:
Facet value counts. The object properties are the facet control names. The value of each property is an object with the facet value as the property and the count as the property value.
Type
object

getTotalResourceCount() → {number}

Returns the total number of resources (records) in the report. This is the same value displayed by the facetsRegion#showTotalCount property, except it is not formatted. Returns null if facetsRegion#feedback property is false.

Returns:
Type
number
Example

This example logs the number of records in the report to the console.

console.log("Total records is ", apex.region( "regionId" ).getTotalResourceCount() );

hideFacet(pFacetName)

Hides the specified facet. Note that hiding a facet does not clear any value(s) that may currently be filtering the report.

In faceted search mode (facetsRegion#uiMode is "F") the facet header and all choices or other selection UI are hidden. If the displayed control property is not "A" (for always) then the facet is still available for the user to select on the "More Filters" popup.

In smart filter mode (facetsRegion#uiMode is "S") the hidden facet will not show in the suggestion chip area or in the suggestion drop down.

See also facetsRegion#showFacet.

Parameters:
Name Type Description
pFacetName string
Examples

This example hides the facet named "P1_COMM".

apex.region( "myRegionId" ).hideFacet( "P1_COMM" );

This example hides the facet named "P1_COMM" and also clears any values it may have.

apex.item( "P1_COMM" ).setValue( "" );
apex.region( "myRegionId" ).hideFacet( "P1_COMM" );

lock()

Disables the facets region so that facet values cannot be changed through the UI or API. This is done by the report region associated with this facets region so that multiple requests are not sent to the server at the same time. For every call to facetsRegion#lock there must be a corresponding call to facetsRegion#unlock.

See facetsRegion#unlock.

Examples

This example shows how a report region plug-in would listen for facet value changes and call lock and unlock. 

// ajaxIdentifier and facetsStaticId are passed into the report plug-in
if ( facetsStaticId ) {
    let facetsRegion = apex.region( facetsStaticId );
    facetsRegion.widget().on( "facetschange", function() {
        facetsRegion.lock();
        let p = apex.server.plugin( ajaxIdentifier, ... );
        ...
        p.always( function() {
            facetsRegion.unlock();
        } );
    } );
}

This example shows how to set multiple facet item values but only cause the report and facet counts to be updated once. The region static id is "empFacets" and P2_JOB and P2_MGR are 2 of the facet names.

let facets = apex.region( "empFacets" );
facets.lock();
$s("P2_JOB", "CLERK");
$s("P2_MGR", "7698");
facets.unlock(); // only after this will the report and counts be updated

off(events, …args)

Removes an event handler from the widget element associated with this region. This method only applies to regions that are implemented with a jQuery UI style widget. This means that region#widgetName property must be defined and the region#widget method returns a value.

This is a shortcut for calling apex.region(id).widget().off(...). Unlike the jQuery object off method this does not return the jQuery object and therefore is not chainable. See the jQuery documentation for details.

See also region#on.

Parameters:
Name Type Attributes Description
events One or more space-separated event types and optional namespaces as defined by the jQuery off method. For events defined by this region widget the event name prefix can be omitted.
args * <repeatable>
 Other arguments to be passed to the widget's jQuery object off method such as selector, data, and handler.
Inherited From:
Example

This example removes all event handlers for the selectionChange event of an Interactive Grid region. Note that the short event name "selectionChange" can be used rather than the full name "interactivegridselectionchange". See also interactiveGrid#event:selectionchange.

apex.region( interactiveGridRegionId ).off( "selectionChange" );

on(events, …args)

Attaches an event handler to the widget element associated with this region. This method only applies to regions that are implemented with a jQuery UI style widget. This means that region#widgetName property must be defined and the region#widget method returns a value.

This is a shortcut for calling apex.region(id).widget().on(...). Unlike the jQuery object on method this does not return the jQuery object and therefore is not chainable. See the jQuery documentation for details.

See also region#off.

Parameters:
Name Type Attributes Description
events One or more space-separated event types and optional namespaces as defined by the jQuery on method. For events defined by this region widget the event name prefix can be omitted.
args * <repeatable>
 Other arguments to be passed to the widget's jQuery object on method such as selector, data, and handler.
Inherited From:
Example

This example handles the selectionChange event of an Interactive Grid region by logging a message to the console. Note that the short event name "selectionChange" can be used rather than the full name "interactivegridselectionchange". See also interactiveGrid#event:selectionchange

apex.region( interactiveGridRegionId ).on( "selectionChange", function(event, data) {
    console.log("Selection changed; # records selected is", data.selectedRecords.length );
} );

refresh()

This is a convenience method that simply calls the facetsRegion#fetchCounts method.

Overrides:

refreshView()

Renders and initializes the facets UI.

Example

This example refreshes the view.

apex.region( "regionId" ).refreshView();

removeChart(pFacetName)

Remove the chart for the given facet.

See also facetsRegion#addChart.

Parameters:
Name Type Description
pFacetName string The facet name of the chart to remove.
Example

This example removes the chart for the P1_SAL facet.

apex.region( "myRegionId" ).removeChart( "P1_SAL" );

reset()

Clears all filters and search terms and resets any persistent settings to their original configured values.

Example

This example resets the region.

apex.region( "regionId" ).refreshView();

showFacet(pFacetName)

Shows the specified facet. There are a few facetsRegion#control properties that also control if a facet is shown or hidden: displayed, visibleCondition, lovDependsOnRequired. When displayed is "A" (for always) the facet can still be shown or hidden programmatically. When a facet is automatically conditionally displayed due to cascading list of values where the parent is required (lovDependsOnRequired) or a depending on facet (visibleCondition) it is best not to programmatically show or hide it.

See also facetsRegion#hideFacet.

Parameters:
Name Type Description
pFacetName string
Example

This example shows the facet named "P1_COMM".

apex.region( "myRegionId" ).showFacet( "P1_COMM" );

unlock()

Enables the facets region after it was previously disabled with facetsRegion#lock so that facet values can be changed again. For every call to facetsRegion#lock there must be a corresponding call to facetsRegion#unlock.

See facetsRegion#lock.

Example

See facetsRegion#lock for examples.

Type Definitions

checkboxControl

Checkbox specific options Note the checkbox type can only be in a group. This means it must follow a group control or be in the facets array of a group item. It is different from other facet controls in that it does not form its own group. The label is the label of the checkbox. So some of the common control properties such as collapsible and maxHeight don't apply and are simply ignored. Some properties take their value from the group the checkbox is in.
Type:
  • object
Properties:
Name Type Description
value string Control return value when checked
icon string Icon CSS class
escape boolean If false allows markup in the label. Otherwise markup is escaped.
altLabel string {string} label to use in currentFacets and charts. Useful when the label contains markup.

control

Facet control option properties that configure the look and behavior of a facet.

A note about facet visibility: There are 3 options that can affect if a facet is shown: displayed, visibleCondition, and lovDependsOn. There is little coordination between these options. In general, the last one evaluated wins (gets to say if the facet is visible or not).

See also listControl, facetsRegion#rangeControl.

Type:
  • object
Properties:
Name Type Description
name string The item/session state name
type string One of "list", "range", "rangeList", "selectList", "group", "checkbox", "input"
label string The UI label to show for the facet control.
includeLabel boolean Determines if the facet label is also displayed when a facet value is shown standalone such as in the current facets area in faceted search mode or as a suggestion facet chip in smart filters mode.
icon string Icon CSS classes to show before the facet label in faceted search mode and in the suggestions drop down in smart filters mode.
cssClasses string Additional classes to set on the facet control. In faceted search mode the class is added to the facet control element with class 'a-FS-control'. In smart filters mode the class is added to the suggestion chip element with class 'a-Chip' and to the popup element with class 'a-FS-body'.
collapsible boolean Determines if the the facet control can be collapsed. Only applies when facetsRegion#uiMode is "F" (faceted search mode).
initialCollapsed boolean When collapsible is true this determines if the facet control is initially collapsed. Only applies when facetsRegion#uiMode is "F" (faceted search mode).
maxHeight integer The maximum height of the facet control values area. If the facet has more values than will fit in this height then they will scroll. Only applies when facetsRegion#uiMode is "F" (faceted search mode).
clearBtn boolean If true the control will have a clear button shown when it has a value. Default true. When facetsRegion#uiMode is "S" (smart filters mode) this does not apply and is set to false.
hasFeedback boolean If true then this control expects to get feedback about how many matching resources are available. The default comes from option facetsRegion#feedback.
displayed string Controls when the facet control is displayed. The value is one of 'A', 'S', 'H' (A=Always, S=Show Initially, H=Hide Initially). When not 'A' the user can show or hide the facet. Only applies when facetsRegion#uiMode is "F" (faceted search mode).
visibleCondition object A condition object as described by apex.util.checkCondition. This controls the visibility of the facet. When the condition is true the facet if visible. When not visible the facet will have no value.
showChart boolean Default true. Only applicable for LOV related controls and if showCharts, hasFeedback and showCounts is true.
initialChart boolean Default false. Only applies if showChart is applicable and true and showCharts is a string.
suggestedValues boolean | array Determines if a facet suggestion chip is displayed in the suggestion filter chips area and if so what value to suggest. If true the value with the largest count or first value of a LOV facet is used as the suggestion value. If false this facet is not included in the suggestion filter chip area. If an array it is an array of facet values. The first value that has a non-zero count is used. Only applies when facetsRegion#uiMode is "S" (smart search mode).
* facetsRegion.listControl | facetsRegion.rangeControl | facetsRegion.selectListControl | facetsRegion.checkboxControl | facetsRegion.inputControl Additional type specific properties.

inputControl

Input specific options
Type:
  • object
Properties:
Name Type Description
dataType string The datatype of the value to enter and the facet value to compare with. The comparison operator is controlled by the server. One of "NUMBER", "VARCHAR2", "DATE", "TIMESTAMP", "TIMESTAMP WITH TIME ZONE", "TIMESTAMP WITH LOCAL TIME ZONE"
formatMask string Format Mask of the input when facet is based on dataType "DATE", "TIMESTAMP", "TIMESTAMP WITH TIME ZONE", "TIMESTAMP WITH LOCAL TIME ZONE"
inputLabel string Label to show before the input.
suffixText string {string} Text to show after the input.
currentLabel string {string} Label used for the current facets area. Example: "Within %0 miles" When dataType is "NUMBER":
min number Minimum value user is allowed to enter
max number Maximum value user is allowed to enter
step number Number input step increment

listControl

These are additional options for controls that have a list of values (LOV). These options apply to the facet control types 'list' and 'rangeList'

Type:
  • object
Properties:
Name Type Description
escape boolean If false allows markup in the values display values. Otherwise markup is escaped.
multiple boolean If true the user can select multiple values from the list. (checkboxes)
showCounts boolean Default true. Only applicable if hasFeedback is true.
hideEmpty boolean If true values with 0 count are hidden if false values with 0 count are visually "disabled"
lovDependsOn string Parent cascading LOV parent facet name. When the parent changes, new values are requested from the server.
lovDependsOnRequired boolean If true the lovDependsOn parent must have a value for this facet to have any values. This only applies when lovDependsOn is specified.
values Array.<object> LOV array of objects with these properties
Properties
Name Type Attributes Description
r string Return value
d string Display value
l string <optional>
 Optional display value without markup. Only needed when display value includes markup if no l property and escape is false fall back to stripHTML on display value (d).
i string <optional>
 Icon CSS Classes for value
g boolean <optional>
 Indicates that this list item represents a group not a value.
filterValues boolean If true the user can filter the list of values to make it easy to find a particular value.
listClasses string extra classes to add to the list grouping element
showAllCount number If the list contains more than this number of items a "Show all" control is shown. Only applies when facetsRegion#uiMode is "F" (faceted search mode).
showAllGrace number Default 1. If the number of items is withing this amount of the showAllCount don't bother with showMore behavior. Only applies if showAllCount is given. This solves the problem of clicking show more/all only to find for example 1 more item.
orderByCount boolean If true the items are ordered by the count descending (after checked items if checkedFirst is true).
checkedFirst boolean If true any selected items are shown first. Not supported if values are grouped.
disabledLast boolean If true any disabled items are shown last. Only applies if hasFeedback is true. Not applicable if hideEmpty is true. Not supported if values are grouped.
hideRadioButton boolean Only applies when multiple is false. Uses bold label rather than radio button to indicate selected item
noManualEntry boolean Only applies to rangeList. If true the manual range entry controls are not added.
actionsFilter boolean If true adds the action Filter to the facet context menu. The default is false. Only applies when facetsRegion#uiMode is "F" (faceted search mode).

rangeControl

These are additional options for controls that allow a range defined by a start and end value. These options apply to the facet control types 'range' and 'rangeList' (unless noManualEntry is true).

Type:
  • object
Properties:
Name Type Description
allowOpen boolean If true manual entry open ended ranges are allowed. Default false.
prefixText string Text to display before the range input fields. Example: "$".
suffixText string Text to display after the range input fields. Example: "mph".
rangeText string Text displayed between the 2 range input fields. Example: " - ".
currentLabel string Label used for the current facets area. Example: "$%0 to $%1"
currentLabelOpenHi string Label used for the current facets area. Example: "Over $%0"
currentLabelOpenLow string Label used for the current facets area. Example: "Under $%0"
min number Minimum value user is allowed to enter. When dataType is number:
max number Maximum value user is allowed to enter. When dataType is number:
step number Number input step increment. When dataType is number:
dataType string The datatype of the value to enter and the facet value to compare with. The comparison operator is controlled by the server. One of "NUMBER", "VARCHAR2", "DATE", "TIMESTAMP", "TIMESTAMP_TZ", "TIMESTAMP_LTZ"
formatMask string Format Mask of the input when facet is based on dataType "DATE", "TIMESTAMP", "TIMESTAMP_TZ", "TIMESTAMP_LTZ"

selectListControl

These are additional options for select list controls. These options apply to the facet control types 'selectList'.

Type:
  • object
Properties:
Name Type Description
showCounts boolean Default true. Only applicable if hasFeedback is true.
hideEmpty boolean If true values with 0 count are hidden if false values with 0 count are visually "disabled"
lovDependsOn string Parent cascading LOV parent facet name. When the parent changes, new values are requested from the server.
lovDependsOnRequired boolean If true the lovDependsOn parent must have a value for this facet to have any values. This only applies when lovDependsOn is specified.
values Array.<object> Same as for list type.
nullLabel string This is the label for the first option, which used to unselect all others. It represents no facet value selected. This is not the same as the List of Values: Include Null Option. Required.