Skip to content

Commit beaf421

Browse files
committed
docs: update migration guide
1 parent 51a31b3 commit beaf421

File tree

2 files changed

+21
-57
lines changed

2 files changed

+21
-57
lines changed

CHANGELOG.md

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,15 +3,18 @@
33
- `PagingListener` widget to connect a `PagingController` to a `PagedLayoutBuilder`.
44

55
### Changed
6-
- `PagingController` no longer has `addPageRequestListener` method and `firstPageKey` parameter. Use the `fetchPage` and `getNextPageKey` parameters of the constructor instead.
6+
- `PagingController` no longer has `addPageRequestListener` method and `firstPageKey` parameter. Use the `fetchPage` parameter of the constructor instead.
77
- `PagingController` no longer has the `itemList`, `error`, and `nextPageKey` getters and setters. All values are now stored in `PagingState`.
8-
- `PagingController` no longer has the `appendPage`, `appendLastPage`, and `retryLastFailedRequest` methods. Use the `copyWith` method of `PagingState` to update its fields.
8+
- `PagingController` no longer has the `appendPage` and `appendLastPage` methods. Use the `copyWith` method of `PagingState` to update its `pages`, `keys`, and `hasNextPage` fields.
9+
- `PagingController` no longer has the `retryLastFailedRequest` method. You can simply call `fetchNextPage` to try again.
910
- `PagingController` no longer has the `invisibleItemsThreshold` field. It is now configured in `PagedChildBuilderDelegate`.
11+
- `PagingController` now features getters matching the fields of `PagingState` as well as `mapItems` to modify the items.
1012
- `PagedLayoutBuilder` no longer accepts `pagingController` as a parameter. It now takes `PagingState` and `fetchNextPage` instead.
1113
- `PagingState` now uses `pages` (`List<List<ItemType>>`) instead of `itemList` (`List<ItemType>`). A new extension getter `items` is provided for flattening.
1214
- `PagingState` now features `keys`, a list storing all fetched keys, and `hasNextPage` replacing `nextPageKey`.
1315
- `PagingState` now includes `isLoading`, which tracks whether a request is in progress.
1416
- `PagingState` now provides `error` as type `Object?` instead of `dynamic`.
17+
- `PagingState` now includes `mapItems` and `filterItems` extension methods for modifying items conveniently.
1518

1619
### Fixed
1720
- `PagingController` now deduplicates requests.

MIGRATION.md

Lines changed: 16 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,9 @@ This is a large breaking change and will require refactoring in your code.
77

88
The package was upgraded to a newer modern flutter major version.
99

10-
- Newly requires `dart: ">=3.4.0"` and `flutter: ">=3.0.0"`
11-
- Newly depends on `collection: ">=1.15.0"`
10+
- Newly requires `dart: ">=3.4.0"` and `flutter: ">=3.0.0"` for modern language features.
11+
- Newly depends on `collection: ">=1.15.0"` for deep collection equality on `PagingState`.
12+
- Newly depends on `meta: ">=1.8.0"` for annotations on `PagingState` extension methods.
1213

1314
## PagingController
1415

@@ -44,13 +45,18 @@ This fixes several issues of the past:
4445
The PagingController can also be arbitrarily extended to include additional functionality that you might require.
4546
The source code explains how to structure new code.
4647

48+
Lastly, the various getter and setter methods previously featured to modify the state have been removed.
49+
New getters have been added, however, setters have been left out since it should not be necessary to modify the state often.
50+
One exception is the newly provided `mapItems` extension method, which can be used to modify the items in a convenient way, while retaining their page structure.
51+
4752
### API Changes
4853

