PagyController<T> class

A controller that manages paginated API data and local item modifications.

PagyController is responsible for:

  • Fetching data from an API endpoint with pagination
  • Managing internal state via PagyState
  • Retrying failed requests with cached parameters
  • Allowing local updates to the item list without re-fetching

Key Responsibilities:

  • Holds the list of items and exposes them as read-only
  • Stores pagination, filter, and query parameters
  • Handles cancellation of requests
  • Integrates with PagyBuilder, PagyListView, and PagyGridView

Example Usage:

final controller = PagyController<User>(
  endPoint: '/users',
  fromMap: (json) => User.fromJson(json),
  responseMapper: (response) => PagyResponseParser.fromJson(response),
  limit: 20,
);

// Trigger load
controller.loadData();
Available extensions

Constructors

PagyController({required String endPoint, required T fromMap(Map<String, dynamic>), @Deprecated('Use responseParser instead') PagyResponseParser responseMapper(Map<String, dynamic> response)?, PagyResponseParser responseParser(Map<String, dynamic> response)?, String? token, @Deprecated('Use query instead') Map<String, dynamic>? additionalQueryParams, Map<String, dynamic>? query, int limit = 4, @Deprecated('Use payloadMode instead') PaginationPayloadMode? paginationMode, PaginationPayloadMode? payloadMode, dynamic payloadData, dynamic headers, PagyApiRequestType requestType = PagyApiRequestType.get})
Creates a PagyController for managing paginated data from an API.

Properties

additionalQueryParams → Map<String, dynamic>?
Extra query parameters appended to pagination params.
final
cancelToken ↔ CancelToken?
Internal cancel token to abort API requests in-flight.
getter/setter pair
controller → ValueNotifier<PagyState<T>>
Holds the API pagination state and notifies listeners on updates.
final
endPoint → String
The API endpoint used for fetching paginated data.
final
filter ↔ Map<String, dynamic>?
Internal filter object for persisting last applied filters.
getter/setter pair
fromMap → T Function(Map<String, dynamic>)
Converts raw JSON response into a model object of type T.
final
hashCode → int
The hash code for this object.
no setterinherited
headers → dynamic
Optional custom headers for API requests.
final
items → List<T>
Read-only, unmodifiable view of the current items list.
no setter
itemsList → List<T>
Internal storage of fetched items.
final
lastParams ↔ Map<String, dynamic>?
Last used request parameters, stored for retry functionality.
getter/setter pair
limit → int
Number of items to fetch per page (default: 4).
final
metadata → PagyMetadata
Returns pagination metadata for UI display.
no setter
paginationMode → PaginationPayloadMode?
Determines whether pagination params are sent as query or payload.
final
payloadData → dynamic
Optional static payload data included in API requests.
final
payloadMode → PaginationPayloadMode?
Mode for sending pagination parameters (query string or request body).
final
query → Map<String, dynamic>?
Query parameters to append to API requests.
final
requestType → PagyApiRequestType
Defines the HTTP method used for requests.
final
responseMapper → PagyResponseParser Function(Map<String, dynamic> response)?
Function to parse API response into a PagyResponseParser.
final
responseParser → PagyResponseParser Function(Map<String, dynamic> response)?
Function to parse API response into a PagyResponseParser.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
state → PagyState<T>
Current pagination state exposed from controller.
no setter
token → String?
Optional token to include in API request headers (e.g., Bearer token).
final

Methods

addItem(T item, {bool atStart = false}) → void

Available on PagyController<T>, provided by the PagyControllerHelpers extension

Adds a single item to the list.
addItems(List<T> items, {bool atStart = false}) → void

Available on PagyController<T>, provided by the PagyControllerHelpers extension

Adds multiple items to the list.
applyFilters(Map<String, dynamic> filters) → Future<void>
Applies filters and reloads data from page 1.
dispose() → void

Available on PagyController<T>, provided by the PagyControllerHelpers extension

Disposes the underlying ValueNotifier to free resources.
insertAt(int index, T item) → void

Available on PagyController<T>, provided by the PagyControllerHelpers extension

Inserts an item at a specific index.
listen(void onChanged(List<T> items)) → void

Available on PagyController<T>, provided by the PagyControllerHelpers extension

Attaches a listener that is called whenever the items list changes.
loadData({bool refresh = true, Map<String, dynamic>? queryParameter, PaginationPayloadMode? paginationMode, dynamic payloadData}) → Future<void>

Available on PagyController<T>, provided by the PagyControllerLoader extension

Loads paginated data from the API.
loadMore() → Future<void>
Explicitly loads the next page of data.
mapItems(T mapper(T old)) → void

Available on PagyController<T>, provided by the PagyControllerHelpers extension

Maps all items in the list using the provided mapper function.
modifyDirect(ValueUpdater<PagyState<T>> updater) → void

Available on PagyController<T>, provided by the PagyControllerHelpers extension

Directly modifies the PagyState using an updater callback.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
refresh() → Future<void>
Clears current data and reloads from page 1.
removeWhere(bool test(T item)) → void

Available on PagyController<T>, provided by the PagyControllerHelpers extension

Removes items that match the given test condition.
replaceWhere(bool test(T item), T newItem) → void

Available on PagyController<T>, provided by the PagyControllerHelpers extension

Replaces the first item matching test with newItem.
reset() → void

Available on PagyController<T>, provided by the PagyControllerHelpers extension

Resets the controller to its initial empty state.
retry() → Future<void>

Available on PagyController<T>, provided by the PagyControllerLoader extension

Retries the last failed request if parameters exist.
Performs a search with the given query.
toString() → String
A string representation of this object.
inherited
updateData(List<T> newData) → void

Available on PagyController<T>, provided by the PagyControllerHelpers extension

Replaces the entire dataset with newData.
updateItemAt(int index, T newItem) → void

Available on PagyController<T>, provided by the PagyControllerHelpers extension

Updates the item at index with newItem.

Operators

operator ==(Object other) → bool
The equality operator.
inherited