Configure an event handler for a Filter component

  • Release version: Washingtondc
  • Updated June 6, 2024
  • 2 minutes to read

    • On a technical dashboard, configure a special client script-based event handler for a Filter component so it can be followed by any Lists or Data Visualizations. It is not necessary to configure an event handler for filters on inline dashboards.

    Before you begin

    This procedure assumes that the following tasks are complete:
    1. You have added the Filter component to the UI Builder page, as well as at least one Data Visualization or List component. The Filter can apply to multiple Data Visualizations or Lists.
    2. You have configured the filter to source and the data to filter, if applicable, for the Filter component. If the Filter component is supposed to filter a List, you have specified the table that the List component shows as data to filter.
    3. You have configured data sources for any Data Visualization components.
    4. You have specified a table for any List components.

    Role required: ui_builder_admin, admin

    Procedure

    1. Open the relevant UI Builder page.
      This page may be a technical dashboard.
    2. Navigate to the UI Builder State section and add a state variable named parFilters of type JSON.
      For more information, see Create and bind a client state parameter to a component.
    3. Edit the parFilters variable to be a simple array with the initial value []
      1. Select the Edit control in the initial value field.

        The Edit button in the Initial Value field of the parFilters state variable.
      2. From the list of JSON initial values, select simple array.

        Simple array selected from the list of initial values when editing the parFilters variable.
      3. Select Apply.
        The result is a JSON state variable with a simple array as the initial value.
        Final form of parFilters as a JSON state variable with an empty simple array as the initial value.
    4. Add a second state variable named encodedQueries of type JSON with initial value {}.
    5. Navigate to the Client Scripts section and create a custom script with a name such as "Apply PAR Filters" and the following content or a functional equivalent thereof: 
      function handler({ api, event, helpers, imports }) {
	const mergePARFiltersV2 = imports["global.mergePARFilters"]().v2;
	const { appliedFilters } = event.payload;
	api.setState("parFilters", ({ currentValue, api }) => {
		const { parFilters, encodedQueries } = mergePARFiltersV2(
			currentValue,
			appliedFilters
		);
		api.setState("encodedQueries", encodedQueries);
		return parFilters;
	});
}
    6. In the Client Scripts section, open the Client Script Includes tab.

      The Client Script Includes tab of the Client Scripts pane on a UIB page.
    7. In the Add a script include field, select mergePARFilters and click Add.

      Adding the mergePARFilters script include.
    8. Close the window for configuring data, client state, and client scripts.
    9. In the UI Builder, select the Filter component.
    10. Select the Events tab in the configuration panel and add the page script you have created, which in our example is Apply PAR Filters, as an event handler.

      Adding the Apply PAR Filters script as the Filter applied event handler.
    11. In the UI Builder, select a List component, if one exists.
    12. Select Edit fixed filter and set this property [fixedQuery] as the dynamic binding expression @state.encodedQueries.<list-datasource>.
      Replace <list-datasource> with the data source for the List component. For example, if your List shows records from the Incident [incident] table, enter @state.encodedQueries.incident.
      In the fixed filter field on a List config panel, binding the fixedQuery property to the encodedQueries client state parameter.
    13. Repeat the previous two steps for any other List components.
    14. Save the page.