Skip to main content

How to implement custom pagination

This recipe demonstrates how to implement cursor-based pagination using custom pagination utilities in Rell and consume it from a client. This approach provides full control over pagination logic and is ideal for projects that need customized pagination behavior.

Prerequisites​

Demo script​

Key Features​

This recipe includes examples for:

  • Custom pagination utilities - Custom-built pagination logic with full control over cursor behavior
  • Offset-based pagination - Uses offset and limit for data retrieval with page tracking
  • Custom cursor encoding - Base64-encoded cursors with page number tracking
  • Flexible page sizing - Configurable page sizes with maximum limits

Architecture Overview​

The recipe includes both server and client components:

Rell Module (Server-side)​

  • Entity: user with name field for demonstration
  • Query: get_users_paginated with page_cursor and data_size parameters returning custom paged_result
  • Operation: add_user for seeding test data
  • Custom utilities: paginator.rell module with pagination helper functions

JavaScript Client​

  • First page request - Fetches initial data with page_cursor set to null
  • Subsequent pages - Uses next_cursor from previous response
  • Page size control - Uses data_size parameter for configurable page sizes

Custom Pagination Pattern​

The Rell implementation uses custom pagination utilities:

Pagination Structures​

  • page_cursor: Tracks current page position with after_rowid and after_page
  • pagination_result: Contains data and rowid for each result item
  • paged_result: Standard response format with data and next_cursor

Cursor Management​

  • encode_cursor: Converts cursor to base64-encoded string
  • decode_cursor: Parses cursor from client requests
  • Page tracking: Maintains current page number for offset calculations

Query Processing​

  • fetch_data_size: Fetches one extra item to determine if more pages exist
  • query_offset_for_page_size: Calculates offset based on current page
  • make_page: Constructs response with appropriate next cursor

Client Usage Pattern​

The JavaScript client demonstrates the pagination flow:

  • Initial request sets page_cursor to null and specifies data_size
  • Each response includes data array and optional next_cursor
  • Subsequent requests use the next_cursor to fetch following pages
  • Pagination continues until next_cursor is null

Customization Benefits​

This custom approach offers several advantages:

  • Full control - Complete control over pagination logic and cursor format
  • Flexible implementation - Easy to modify pagination behavior for specific needs
  • Performance optimization - Can implement custom indexing and query optimizations
  • Custom metadata - Can include additional pagination metadata in responses

Use Cases​

This custom pagination approach is ideal for:

  • Custom sorting requirements - Complex sorting that doesn't fit standard patterns
  • Specialized cursor logic - Need for custom cursor encoding or metadata
  • Performance optimization - Projects requiring specific query optimization strategies
  • Legacy integration - Matching existing API pagination formats

Learn more​