Filters Manager

<bk-filters-manager></bk-filters-manager>

The Filters Manager manages the display, application, and modification of filters. If no filter has been applied, the Filters Manager does not render anything. Otherwise, a counter of applied filters is displayed. Upon clicking on the filters counter, a pop-up that lists such filters is displayed. Each of these can be toggled and un-toggled, removed, or it is possible to emit the request for editing it.

The Filters Manager listens to the request to add a new filter to existing ones, i.e. listens to add-filter events. A component like the Filter Drawer could be the source of such request. Applied filters are converted into a mongo-like query and propagated to other components, requesting to use such query when fetching data from the backend - that is, the query is injected into the payload of a change-query event. A component like the CRUD client listens to the change-query event and fetches data using its payload as query.

How to configure

The Filters Manager does not require any particular configuration for its most basic usage:

{
  "tag": "bk-filters-manager"
}

Bootstrap - Apply filters from URL

Upon connecting to the page, the Filters Manager parses the page URL to retrieve the query parameter filters. If found, its content is converted to filters, and the request is issued to use such filters upon data retrieval.

Hide Filters

A data-schema can be provided to the Filters Manager using property dataSchema, which might provide information for each field of the collection on how it should be used with respect to filtering.

In particular, filters on properties that include within their data-schema description the option to be hidden in filters:

{
  "filtersOptions": {
    "hidden": true
  }
}

are not included in the list of filters that is displayed by the Filters Manger. Nonetheless, the Filters Manger still requests the filter to be applied.

Persistent filters

Property saveFilters allows to save filters to local-storage. Filters are saved in local-storage through a key which can be customized with property localStorageKey, and defaults to bk-filters-manager-store- followed by the pathname of the current URL. Upon connecting to the page, the Filters Manger fetches filters from local-storage and applies them.

caution

To avoid data clashing, localStorageKey should be unique per page.

Locale

The texts of the Filters Manager can be customized through the property customLocale, which accepts an object shaped like the following:

type Locale = {
  customFilters: LocalizedText
  appliedFilter: LocalizedText
  appliedFilters: LocalizedText
  toggleFilter: LocalizedText
  untoggleFilter: LocalizedText
  deleteFilter: LocalizedText
}

where LocalizedText is either a string or an object mapping language acronyms to strings.

Examples

A Filters Manager that does not hold in its state any filter yet, with no particular configuration:

{
  "tag": "bk-filters-manager"
}

upon receiving an add-filter event with payload:

{
  "property": "name",
  "operator": "equal",
  "value": "Bruce"
}

emits a change-query event with payload:

{
  "filters": [
    {
      "property": "name",
      "operator": "equal",
      "value": "Bruce"
    }
  ]
}

And, upon receiving a second add-filter with payload:

{
  "property": "price",
  "operator": "greater",
  "value": 15
}

emits a change-query event with payload:

{
  "filters": [
    {
      "property": "name",
      "operator": "equal",
      "value": "Bruce"
    },
    {
      "property": "price",
      "operator": "greater",
      "value": 15
    }
  ]
}

API

Properties & Attributes

property	attribute	type	default	description
dataSchema	-	ExtendedJSONSchema7Definition	-	data-schema describing the fields of the collection to query
filters	-	Filter[]	[]	List of currently applied filters
hide	hide	boolean	false	Hides the rendered component
saveFilters	save-filters	boolean	false	if true, filters are automatically saved to local storage
localStorageKey	local-storage-key	strign	bk-filters-manager-storage-{pathname}	key used to identify filters saved in local-storage. Defaults to a string composed of 'bk-filters-manager-storage-' and the pathname of the current URL.

Listens to

event	action
add-filter	applies a new filter

Emits

event	description
change-query	requires data filtering
change-filter	triggers the modification of an existing filter