FilterState

Provides interface for managing applied filters.

About this widget

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

You can add three types of filters:

• FilterFacet
• FilterNumeric
• FilterTag

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

• An optional name
• A FilterOperator indicating which type of boolean operator should be applied between each filter in the group: FilterOperator.and or FilterOperator.or. For more information, see Combining boolean operators.

Examples

Create

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

Dart

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:

Dart

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:

Dart

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:

Dart

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:

Dart

// Remove all filter groups
filterState.clear(); 
 // Clear filter group 'authors'
filterState.clear(authors);
// Clear all filter groups except 'authors'
filterState.clearExcept([authors]); 

Fields

filters · Stream<Filters>

Filters groups stream (facet, tag, numeric and hierarchical).

Dart

filterState.filters.listen((filters) {
  // Count of applied filters
  final count = filters.getFilters().length;
  print('${count} filter(s) applied');

  // Applied facet filters
  filters.facetGroups.forEach(
      (key, value) => print("${key.name}: ${value.join(',')}"));
});

Methods

add

Adds a list of filters to a group by its groupID.

Dart

filterState.add(groupID, filters);

set

Overrides filters list with a provided map.

Dart

filterState.set(map);

remove

Removes a list of filters from a group by its groupID.

Dart

filterState.remove(groupID, filters);

toggle

Toggles a filter in given group by its groupID.

Dart

filterState.toggle(groupID, filter);

contains

Checks if a filter exists in a group.

Dart

filterState.contains(groupID, filter);

addHierarchical

Adds a HierarchicalFilter to a group.

Dart

filterState.addHierarchical(attribute, hierarchicalFilter);

removeHierarchical

Removes HierarchicalFilter group by its attribute.

Dart

filterState.removeHierarchical(attribute);

clear

Clears provided group IDs. If none provided, all filters will be cleared.

Dart

filterState.clear(groupIDs);

clearExcept

Clears all groups except provided group IDs.

Dart

filterState.clearExcept(groupIDs);

modify

Asynchronously updates filters. Useful to apply multiple consecutive update operations without firing multiple filters events.

Dart

filterState.modify((filters) async =>
  filters
      .add(groupID, filters)
      .remove(groupID, filters;

snapshot

Gets the latest Filters value submitted by filters:

Dart

final filters = filterState.snapshot();

dispose

Releases all underlying resources.

Dart

filterState.dispose();