Filter State

About this widget

A FilterState holds one or several filters, organized in groups, and emits changes of added or removed filters, which will be applied to searches performed by connected components.

There are three types of filters:

• FilterFacet
• FilterNumeric
• FilterTag

A group of filters must be identified by a FilterGroupID. A FilterGroupID have:

• A FilterOperator indicates which type of boolean operator should be applied between each filters in the group: FilterOperator.and or FilterOperator.or
• An optional name Check out the Combining boolean operators guide for more information.

Examples

Create

The following is an example of creating and setting up a FilterState with different filters (facets, tags and numerical):

1
2
3
4
5
6
7
8
const authors = FilterGroupID('author', FilterOperator.or);
const genres = FilterGroupID('genres');
const numbers = FilterGroupID('numbers');
final filterState = FilterState()
  ..add(authors, [Filter.facet('author', 'Shakespeare')])
  ..add(genres, [Filter.tag('drama')])
  ..add(numbers, [Filter.range('rating', lowerBound: 3, upperBound: 5)])
  ..add(numbers, [Filter.comparison('price', NumericOperator.less, 50)]);

The preceding code snippet corresponds to the following expression: (author:Shakespeare) AND (_tags:drama) AND (rating:3 TO 5 AND price < 50)

Read

Listen to filters stream to get filtering changes:

1
2
3
4
5
6
7
StreamBuilder<Filters>(
  stream: filterState.filters,
  builder: (context, snapshot) {
    final filters = snapshot.data;
    final count = filters?.getFilters().length ?? 0;
    return Text('Filters applied: $count');
  });

Use snapshot to get the latest Filters value submitted by filters stream:

1
final filters = filterState.snapshot();

Update

FilterState can be updated using methods such as add, set and remove, each modification triggers a filters submission.
Use modify to run multiple modifications (atomically), and trigger a single filters submission:

1
2
3
4
  filterState.modify((filters) async =>
      filters
          .add(authors, [Filter.facet('author', 'J. K. Rowling')])
          .remove(authors, [Filter.facet('author', 'Shakespeare')]));

Delete

Remove all or some filter groups using clear and clearExcept

1
2
3
4
5
6
  // Remove all filter groups
  filterState.clear(); 
   // Clear filter group 'authors'
  filterState.clear(authors);
  // Clear all filter groups except 'authors'
  filterState.clearExcept([authors]);