Expandable Filters

<bk-expanded-filters></bk-expanded-filters>

The Expandable Filters consist in a form which allows to apply filters to a collection. Each field of the form is associated to a field of the collection and to a filter operator. Upon submitting the form:

• inserted values for each field are used to create an array of filters with the corresponding associated collection field and filter operator. No filter is applied for fields without values.
• The need to filter the data according to such filters is signaled to other components. This is achieved by emitting a change-query event. Components such as the CRUD Client might pick up on this request. Note that, differently from the Filter Drawer, the Expandable Filters are not designed to interact with the Filters Manager.

The form is hidden/spawned whenever the request to provide support for applying filters is signaled. That is, whenever a filter event is received.

The fields within the form are organized into a grid with a maximum number of columns of 4, which shrinks to 3 or 2 depending on the window width.

How to configure

Properties dataSchema and filtersConfig should be specified in the Expandable Filters configuration.

{
  "tag": "bk-expanded-filters",
  "properties": {
    "dataSchema": {
      "type": "object",
      "properties": {
        "dishes": {"type": "array", "format": "multilookup"},
        "name": {"type": "string"},
        "orderedAt": {"type": "string", "format": "date-time"},
      }
    },
    "filtersConfig": [
      {
        "property": "orderedAt",
        "operator": "between"
      },
      "dishes",
      "name"
    ]
  }
}

The data-schema describes the structure of the underlying data, while filtersConfig specifies the fields to show and their associated collection property and filter operator. filtersConfig is an array of strings and/or objects with keys "property" and "operator". String entries are interpreted as the collection property to associate to the field, and a default operator is used. The default operator is always equal unless the property is of format multilookup, in which case includesAll is used. It is not possible to specify the same property more than once.

Properties with filterOptions.hidden set to true in the data-schema are not shown.

caution

Filters on properties of type array or object are not available, unless they have format lookup of multilookup (only for array field).

Bootstrap - Apply filters from URL

If property readFromUrl is set to true, the Expandable Filters parse the page URL to retrieve the query parameter filters. If found, its content is converted to filters that are used to initialize the form values and are applied accordingly to filtersConfig.

Lookup fields (writable views)

Fields described inside the data-schema as having type object or array and format lookup are rendered respectively as select and multi-select fields.

Options for such fields will be dynamically fetched from the endpoint specified in basePath property, using the /lookup route provided by the CRUD Service to writable views (version 6.9.0 or higher) , which returns a list of objects. Each option fetched like this should have at least a label field, which is used as display value inside the form, and a value field which is used as unique identifier for such option.

caution

If you use the _id field as value in your lookups, remember to set its type as string.

Locale

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

type Locale = {
  buttons: {
    applyButton: LocalizedText
    clearButton: LocalizedText
  },
  valueInputPlaceholder: LocalizedText
  valueSelectPlaceholder: LocalizedText
  true: LocalizedText
  false: LocalizedText
  datePicker: {
    lang: {
      locale: LocalizedText,
      placeholder: LocalizedText
      rangePlaceholder: {
        start: LocalizedText
        stop: LocalizedText
      },
      today: LocalizedText
      now: LocalizedText
      backToToday: LocalizedText
      ok: LocalizedText
      clear: LocalizedText
      month: LocalizedText
      year: LocalizedText
      timeSelect: LocalizedText
      dateSelect: LocalizedText
      monthSelect: LocalizedText
      yearSelect: LocalizedText
      decadeSelect: LocalizedText
      monthBeforeYear: 'true' | 'false'
      previousMonth: LocalizedText
      nextMonth: LocalizedText
      previousYear: LocalizedText
      nextYear: LocalizedText
      previousDecade: LocalizedText
      nextDecade: LocalizedText
      previousCentury: LocalizedText
      nextCentury: LocalizedText
    },
    timePickerLocale:{
      placeholder: LocalizedText
    }
  }
}

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

Examples

Example: Basic Usage

Given the following configuration,

{
  "tag": "bk-expanded-filters",
  "properties": {
    "dataSchema": {
      "type": "object",
      "properties": {
        "dishes": {"type": "array", "format": "multilookup"},
        "name": {"type": "string"},
        "orderedAt": {"type": "string", "format": "date-time"},
      }
    },
    "filtersConfig": [
      {
        "property": "orderedAt",
        "operator": "between"
      },
      "dishes",
      "name"
    ]
  }
}

it is possible to specify a value for filtering properties dishes, name and orderedAt. Assuming the inserted values to be representable as:

{
  "orderedAt": ["2023-03-03T09:00:00.000Z", "2023-03-03T12:00:00.000Z"],
  "name": "Joe",
  "dishes": ["dish-1", "dish-2"]
}

Then the emitted filters look like:

{
  "property": "orderedAt",
  "operator": "between",
  "value": ["2023-03-03T09:00:00.000Z", "2023-03-03T12:00:00.000Z"]
},
{
  "property": "name",
  "operator": "equal",
  "value": "Joe"
},
{
  "property": "dishes",
  "operator": "includesAll",
  "value": ["dish-1", "dish-2"]
}

If a component such as the CRUD Client is included in the page (and provided with the same data-schema), these filters are chained inside an $and mongo-like query and used to retrieved filtered data.

Example: Apply filters from URL

Assuming the Expandable Filters to be configured like:

{
  "tag": "bk-expanded-filters",
  "properties": {
    "dataSchema": {
      "type": "object",
      "properties": {
        "name": {"type": "string"},
        "price": {"type": "number"},
        "orderedAt": {"type": "string", "format": "date-time"}
      }
    },
    "filtersConfig": [
      "name",
      {"property": "price", "operator": "less"},
      {"property": "orderedAt", "operator": "between"}
    ]
  }
}

and the following query parameter to be included in the URL of the current plugin:

{
  "filters": [
    {"property": "name", "operator": "equal", "value": "test"},
    {"property": "price", "operator": "less", "value": 10},
    {"property": "orderedAt", "operator": "less", "value": "2023-03-03T09:00:00.000Z"}
  ]
}

then a change-query event will be emitted with filters:

{
  "property": "name",
  "operator": "equal",
  "value": "test"
},
{
  "property": "price",
  "operator": "less",
  "value": 10
}

Filter on field "orderedAt" is not emitted since the filter operator less does not correspond to the one specified for the property inside filtersConfig (between).

API

Properties & Attributes

property	attribute	type	default	description
dataSchema	-	ExtendedJSONSchema7Definition	-	data-schema describing the fields of the collection to query
filtersConfig	-	FiltersConfig[]	-	lists the filters to include in the component
openByDefault	open-by-default	boolean	false	whether to show the component by default
liveSearchTimeout	live-search-timeout	number	5000	lookup live-search timeout
liveSearchItemsLimit	live-search-items-limit	number	10	max items to fetch on regex live search
readFromUrl	read-from-url	boolean	false	whether filters from URL should be read and applied at bootstrap time
basePath	-	string	-	endpoint to use to fetch lookup options

FiltersConfig

type FiltersConfig = string | {
  property: string
  operator: string
}

Listens to

event	action
filter	display/close the expanded filters component
display-data	retrieves data to build lookup options
lookup-data	retrieves data to build lookup options

Emits

event	description
change-query	when done filling or clearing the form, applies or clear the filters