You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+47-22Lines changed: 47 additions & 22 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,40 +8,52 @@ A set of most common BLoC use cases build on top [flutter_bloc](https://github.c
8
8
## Key contepts
9
9
10
10
##### BLoC
11
+
11
12
BLoC, aka **B**usiness **Lo**gic **C**omponent, is a state management system for Flutter. It's main goal is to separate business logic from the presentation layer. The BLoC handles user actions or any other events and generates new state for the view to render.
12
13
13
14
##### Repository
15
+
14
16
A `Repository` to handles data operations. It knows where to get the data from and what API calls to make when data is updated. A `Repository` can utilize a single data source as well as it can be a mediator between different data sources, such as database, web services and caches.
15
17
16
18
##### ViewStateBuilder
19
+
17
20
`ViewStateBuilder` is responsible for building the UI based on the view state. It's a wrapper over the `BlocBuilder` widget so it accepts a `bloc` object and a set of handy callbacks, which corresponds to each possible state:
18
21
19
-
*`onReady` - informs the presentation layer that view is in it's initial state, and no action has taken place yet,
20
-
*`onLoading` - informs the presentation layer that the data is being loaded, so it can display a loading indicator,
21
-
*`onRefreshing` - informs the presentation layer that the data is being refreshed, so it can display a refresh indicator or/and the current state of list items,
22
-
*`onSuccess` - informs the presentation layer that the loading is completed and a `nonnull` and not empty data was retrieved,
23
-
*`onEmpty` - informs the presentation layer that the loading is completed, but `null` or empty data was retrieved,
24
-
*`onError` - informs the presentation layer that the loading or refreshing has ended with an error. It also provides an error that has occurred.
22
+
*`initial` - informs the presentation layer that view is in it's initial state, and no action has taken place yet,
23
+
*`loading` - informs the presentation layer that the data is being loaded, so it can display a loading indicator,
24
+
*`refreshing` - informs the presentation layer that the data is being refreshed, so it can display a refresh indicator or/and the current state of list items,
25
+
*`data` - informs the presentation layer that the loading is completed and a `nonnull` and not empty data was retrieved,
26
+
*`empty` - informs the presentation layer that the loading is completed, but `null` or empty data was retrieved,
27
+
*`error` - informs the presentation layer that the loading or refreshing has ended with an error. It also provides an error that has occurred.
25
28
26
29
##### ViewStateListener
30
+
27
31
`ViewStateListener` is responsible for performing an action based on the view state. It should be used for functionality that needs to occur only in response to a state change such as navigation, showing a `SnackBar` etc. `ViewStateListener` is a wrapper over the `BlocListener` widget so it accepts a `bloc` object as well as a `child` widget and a set of handy callbacks corresponding to a given state:
28
32
29
33
*`onLoading` - informs the presentation layer that the data is being loaded,
30
34
*`onRefreshing` - informs the presentation layer that the data is being refreshed,
31
-
*`onSuccess` - informs the presentation layer that the loading is completed and a `nonnull` and not empty data was retrieved,
35
+
*`onData` - informs the presentation layer that the loading is completed and a `nonnull` and not empty data was retrieved,
32
36
*`onEmpty` - informs the presentation layer that the loading is completed, but `null` or empty data was retrieved,
33
37
*`onError` - informs the presentation layer that the loading or refreshing has ended with an error. It also provides an error that has occurred.
34
38
35
39
## Features
36
40
37
41
### ListBloc
38
-
The most basic use case. Allows to fetch, refresh and display a list of items without filtering and pagination. Thus, `ListBloc` should be used only with a reasonable amount of data. `ListBloc` provides the methods for loading and refreshing data: `loaditems()` and `refreshitems()`. The former is most suitable for initial data fetch or for retry action when the first fetch fails. The latter is designed for being called after the initial fetch succeeds. It can be performed when the list has already been loaded. To display the current view state `ListBloc` cooperates with `BlocBuilder` as well as `ViewStateBuilder`.
42
+
43
+
The most basic use case. Allows to fetch, refresh and display a list of items without filtering and pagination. Thus, `ListBloc` should be used only with a reasonable amount of data.
44
+
45
+
`ListBloc` provides the methods for loading and refreshing data:
46
+
47
+
*`loaditems()` - most suitable for initial data fetch or for retry action when the first fetch fails,
48
+
*`refreshitems()` - designed for being called after the initial fetch succeeds.
49
+
50
+
To display the current view state `ListBloc` cooperates with `BlocBuilder` as well as `ViewStateBuilder`.
39
51
40
52
##### ListRepository
41
53
42
54
A `ListRepository` implementation should provide only one method:
43
55
44
-
`Future<List<T>> getAll();` - this method is responsible for providing all the data to the `ListBloc`.
56
+
*`Future<List<T>> getAll();` - this method is responsible for providing all the data to the `ListBloc`.
45
57
46
58
Where:
47
59
*`T` is the item type returned by this repository.
An extension to the `ListBloc` that allows filtering.
55
68
56
69
##### FilterRepository
57
70
58
71
`FilterListRepository` provides two methods:
59
72
60
-
`Future<List<T>> getAll();` - this method is called when a `null` filter is provided and should return all items,
61
-
`Future<List<T>> getBy(F filter);` - this method is called with `nonnull` filter and should return only items that match it.
73
+
*`Future<List<T>> getAll();` - this method is called when a `null` filter is provided and should return all items,
74
+
*`Future<List<T>> getBy(F filter);` - this method is called with `nonnull` filter and should return only items that match it.
62
75
63
76
Where:
64
77
*`T` is the item type returned by this repository,
@@ -69,18 +82,22 @@ Where:
69
82
[Filter List BLoC Sample App](example/lib/src/list_filter_app.dart)
70
83
71
84
### PagedListBloc
72
-
A list BLoC with pagination but without filtering. It works best with [Infinite Widgets](https://github.com/jaumard/infinite_widgets) but a custom presentation layer can provided as well.
85
+
86
+
A list BLoC with pagination but without filtering. It works best with [Infinite Widgets](https://github.com/jaumard/infinite_widgets) but a custom presentation layer can be provided as well.
73
87
74
88
#### Page
89
+
75
90
Contains information about the current page, this is `number` and `size`.
76
91
77
92
#### PagedList
93
+
78
94
List of items with information if there are more items or not.
79
95
80
96
#### PagedListRepository
97
+
81
98
`PagedListRepository` comes with only one method:
82
99
83
-
`Future<List<T>> getAll(Page page);` - this method retrieves items meeting the pagination restriction provided by the `page` object.
100
+
*`Future<List<T>> getAll(Page page);` - this method retrieves items meeting the pagination restriction provided by the `page` object.
84
101
When items are exceeded it should return an empty list or throw `PageNotFoundException`. `PagedListBloc` will handle both cases in the same way.
85
102
86
103
Where:
@@ -91,19 +108,22 @@ Where:
91
108
[Paged List BLoC Sample App](example/lib/src/list_paged_app.dart)
92
109
93
110
### PagedListFilterBloc
94
-
A list BLoC with pagination and filtering. It works best with [Infinite Widgets](https://github.com/jaumard/infinite_widgets) but a custom presentation layer can provided as well.
111
+
112
+
A list BLoC with pagination and filtering. It works best with [Infinite Widgets](https://github.com/jaumard/infinite_widgets) but a custom presentation layer can be provided as well.
95
113
96
114
#### Page
115
+
97
116
Contains information about the current page, this is `number` and `size`.
98
117
99
118
#### PagedList
119
+
100
120
List of items with information if there are more items or not.
101
121
102
122
#### PagedListFilterRepository
103
123
`PagedListFilterRepository` provides only two methods:
104
124
105
-
`Future<List<T>> getAll(Page page);` - retrieves items meeting the pagination restriction provided by the `page` object.
106
-
`Future<List<T>> getBy(Page page, F filter);` - retrieves items meeting pagination as well as the filter restrictions provided by the `page` and `filter` objects.
125
+
*`Future<List<T>> getAll(Page page);` - retrieves items meeting the pagination restriction provided by the `page` object.
126
+
*`Future<List<T>> getBy(Page page, F filter);` - retrieves items meeting pagination as well as the filter restrictions provided by the `page` and `filter` objects.
107
127
108
128
When items are exceeded it should return an empty list or throw `PageNotFoundException`. `PagedListFilterBloc` will handle both cases in the same way.
109
129
@@ -120,9 +140,10 @@ Where:
120
140
A BLoC that allows to fetch a single item with given identifier.
121
141
122
142
#### DetailsRepository
143
+
123
144
`DetailsRepository` comes with only one method:
124
145
125
-
`Future<T> getById(I id);` - this method retrieves an item with given id. When there's no item matching the id the `null` should be returned or `itemNotFoundException` should be thrown. In both cases the `DetailsBloc` will emit `Empty` state.
146
+
*`Future<T> getById(I id);` - this method retrieves an item with given id. When there's no item matching the id the `null` should be returned. In this cases the `DetailsBloc` will emit `Empty` state.
126
147
127
148
Where:
128
149
*`T` is the item type returned by this repository,
@@ -155,8 +176,12 @@ Or whatever works for you. A sample implementation using `connectivity_plus` may
155
176
class ConnectivityPlusRepository implements ConnectionRepository {
156
177
@override
157
178
Stream<Connection> observe() {
158
-
return connectivity.onConnectivityChanged.map(
159
-
(ConnectivityResult result) => result != ConnectivityResult.none
179
+
// Required due to https://github.com/fluttercommunity/plus_plugins/issues/2527
0 commit comments