* Added error logs

* Optimized initializing PaginatedItemsBuilder
* Added showLoaderOnResetBuilder in PaginationItemsStateHandler to update showLoaderOnReset param for builders with internal state management.
* Updated example app
* Updated README.md
* Updated version

Author: rithik-dev

CHANGELOG.md

@@ -1,3 +1,11 @@
+## [1.1.0] - 01/04/2022
+
+* Added error logs
+* Optimized initializing PaginatedItemsBuilder
+* Added showLoaderOnResetBuilder in PaginationItemsStateHandler to update showLoaderOnReset param for builders with internal state management.
+* Updated example app
+* Updated README.md
+
 ## [1.0.9] - 31/03/2022
 
 * Added ignore pointer to disable onTap for loaders

README.md

@@ -52,14 +52,18 @@ Future<void> updateProducts({
     notifyListeners();
   }
 
-  final res = await apiFunction(
-    // startKey is optional and only required when you have pagination support in api
-    startKey: reset ? null : _productsResponse?.paginationKey,
-  );
-  if (reset || _productsResponse == null) {
-    _productsResponse = res;
-  } else {
-    _productsResponse!.update(res);
+  try {
+    final res = await apiFunction(
+      // startKey is optional and only required when you have pagination support in api
+      startKey: reset ? null : _productsResponse?.paginationKey,
+    );
+    if (reset || _productsResponse == null) {
+      _productsResponse = res;
+    } else {
+      _productsResponse!.update(res);
+    }
+  } catch(_) {
+    // handle error
   }
   notifyListeners();
 }
@@ -72,23 +76,36 @@ Future<PaginatedItemsResponse<Product>?> apiFunction({
   // can be string or int (page number) or any other type.
   dynamic startKey,
 }) async {
-  // startKey necessary if pagination support
-  final res = await _api.getProducts(startKey: startKey);
-
-  return PaginatedItemsResponse<Product>(
-
-    // list of items
-    listItems: res.data?.products,
-
-    // only required to pass if pagination supported, else null. (can be of any type)
-    paginationKey: res.data?.paginationKey,
-
-    // unique id, should only be passed in the repository function.
-    // required for functions like `updateItem`, `findByUid`
-    // and avoiding duplication of items in list (compares uid)
-    idGetter: (product) => product.id,
-
-  );
+ try {
+   // startKey necessary if pagination support
+   final res = await _api.getProducts(startKey: startKey);
+
+   return PaginatedItemsResponse<Product>(
+
+     // list of items
+     listItems: res.data?.products,
+
+     // only required to pass if pagination supported, else null. (can be of any type)
+     paginationKey: res.data?.paginationKey,
+
+     // unique id, should only be passed in the repository function.
+     // required for functions like `updateItem`, `findByUid`
+     // and avoiding duplication of items in list (compares uid)
+     idGetter: (product) => product.id,
+
+   );
+ } catch(_) {
+   // handling error is important as if null is returned, the `response` becomes null,
+   // which in turn causes infinite loading...
+   
+   // hence, returning a response with empty list, so that screen shows the no items found text, 
+   // so that the user can refresh the contents, and you can probably have a snackBar or toast, 
+   // notifying the user of the error...
+   return  PaginatedItemsResponse<Product>(
+     listItems: [],
+     idGetter: (product) => product.id,
+   );
+ }
 }
 ```
 
@@ -145,6 +162,7 @@ Future<PaginatedItemsResponse<Post>?> updatePosts(dynamic paginationKey) async {
 
 PaginationItemsStateHandler<Post>(
     fetchPageData: updatePosts,
+    showLoaderOnResetBuilder: (itemsFetchScope) => itemsFetchScope == ItemsFetchScope.noItemsRefresh,
     builder: (response, fetchPageData) {
         return PaginatedItemsBuilder<Post>(
             response: response,

example/lib/controllers/posts_controller.dart

@@ -25,13 +25,17 @@ class PostsController extends ChangeNotifier {
       notifyListeners();
     }
 
-    final res = await PostsRepository.getPosts(
-      startKey: _postsResponse?.paginationKey,
-    );
-    if (reset || _postsResponse == null) {
-      _postsResponse = res;
-    } else {
-      _postsResponse!.update(res);
+    try {
+      final res = await PostsRepository.getPosts(
+        startKey: reset ? null : _postsResponse?.paginationKey,
+      );
+      if (reset || _postsResponse == null) {
+        _postsResponse = res;
+      } else {
+        _postsResponse!.update(res);
+      }
+    } catch (_) {
+      // handle error
     }
     notifyListeners();
   }

example/lib/screens/home_screen.dart

@@ -78,6 +78,8 @@ class PostsListWithStateHandledInternally extends StatelessWidget {
       child: Scaffold(
         body: PaginationItemsStateHandler<Post>(
           fetchPageData: updatePosts,
+          showLoaderOnResetBuilder: (itemsFetchScope) =>
+              itemsFetchScope == ItemsFetchScope.noItemsRefresh,
           builder: (response, fetchPageData) {
             return PaginatedItemsBuilder<Post>(
               response: response,

example/pubspec.lock

@@ -129,7 +129,7 @@ packages:
       path: ".."
       relative: true
     source: path
-    version: "1.0.9"
+    version: "1.1.0"
   path:
     dependency: transitive
     description:

lib/src/paginated_items_builder.dart

@@ -1,3 +1,4 @@
+import 'dart:developer' as dev;
 import 'dart:math';
 
 import 'package:flutter/material.dart';
@@ -182,6 +183,7 @@ class _PaginatedItemsBuilderState<T> extends State<PaginatedItemsBuilder<T>> {
         (widget.response != null &&
             !widget.response!.hasMoreData &&
             !_loadingMoreData)) return;
+
     setState(() {
       // if (_initialLoading) {
       //   _initialLoading = false;
@@ -195,10 +197,18 @@ class _PaginatedItemsBuilderState<T> extends State<PaginatedItemsBuilder<T>> {
 
     try {
       await widget.fetchPageData(reset, itemsFetchScope);
-    } catch (_) {}
+    } catch (error, stackTrace) {
+      dev.log(
+        '\nSomething went wrong.. Most probably the fetchPageData failed due to some error! Please handle any possible errors in the fetchPageData call.',
+        name: 'PaginationItemsBuilder<$T>',
+        error: error,
+        stackTrace: stackTrace,
+      );
+    }
 
     if (_initialLoading) _initialLoading = false;
     if (_loadingMoreData) _loadingMoreData = false;
+
     try {
       setState(() {});
     } catch (_) {}
@@ -289,11 +299,7 @@ class _PaginatedItemsBuilderState<T> extends State<PaginatedItemsBuilder<T>> {
         ? _config?.mockItemGetter<T>()
         : _config?.mockItemGetter(widget.mockItemKey);
 
-    final itemsStateHandlerAsParent =
-        context.findAncestorWidgetOfExactType<PaginationItemsStateHandler<T>>();
-    if (itemsStateHandlerAsParent == null) {
-      _fetchData(itemsFetchScope: ItemsFetchScope.initialLoad);
-    }
+    _fetchData(itemsFetchScope: ItemsFetchScope.initialLoad);
 
     PaginatedItemsBuilder.config ??=
         PaginatedItemsBuilderConfig.defaultConfig();

lib/src/pagination_items_state_handler.dart

@@ -1,3 +1,5 @@
+import 'dart:developer' as dev;
+
 import 'package:flutter/material.dart';
 import 'package:paginated_items_builder/paginated_items_builder.dart';
 
@@ -22,10 +24,28 @@ class PaginationItemsStateHandler<T> extends StatefulWidget {
         fetchPageData,
   ) builder;
 
+  /// Whether to switch all the cards to their respective loaders when [reset] is true,
+  /// i.e. if the user pulls down to refresh, or no items were found...
+  ///
+  /// The callback value is the [ItemsFetchScope], which defines the action calling the
+  /// fetch data function.
+  ///
+  /// The [reset] flag will be true only when the [itemsFetchScope] is either
+  /// [ItemsFetchScope.noItemsRefresh] i.e. no items were found, and user
+  /// clicked the refresh icon OR [ItemsFetchScope.pullDownToRefresh] i.e.
+  /// the user wants to refresh the list contents with pull-down action.
+  ///
+  /// This callback will only be called if [reset] is true.
+  ///
+  /// By default, [showLoaderOnResetBuilder] is true only if [scope] is [ItemsFetchScope.noItemsRefresh].
+  final bool Function(ItemsFetchScope itemsFetchScope)?
+      showLoaderOnResetBuilder;
+
   const PaginationItemsStateHandler({
     Key? key,
     required this.fetchPageData,
     required this.builder,
+    this.showLoaderOnResetBuilder,
   }) : super(key: key);
 
   @override
@@ -35,36 +55,43 @@ class PaginationItemsStateHandler<T> extends StatefulWidget {
 
 class _PaginationItemsStateHandlerState<T>
     extends State<PaginationItemsStateHandler<T>> {
-  PaginatedItemsResponse<T>? itemsResponse;
+  PaginatedItemsResponse<T>? _itemsResponse;
 
   Future<void> _update(bool reset, ItemsFetchScope scope) async {
-    if (reset) {
-      itemsResponse = null;
+    bool showLoaderOnReset = scope == ItemsFetchScope.noItemsRefresh;
+    if (reset && widget.showLoaderOnResetBuilder != null) {
+      showLoaderOnReset = widget.showLoaderOnResetBuilder!(scope);
+    }
+
+    // showLoaderOnReset only used if reset is true...
+    if (reset && showLoaderOnReset) {
+      _itemsResponse = null;
       setState(() {});
     }
 
     try {
-      final res = await widget.fetchPageData(itemsResponse?.paginationKey);
-      if (itemsResponse == null) {
-        itemsResponse = res;
+      final res = await widget.fetchPageData(
+        reset ? null : _itemsResponse?.paginationKey,
+      );
+      if (reset || _itemsResponse == null) {
+        _itemsResponse = res;
       } else {
-        itemsResponse!.update(res);
+        _itemsResponse!.update(res);
       }
-    } catch (_) {}
+    } catch (error, stackTrace) {
+      dev.log(
+        '\nSomething went wrong.. Most probably the fetchPageData failed due to some error! Please handle any possible errors in the fetchPageData call.',
+        name: 'PaginationItemsStateHandler<$T>',
+        error: error,
+        stackTrace: stackTrace,
+      );
+    }
 
     try {
       setState(() {});
     } catch (_) {}
   }
 
   @override
-  void initState() {
-    _update(false, ItemsFetchScope.initialLoad);
-    super.initState();
-  }
-
-  @override
-  Widget build(BuildContext context) {
-    return widget.builder(itemsResponse, _update);
-  }
+  Widget build(BuildContext context) => widget.builder(_itemsResponse, _update);
 }

pubspec.yaml

@@ -1,6 +1,6 @@
 name: paginated_items_builder
 description: Easier to display items in a list/grid view from your controllers directly or handling state internally with support for pagination.
-version: 1.0.9
+version: 1.1.0
 homepage: https://github.com/rithik-dev/paginated_items_builder
 
 environment: