Search Bar

<bk-search-bar></bk-search-bar>

Allows data filtering by matching a text string

Search bar allows to filter data against text using a regex. Special regex characters (( ) [ ] { } + - ^ * $ \ ? / | .) are sanitized within the input.

Upon search, the Search Bar notifies that data should be queried by matching its fields against the input string. Technically, the Search Bar emits a change-query event, injecting the submitted text in the payload event with key "search".

How to configure

For its most basic usage, no particular configuration is required by the Search Bar.

{
  "tag": "bk-search-bar"
}

Lookup fields

If searchLookups property is true, upon search the Search Bar requests the submitted text to also be matched against lookups and multi-lookup fields, which is achieved by emitting a search-lookups event. A component like the Lookup CRUD Client could listen to this event and propagated fetched lookup values that match the searched text.

excludeFromSearch as false in their schema are also searched. The text value is compared against the lookupFields specified in the lookupOptions in the schema.

danger

Searching lookup fields could be computationally heavy. The number of searchable lookups should be kept to the needed minimum and search-bar properties such as liveSearchItemsLimit and autoSearchMinInput should be configured carefully. For this reason, components such as the Lookup CRUD Client only perform text searches on lookup fields that have excludeFromSearch set to false in the provided data-schema.

Tuning automatic search

The Search Bar supports automatic search - that is, search is automatically submitted by typing into the input field of the component.

The following properties can be used to tune automatic search:

• searchDebounce: milliseconds before the search is automatically submitted after the user has stopped typing
• autoSearchMinInput: minimum number of characters of the input value before the search is automatically submitted

Locale

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

type Locale = {
  placeholder: LocalizedText
}

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

Examples

Example: Basic Search

For instance, with the Search Bar configured like:

{
  "tag": "bk-search-bar"
}

submitting for search the entry "example" triggers the emission of a change-query event with payload

{
  "search": "example"
}

A component such as the CRUD Client might listen to such event, and trigger data fetching with regex filters against all searchable fields.

Example: Interaction with CRUD Client

With a configuration that includes both a Search Bar and a CRUD Client like:

{
  "tag": "bk-search-bar"
},
{
  "tag": "bk-crud-client",
  "properties": {
    "dataSchema": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "surname": { "type": "string" },
        "email": { "type": "string", "excludeFromSearch": true }
      }
    }
  }
}

if the user submits a text search with input "example" using the Search Bar, a change-query event is emitted with payload:

{
  "search": "example" 
}

triggering a data fetching call by the CRUD Client with query:

{
  "$or": [
    { "name": { "$regex": ".*example.*", "$options": "i" } },
    { "surname": { "$regex": ".*example.*", "$options": "i" } }
  ]
}

The CRUD Client excludes "email" from the query because of the excludeFromSearch flag specified in the corresponding data-schema field.

Note that the CRUD Client performs case-insensitive searches.

Example: Limitations

In components designed to visualize data, such as the Table, some data might be displayed differently than the corresponding value in the database. In such cases, it is important to notice that using the Search Bar with the CRUD Client fails to perform searches against the displayed value, that are instead performed against the actual values, as stored in the database. This limitation does not apply to lookup fields, which might be searchable using a component like the Lookup CRUD Client.

For example, assuming a backend collection to have a weekDay field which can have values: "0", "1", "2", "3", "4", and a configuration with a Search Bar, a CRUD Client, a Table having enum fields such as:

{
  "tag": "bk-search-bar"
},
{
  "tag": "bk-crud-client",
  "properties": {
    "dataSchema": {
      "weekDay": {
        "type": "string",
        "enum": [
          {"id": "0", "label": "Monday"},
          {"id": "1", "label": "Tuesday"},
          {"id": "2", "label": "Wednesday"},
          {"id": "3", "label": "Thursday"},
          {"id": "4", "label": "Friday"}
        ]
      }
    }
  }
},
{
  "tag": "bk-table",
  "properties": {
    "dataSchema": {
      "weekDay": {
        "type": "string",
        "enum": [
          {"id": "0", "label": "Monday"},
          {"id": "1", "label": "Tuesday"},
          {"id": "2", "label": "Wednesday"},
          {"id": "3", "label": "Thursday"},
          {"id": "4", "label": "Friday"}
        ]
      }
    }
  }
}

The Table displays inside its rows the data it received by the CRUD Client, but visualizes the enum field weekDay using the corresponding label key. For instance, if the CRUD Client fetches and propagates data like:

[
  {"weekDay": "0"},
  {"weekDay": "1"}
]

the Table renders a table with two rows, having a weekDay column with entries "Monday" instead of "0" and "Tuesday" instead of "1", as specified in the enum property of the data-schema:

[
  ["Monday"],
  ["Tuesday"]
]

Using the Search Bar to search for the values displayed in the Table ("Monday", "Tuesday", ...) fails, since ultimately the search is performed by the CRUD Client against the actual stored value.

Searching for "mon" triggers the Search Bar to emit a change-query event with payload:

{
  "search": "mon"
}

The CRUD Client listens to the event and fetches data with a query like:

{
  "weekDay": {
    "$regex": ".*mon.*", "$options": "i"
  }
}

which returns no data, since "mon" does not match any of the stored values of weekDay ("0", "1", "2", "3", "4").

API

Properties & Attributes

property	attribute	type	default	description
autoSearchMinInput	auto-search-min-input	number	2	min length of input string before performing automatic search
liveSearchItemsLimit	live-search-items-limit	number	100	max items to fetch on regex live search
placeholder	-	LocalizedText	-	placeholder of the search bar input
searchDebounce	search-debounce	number	0	milliseconds to wait before performing an automatic search. If 0, automatic search is disabled
searchLookups	search-lookups	boolean	false	whether or not to perform search on lookups. If true, a component such as the Lookup CRUD Client should be included in the plugin

Listens to

event	action
loading-data	sets internal loading state
nested-navigation-state/back	keeps track of navigation steps
nested-navigation-state/push	keeps track of navigation steps
search-lookups-found	includes lookup values searched against text search. Triggers the emission of a change-query event

Emits

event	description
change-query	requires data filtered according with the typed input
search-lookups	notifies to search lookups against a text