The goal of this package is to make it easy to implement the BLoC
Design Pattern (Business Logic Component).
This design pattern helps to separate presentation from business logic. Following the BLoC pattern facilitates testability and reusability. This package abstracts reactive aspects of the pattern allowing developers to focus on converting events into states.
Events are the input to a Bloc. They are commonly UI events such as button presses. Events
are dispatched
and then converted to States
.
States are the output of a Bloc. Presentation components can listen to the stream of states and redraw portions of themselves based on the given state (see BlocBuilder
for more details).
Transitions occur when an Event
is dispatched
after mapEventToState
has been called but before the Bloc
’s state has been updated. A Transition
consists of the currentState, the event which was dispatched, and the nextState.
BlocSupervisor oversees Bloc
s and delegates to BlocDelegate
.
BlocDelegate handles events from all Bloc
s which are delegated by the BlocSupervisor
. Can be used to intercept all Bloc
events, transitions, and errors. It is a great way to handle logging/analytics as well as error handling universally.
initialState is the state before any events have been processed (before mapEventToState
has ever been called). initialState
must be implemented.
mapEventToState is a method that must be implemented when a class extends Bloc
. The function takes the incoming event as an argument. mapEventToState
is called whenever an event is dispatched
by the presentation layer. mapEventToState
must convert that event into a new state and return the new state in the form of a Stream
which is consumed by the presentation layer.
dispatch is a method that takes an event
and triggers mapEventToState
. dispatch
may be called from the presentation layer or from within the Bloc (see examples) and notifies the Bloc of a new event
.
transformEvents is a method that transforms the Stream<Event>
along with a next
function into a Stream<State>
. Events that should be processed by mapEventToState
need to be passed to next
. By default asyncExpand
is used to ensure all events are processed in the order in which they are received. You can override transformEvents
for advanced usage in order to manipulate the frequency and specificity with which mapEventToState
is called as well as which events are processed.
transformStates is a method that transforms the Stream<State>
into a new Stream<State>
. By default transformStates
returns the incoming Stream<State>
. You can override transformStates
for advanced usage in order to manipulate the frequency and specificity at which transitions
(state changes) occur.
onEvent is a method that can be overridden to handle whenever an Event
is dispatched. It is a great place to add bloc-specific logging/analytics.
onTransition is a method that can be overridden to handle whenever a Transition
occurs. A Transition
occurs when a new Event
is dispatched and mapEventToState
is called. onTransition
is called before a Bloc
’s state has been updated. It is a great place to add bloc-specific logging/analytics.
onError is a method that can be overridden to handle whenever an Exception
is thrown. By default all exceptions will be ignored and Bloc
functionality will be unaffected. It is a great place to add bloc-specific error handling.
dispose is a method that closes the event
and state
streams. Dispose
should be called when a Bloc
is no longer needed. Once dispose
is called, events
that are dispatched
will not be processed and will result in an error being passed to onError
. In addition, if dispose
is called while events
are still being processed, any states
yielded after are ignored and will not result in a Transition
.
onEvent is a method that can be overridden to handle whenever an Event
is dispatched to any Bloc
. It is a great place to add universal logging/analytics.
onTransition is a method that can be overridden to handle whenever a Transition
occurs in any Bloc
. It is a great place to add universal logging/analytics.
onError is a method that can be overriden to handle whenever an Exception
is thrown from any Bloc
. It is a great place to add universal error handling.
For simplicity we can create a CounterBloc
like:
class CounterBloc extends Bloc<CounterEvent, int> {
@override
int get initialState => 0;
@override
Stream<int> mapEventToState(CounterEvent event) async* {
switch (event) {
case CounterEvent.decrement:
yield currentState - 1;
break;
case CounterEvent.increment:
yield currentState + 1;
break;
}
}
}
Our CounterBloc
converts CounterEvents
to integers.
As a result, we need to define our CounterEvent
like:
enum CounterEvent { increment, decrement }
Then we can dispatch events to our bloc like so:
void main() {
final counterBloc = CounterBloc();
counterBloc.dispatch(CounterEvent.increment);
counterBloc.dispatch(CounterEvent.increment);
counterBloc.dispatch(CounterEvent.increment);
counterBloc.dispatch(CounterEvent.decrement);
counterBloc.dispatch(CounterEvent.decrement);
counterBloc.dispatch(CounterEvent.decrement);
}
As our app grows and relies on multiple Blocs
, it becomes useful to see the Transitions
for all Blocs
. This can easily be achieved by implementing a BlocDelegate
.
class SimpleBlocDelegate extends BlocDelegate {
@override
void onTransition(Bloc bloc, Transition transition) {
super.onTransition(bloc, transition);
print(transition);
}
}
Now that we have our SimpleBlocDelegate
, we just need to tell the BlocSupervisor
to use our delegate in our main.dart
.
void main() {
BlocSupervisor.delegate = SimpleBlocDelegate();
final counterBloc = CounterBloc();
counterBloc.dispatch(CounterEvent.increment); // { currentState: 0, event: CounterEvent.increment, nextState: 1 }
counterBloc.dispatch(CounterEvent.increment); // { currentState: 1, event: CounterEvent.increment, nextState: 2 }
counterBloc.dispatch(CounterEvent.increment); // { currentState: 2, event: CounterEvent.increment, nextState: 3 }
counterBloc.dispatch(CounterEvent.decrement); // { currentState: 3, event: CounterEvent.decrement, nextState: 2 }
counterBloc.dispatch(CounterEvent.decrement); // { currentState: 2, event: CounterEvent.decrement, nextState: 1 }
counterBloc.dispatch(CounterEvent.decrement); // { currentState: 1, event: CounterEvent.decrement, nextState: 0 }
}
At this point, all Bloc
Transitions
will be reported to the SimpleBlocDelegate
and we can see them in the console after running our app.
If we want to be able to handle any incoming Events
that are dispatched to a Bloc
we can also override onEvent
in our SimpleBlocDelegate
.
class SimpleBlocDelegate extends BlocDelegate {
@override
void onEvent(Bloc bloc, Object event) {
super.onEvent(bloc, event);
print(event);
}
@override
void onTransition(Bloc bloc, Transition transition) {
super.onTransition(bloc, transition);
print(transition);
}
}
If we want to be able to handle any Exceptions
that might be thrown in a Bloc
we can also override onError
in our SimpleBlocDelegate
.
class SimpleBlocDelegate extends BlocDelegate {
@override
void onEvent(Bloc bloc, Object event) {
super.onEvent(bloc, event);
print(event);
}
@override
void onTransition(Bloc bloc, Transition transition) {
super.onTransition(bloc, transition);
print(transition);
}
@override
void onError(Bloc bloc, Object error, StackTrace stacktrace) {
super.onError(bloc, error, stacktrace);
print('$error, $stacktrace');
}
}
At this point, all Bloc
Exceptions
will also be reported to the SimpleBlocDelegate
and we can see them in the console.
CounterBloc
in a pure Dart app.#flutter #dart #mobile-apps