FlutterArtist Pagination

Structure of the example
Teacher15aShelf
Query
Query More
Query Next
Query Previous
Pagable
PaginationInfo

Programmatic pagination is the process of using code to repeatedly call functions or methods provided by a library to query an API and retrieve data in smaller chunks. Instead of receiving a single massive response containing all data, the data is divided into smaller parts called pages, making it easier to process and manage.

This process is typically performed by sending a sequence of requests. Each subsequent request uses a token or cursor from the previous response to fetch the next page of data. The process continues until the response no longer returns a token or cursor, indicating that all data has been retrieved.

In this article, we learn how to use several methods related to Block pagination.

Download FlutterArtist Demo
FlutterArtist BlockNumberPagination Ex1
FlutterArtist ListView Infinite Scroll Pagination Example
FlutterArtist GridView Infinite Scroll Example
FlutterArtist Pagination Davi table Infinite Scroll ex1

1. Structure of the example

2. Teacher15aShelf

The pageable property of BlockConfig allows you to specify the number of ITEM(s) per page.

Teacher15aBlock( 
  config: BlockConfig(
    pageable: Pageable(pageSize: 3),
  ),
  ...
),

teacher15a_shelf.dart

class Teacher15aShelf extends Shelf {
  @override
  ShelfStructure defineShelfStructure() {
    return ShelfStructure(
      filterModels: {
        Teacher15aFilterModel.filterName: Teacher15aFilterModel(),
      },
      blocks: [
        Teacher15aBlock(
          name: Teacher15aBlock.blkName,
          description: null,
          config: BlockConfig(
            pageable: Pageable(pageSize: 3),
          ),
          filterModelName: Teacher15aFilterModel.filterName,
          formModel: null,
          childBlocks: [],
        ),
      ],
    );
  }

  Teacher15aBlock findTeacher15aBlock() {
    return findBlock(Teacher15aBlock.blkName) as Teacher15aBlock;
  }

  Teacher15aFilterModel findTeacher15aFilterModel() {
    return findFilterModel(Teacher15aFilterModel.filterName)
        as Teacher15aFilterModel;
  }
}

3. Query

Used to query a specific data page. The results will be merged into or replaced within the current list depending on the following criteria:

If filterCriteria or sortableCriteria change, the list of ITEM(s) just queried will definitely replace the current list.
If filterCriteria and sortableCriteria remain unchanged, the newly queried ITEM(s) will be merged into or replaced in the current list depending on the suggestedListUpdateStrategy parameter.

Block.query()

Future<BlockQueryResult> query({
  ListUpdateStrategy suggestedListUpdateStrategy = ListUpdateStrategy.replace,
  AfterQueryAction afterQueryAction =
      AfterQueryAction.setAnItemAsCurrentIfNeed,
  FILTER_INPUT? filterInput,
  SuggestedSelection? suggestedSelection,
  Pageable? pageable,
  Function()? navigate,
})

FlutterArtist Block.query() (***)

4. Query More

The queryMore() method uses the current conditions of the Block to retrieve the next page.

These conditions include:

currentItemId of the parent Block
filterCriteria
sortableCriteria
currentPage

This method retrieves the next page (currentPage + 1), which means a previous query() call must already exist. The result will be merged into the current ITEM(s) list of the Block.

queryMore()

Future<BlockQueryResult> queryMore({
  AfterQueryAction afterQueryAction = AfterQueryAction.setAnItemAsCurrentIfNeed,
})

5. Query Next

The queryNextPage() method retrieves the next page (currentPage + 1) based on the existing conditions. Unlike queryMore(), the query result replaces the current ITEM(s) list entirely.

queryNextPage()

Future<BlockQueryResult> queryNextPage({
  AfterQueryAction afterQueryAction = AfterQueryAction.setAnItemAsCurrentIfNeed,
})

6. Query Previous

The queryPreviousPage() method retrieves the previous page (currentPage - 1). The result replaces the current ITEM(s) list with data from the previous page.

queryPreviousPage()

Future<BlockQueryResult> queryPreviousPage({
  AfterQueryAction afterQueryAction = AfterQueryAction.setAnItemAsCurrentIfNeed,
})

7. Pagable

The pageable is a Block property that contains the pagination parameters used in the most recent query. This property is guaranteed to be non-null when the Block state is DataState.ready.

class Pageable {
  final int page;
  final int? pageSize;
}

teacher15a_pageable_view.dart

class Teacher15aPageableView extends BlockSectionView<Block> {
  static const TextStyle _smallTextStyle = TextStyle(fontSize: 13);

  const Teacher15aPageableView({super.key, required super.block});

  @override
  Widget buildContent(BuildContext context) {
    Pageable? pageable = block.pageable;
    //
    return CustomAppContainer(
      padding: EdgeInsets.all(5),
      width: double.maxFinite,
      child: Column(
        mainAxisAlignment: MainAxisAlignment.start,
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          Text(
            "The 'pageable' parameter is used in the latest query.",
            style: TextStyle(color: Colors.grey),
          ),
          SizedBox(height: 5),
          Text(
            "Block.pageable:",
            style: TextStyle(fontWeight: FontWeight.bold),
          ),
          SizedBox(height: 5),
          if (pageable != null) //
            Text("- Page: ${pageable.page}", style: _smallTextStyle),
          if (pageable != null) //
            Text("- PageSize: ${pageable.pageSize}", style: _smallTextStyle),
        ],
      ),
    );
  }
}

8. PaginationInfo

The paginationInfo is a Block property that provides the current pagination information. It is guaranteed to be non-null when the Block state is DataState.ready.

No ADS

interface class PaginationInfo {
  final int _currentPage;
  final int _pageSize;
  final int _totalItems;
  final int _totalPages; 

  int get currentPage => _currentPage;

  int get pageSize => _pageSize;

  int get totalItems => _totalItems;

  int get totalPages => _totalPages;
}

Note: To view the current pagination information of a Block, you can also use the DebugBlockStateView widget – a built-in widget of FlutterArtist.
FlutterArtist DebugBlockStateView

teacher15a_pagination_info_view.dart

class Teacher15aPaginationInfoView extends BlockSectionView<Teacher15aBlock> {
  static const TextStyle _smallTextStyle = TextStyle(fontSize: 13);

  const Teacher15aPaginationInfoView({super.key, required super.block});

  @override
  Widget buildContent(BuildContext context) {
    PaginationInfo? paginationInfo = block.paginationInfo;
    //
    return CustomAppContainer(
      padding: EdgeInsets.all(5),
      width: double.maxFinite,
      child: Column(
        mainAxisAlignment: MainAxisAlignment.start,
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          Text(
            "Current 'paginationInfo' of the block.",
            style: TextStyle(color: Colors.grey),
          ),
          SizedBox(height: 5),
          Text(
            "Block.paginationInfo:",
            style: TextStyle(fontWeight: FontWeight.bold),
          ),
          SizedBox(height: 5),
          if (paginationInfo != null) //
            Text(
              "- CurrentPage: ${paginationInfo.currentPage}",
              style: _smallTextStyle,
            ),
          if (paginationInfo != null) //
            Text(
              "- PageSize: ${paginationInfo.pageSize}",
              style: _smallTextStyle,
            ),
          if (paginationInfo != null) //
            Text(
              "- TotalItems: ${paginationInfo.totalItems}",
              style: _smallTextStyle,
            ),
          if (paginationInfo != null) //
            Text(
              "- TotalPages: ${paginationInfo.totalPages}",
              style: _smallTextStyle,
            ),
        ],
      ),
    );
  }
}