Flutter Bloc List Manager
A Flutter package built on top of flutter_bloc that makes it easy to manage filtering and searching a list of items while allowing you to concentrate on building your UI.
Read more about the implementation and about adding boolean filtering support.
Widgets
ListManager Widget
The ListManager
widget is the entry-point to accessing the blocs provided by this package. There is no need to manually create any of the other blocs this package provides, they are all available from the build context underneath the ListManager
widget.
ListManager
should be established with:
Types
I
- the item class holding the data for the listT
- the state containing the loaded itemsB
- the bloc that contains the above state
Parameters
filterProperties
- properties that exist on your item classI
that should be used to generate filter conditionssearchProperties
- properties that exist on your item classI
that should be used to run search queries againstchild
- the widget to be rendered by theListManager
, which will have access to the remaining blocs
Example
BlocProvider<SourceBloc>(
create: (_) => SourceBloc(),
child: ListManager<ItemClass, SourceLoaded, SourceBloc>(
filterProperties: const ['property1'],
searchProperties: const ['property2'],
child: Column(
children: [
BlocBuilder<FilterConditionsBloc, FilterConditionsState>(
builder: (context, state) {
return const Text('Render filter conditions UI.');
},
),
BlocBuilder<SearchQueryCubit, String>(
builder: (context, state) {
return const Text('Render Search UI.');
},
),
BlocBuilder<ItemListBloc, ItemListState>(
builder: (context, state) {
return const Text('Render list UI.');
},
),
],
),
),
)
FilterConditionsBloc
State from FilterConditionsBloc
is used to render your filtering UI. Filter conditions will be updated whenever the source bloc is updated.
String values are treated normally.
Boolean values are treated a little differently. If a boolean value is requested to be used as a filterCondition
, display-friendly True
and False
conditions will automatically be added for you.
Example
BlocBuilder<FilterConditionsBloc, FilterConditionsState>(
builder: (_, state) {
if (state is ConditionsInitialized) {
return ListView.builder(
itemCount: state.availableConditions.length,
itemBuilder: (_, index) {
final condition = state.availableConditions.entries.elementAt(index);
return Column(
children: [
Text(condition.key),
...condition.value.map(
(value) => Text(value),
),
],
),
},
);
}
return CircularProgressIndicator();
},
)
Dispatching events
Events can be dispatched against the FilterConditionsBloc
to add/remove active property/value condition pairs. Whenever the source bloc is updated, active conditions that no longer apply are automatically removed.
Example
context.read<FilterConditionsBloc>().add(AddCondition(
property: 'property',
value: 'value',
));
context.read<FilterConditionsBloc>().add(RemoveCondition(
property: 'property',
value: 'value',
));
Note: If you want to manually toggle a boolean condition (i.e. not via constructing UI from the availableConditions
), you would want to use AddCondition('booleanProperty', 'True')
or AddCondition('booleanProperty', 'False')
as those are the underlying display values.
Filter modes
You can choose to override the default filter mode when adding a specific condition for filtering. Perhaps you'd like the main filtering UI to be additive, but you would like to add a global toggle to add and remove a subtractive filter condition into the mix.
Example
context.read<FilterConditionsBloc>().add(AddCondition(
property: 'property',
value: 'value',
mode: FilterMode.and,
));
SearchQueryCubit
The simplest cubit of the bunch, the SearchQueryCubit
is solely responsible for setting or clearing the search query that drives list searching.
Example
context.read<SearchQueryCubit>().setQuery('query');
context.read<SearchQueryCubit>().clearQuery();
ItemListBloc
ItemListBloc
is responsible for connecting all of the other blocs, performing the actual filtering and searching, and providing state in order to render your list UI. There is never a reason to dispatch events to this bloc.
Note on filter modes
Without a much more sophisticated means to assemble filter queries, there is no current way to support compound filtering: i.e. (Condition 1 AND Condition 2) OR (Condition 3 AND Condition 4)
or priority scenarios: i.e. the difference between (Condition 1 OR Condition 2 OR Condition 3) AND Condition 4
and Condition 4 AND (Condition 1 OR Condition 2 OR Condition 3)
. As such, we've chosen to implement filtering such that additive (or
) conditions are matched first and subtractive (and
) conditions are matched last.
Practically, what does this mean?
Your list of items will first be filtered such that every item matching any single or
condition is sent through. The resulting list will then be filtered such that every item matching all and
conditions are sent through. The and
conditions technically refine the resulting list and the or
conditions generate the first pass of the list that should be refined.
Example
BlocBuilder<ItemListBloc, ItemListState>(
builder: (_, state) {
if (state is NoSourceItems) {
return const Text('No source items');
}
if (state is ItemEmptyState) {
return const Text('No matching results');
}
if (state is ItemResults<ItemClass>) {
return ListView(
children: state.items
.map(
(item) => ListTile(
key: ValueKey(item.id),
title: Text(item.name),
),
)
.toList(),
);
}
return Container();
},
)
Data classes
There are a few setup pieces that are required in order to properly manage the data in your list.
ItemClassWithAccessor
Flutter cannot use the dart mirroring packages, so the class used to store individual items in the list must have a prop accessor for any data that needs to be accessed dynamically (either by filtering or searching). The item class will generally also extend equatable as it will be used as part of your source bloc state.
class ItemClass extends Equatable implements ItemClassWithAccessor {
final String id;
final String name;
const ItemClass({
required this.id,
required this.name,
});
@override
List<Object> get props => [id, name];
dynamic operator [](String prop) {
switch (prop) {
case 'id':
return id;
case 'name':
return name;
default:
throw ArgumentError('Property `$prop` does not exist on ItemClass.');
}
}
}
ItemSourceState
You are free to manage your source bloc however you see fit. The only requirement in order to instantiate a ListManager
is that one of the states of your source bloc must implement ItemSourceState
. This allows blocs in this package to know when source items are actually flowing through your source bloc.
Example
class SourceLoaded extends SourceBlocState implements ItemSourceState<ItemClass> {
final items;
const SourceLoaded(this.items);
@override
List<Object> get props => [items];
}
Upcoming improvements
- Pluggable search callback (allowing integration of fuzzy search)
- Conditional instantiation of the
SearchQueryCubit
- Integrating opinionated pre-composed UI widgets
- Potentially moving away from the source bloc concept and requiring a repository instead