49-
- No longer features `itemList`, `error` and `nextPageKey` getters and setters. All values are directly stored in the `PagingState`.
54+
- `itemList` and `nextPageKey` properties have been removed.
55+
- `pages`, `items`, `keys`, `error`, `hasNextPage` and `isLoading` extension getters as well as `mapItems` to modify the items have been added.
5056
- `addPageRequestListener` was removed. Use the `fetchPage` parameter of the constructor instead.
51-
- `appendPage` and `appendLastPage` were removed. Use the `copyWith` method of the `PagingState` to update the `pages`, `keys` and `hasNextPage` fields.
57+
- `appendPage` and `appendLastPage` have been removed. Use the `copyWith` method of the `PagingState` to update the `pages`, `keys` and `hasNextPage` fields.
5258
- `retryLastFailedRequest` was removed. You can simply call `fetchNextPage` to try again.
53-
- No longer accepts `invisibleItemsThreshold`. To configure the `invisibleItemsThreshold` of a layout, use the corresponding parameter of its `PagedChildBuilderDelegate`.
59+
- `invisibleItemsThreshold` parameter has been removed. To configure the `invisibleItemsThreshold` of a layout, use the corresponding parameter of its `PagedChildBuilderDelegate`.
5460

5561
## PagedLayoutBuilder
5662

@@ -108,61 +114,15 @@ Examples of using a custom state management solution can be found in the example
108114

109115
## PagingState
110116

111-
The PagingState in v5 has been updated to be more flexible:
117+
The PagingState has been updated to be more flexible:
112118

113119
- It now includes a List of all keys, `keys`, that have been fetched, each index corresponding to a page of items.
114120
- Instead of storing the next page key, it now includes a boolean `hasNextPage` to indicate if there are more pages to fetch.
115121
- Lastly it now also includes a loading state, in `isLoading`.
116122

117-
Most users probably do not directly interact with PagingState beyond reading it.
118-
However, the PagingState was also changed to allow customisation of its fields.
119-
120-
Instead of storing your Query parameters externally, you can now extend the PagingState to include them:
121-
122-
```dart
123-
final class MyPagingState<PageKeyType extends Object, ItemType extends Object>
124-
extends PagingStateBase<PageKeyType, ItemType> {
125-
MyPagingState({
126-
super.pages,
127-
// ...
128-
this.query,
129-
});
130-
131-
final String? query;
132-
133-
@override
134-
PagingState<PageKeyType, ItemType> copyWith({
135-
Defaulted<List<List<ItemType>>?>? pages = const Omit(),
136-
// ...
137-
Defaulted<String?>? query = const Omit(),
138-
}) {
139-
final partial = super.copyWith(
140-
pages: pages,
141-
// ...
142-
isLoading: isLoading,
143-
);
144-
145-
return MyPagingState(
146-
pages: partial.pages,
147-
// ...
148-
query: query is Omit ? this.query : query as String?,
149-
);
150-
}
151-
152-
@override
153-
PagingState<PageKeyType, ItemType> reset() {
154-
final partial = super.reset();
155-
156-
return MyPagingState(
157-
pages: partial.pages,
158-
// ...
159-
query: null,
160-
);
161-
}
162-
}
163-
```
164-
165-
Extended PagingStates will correctly work with PagingController, thanks to the `copyWith` and `reset` methods. For a better understanding of how this works, check out the source code.
123+
Because Items are now stored within pages, it is more difficult to modify the items directly.
124+
To make this easier, a `mapItems` extension method has been added to modify the items by iterating over them.
125+
Additionally, a `filterItems` extension method has been added to filter the items. This is useful for creating locally filtered computed states.
166126

167127
### API Changes
168128

@@ -171,3 +131,4 @@ Extended PagingStates will correctly work with PagingController, thanks to the `
171131
- `error` is now type Object? instead of dynamic.
172132
- `nextPageKey` was removed. You can use the `keys` field to compute the next page and `hasNextPage` to determine if there are more pages.
173133
- `isLoading` is a new field that indicates if a request is currently in progress.
134+
- `mapItems` and `filterItems` have been added to modify the items in a convenient way.

0 commit comments

Comments
 (0)