FilterField
The FilterField
component is a text-based input component that allows users to
enter filters using an intuitive and easily understandable syntax. Since the
input is text-based, users can always enter anything they want. To provide
guidance to the user, we recommend always using the FilterField
in combination
with suggestions.
The FilterField
is still experimental. Be aware that the API is subject to
change.
Import
import { FilterField } from '@dynatrace/strato-components-preview/filters';
Use cases
Customize comparison operator suggestions
With the autoSuggestions
prop set to true
, relevant operator suggestions are
automatically added to the list of suggestions. You can customize those by
omitting autoSuggestions
and using the returned autoSuggestions
in the
onSuggest
callback. The onSuggest
callback provides all the information you
need to determine which suggestions to show.
Load suggestions async
Load suggestions async and display the suggestions overlay in a loading state by
setting the loading
prop on FilterField.Suggestions
.
Use different strategies for inserting suggestions
Using a pre-defined syntax, the FilterField
parses the input and transforms it
into tokens. A token represents a filter key, value, comparison operator, or
logical operator.
By default, applying a suggestion replaces the token the cursor is currently
positioned in with the suggestion's value. Use the insertionStrategy
prop to
alter the behavior.
The supported replacement strategies are:
Strategy | Behavior |
---|---|
replace-token (default) | Replace the token at the cursor position. |
replace-statement | Replace the whole statement at the cursor position. |
replace-all | Replace the whole filter. |
insert | Insert at the cursor position without any replacements. |
Escape suggestions
The FilterField
syntax uses the space
as delimiter between keys, operators,
values, and statements. To learn more about the syntax refer to the
Dynatrace Documentation.
To avoid an invalid syntax when applying a suggestion, you can use the value
prop and the children of the FilterField.Suggestion
component. The value
is
used when applying the suggestion, whereas the children
are used to render the
suggestion in the overlay.
In general, the following characters need to be escaped, either wrapping the
whole value in double quotes, or using a \
to escape single characters:
*
(Asterisk),
=
>
<
With the suggestion insertion strategy set to replace-token
, the applied value
is escaped automatically if need be.
Examples (the same examples are valid for keys as well):
- Exact match of comparison operator
foo = \=
foo = \<
foo = ">"
foo = "!="
- Starts with / ends with operator in value
foo = *"ba*r"
(ends withba*r
)foo = ba\*r*
(starts withba*r
)foo = *"ba*r"*
(containsba*r
)
- Space in value
foo = "b a r"
foo = b\ ar
Group suggestions and add additional information
Use the FilterField.SuggestionGroup
to visually separate suggestions. Use the
FilterField.SuggestionGroupLabel
to add a label to the group.
Use the FilterField in a form
The user can submit the FilterField
using Enter
or Ctrl / Cmd + Enter
.
This triggers the onFilter
callback, which provides the string representation
of the value, the syntax tree, and its validity state.
Clearing the FilterField
also triggers the onFilter
callback.
The FilterField
can be submitted with a form and by default shows a set of
error messages based on the entered value, rendered as tooltips. Use the
FormField
to make the error state more present and add an accessible error
message underneath the FilterField
. Read up on how to use the FormField
here.
Change syntax to basic mode
Set the syntax
prop to basic
to narrow down the set of rules used to parse
the input. In the basic
mode, logical OR
and grouping are not supported. All
filter expressions are automatically connected with AND
.
Work with the syntax tree
The FilterField
provides a tokenized version of the entered value, grouping
statements that are connected with the same logical operator. With the logical
AND
having a higher precedence than the logical OR
, the statements
a = 1 b = 2 OR c = 3
will be grouped as follows:
Each statement is represented by a node holding the key, operator, and value of
the statement, provided as properties of the statement node. Depending on the
type of value and operators used, additional information (e.g. starts-with
,
contains
) is provided in the syntax tree.
If there is an error in the syntax, a node with type Error
is included in the
syntax tree and the accompanying isValid
flag is set to false
.
Explicit logical operator nodes
Explicit logical operators are included in the syntax tree so we can convert the
tree back to a string without losing any information. The logical operator you
need to use for evaluating a group of statements is already included on the
Group
node. Ignore logical operators in the children
array of groups.
Convert string to syntax tree
Use the convertStringToFilterFieldTree
utility to convert a string into a
FilterTree
. Setting the value programmatically doesn't trigger the onChange
callback. To get the converted syntax tree and filter data accordingly, use the
provided utility function.
Convert syntax tree to string
Use the convertFilterFieldTreeToString
utility to convert a syntax tree into a
string.
See the example below for converting from string to tree and back.