TablixJS Pagination API Documentation

Overview

TablixJS provides comprehensive pagination support for both client-side and server-side scenarios. The pagination system is designed to be performant, flexible, and easy to customize.

Features

• Client-side pagination: Slice data locally for small to medium datasets
• Server-side pagination: Async data loading for large datasets
• Consistent API: Same methods work for both modes
• Event hooks: React to pagination changes
• Customizable UI: Style pagination controls with CSS
• Keyboard navigation: Accessible pagination controls
• Page size controls: Allow users to change records per page
• Mobile responsive: Adapts to smaller screens

Basic Usage

Client-side Pagination

import Table from './src/core/Table.js';

const table = new Table('#myTable', {
  data: myDataArray,
  columns: [
    { name: 'id', title: 'ID' },
    { name: 'name', title: 'Name' }
  ],
  pagination: {
    enabled: true,
    pageSize: 10,
    mode: 'client'  // Default mode
  }
});

Server-side Pagination

// Define your server data loader
async function loadDataFromServer({ page, pageSize, filters, sorts }) {
  const response = await fetch(`/api/data?page=${page}&size=${pageSize}`);
  const result = await response.json();

  return {
    data: result.items,     // Array of records for current page
    totalRows: result.total // Total number of records
  };
}

const table = new Table('#myTable', {
  columns: [...],
  pagination: {
    enabled: true,
    pageSize: 25,
    mode: 'server',
    serverDataLoader: loadDataFromServer
  }
});

Configuration Options

All pagination options are configured in the pagination object:

pagination: {
  enabled: true,              // Enable/disable pagination
  pageSize: 10,              // Records per page
  mode: 'client',            // 'client' or 'server'

  // UI Display Options
  showPageNumbers: true,     // Show numbered page buttons
  maxPageNumbers: 5,         // Max page numbers to show before ellipsis
  showFirstLast: true,       // Show "First" and "Last" buttons
  showPrevNext: true,        // Show "Previous" and "Next" buttons
  showPageSizes: false,      // Show page size selector
  pageSizeOptions: [10, 25, 50, 100], // Available page sizes

  // Server-side Options
  serverDataLoader: null     // Function to load data from server
}

API Methods

Navigation Methods

// Go to specific page (1-indexed)
await table.goToPage(3);

// Navigate relative to current page
await table.nextPage();
await table.prevPage();
await table.firstPage();
await table.lastPage();

// Change page size
await table.changePageSize(25);

Information Methods

// Get current pagination state
const info = table.getPaginationInfo();
console.log(info);
// Returns:
// {
//   currentPage: 2,
//   totalPages: 10,
//   pageSize: 10,
//   totalRows: 95,
//   startRow: 11,
//   endRow: 20,
//   hasNextPage: true,
//   hasPrevPage: true,
//   isLoading: false
// }

Control Methods

// Enable/disable pagination dynamically
await table.setPaginationEnabled(false);
await table.setPaginationEnabled(true);

// Switch between client and server mode
await table.setPaginationMode('server', myServerLoader);
await table.setPaginationMode('client');

Events

Listen to pagination events to react to changes:

// Page navigation events
table.on('beforePageChange', ({ oldPage, newPage, pageSize }) => {
  console.log(`Navigating from page ${oldPage} to ${newPage}`);
});

table.on('afterPageChange', ({ oldPage, newPage, pageSize }) => {
  console.log(`Now on page ${newPage}`);
});

// Page size change events
table.on('beforePageSizeChange', ({ oldPageSize, newPageSize }) => {
  console.log(`Changing page size from ${oldPageSize} to ${newPageSize}`);
});

table.on('afterPageSizeChange', ({ newPageSize, page }) => {
  console.log(`Page size changed to ${newPageSize}, now on page ${page}`);
});

// Server-side loading events
table.on('beforePageLoad', ({ page, pageSize }) => {
  console.log('Loading data from server...');
});

table.on('afterPageLoad', ({ page, pageSize, data, totalRows }) => {
  console.log(`Loaded ${data.length} records for page ${page}`);
});

table.on('pageLoadError', (error) => {
  console.error('Failed to load page data:', error);
});

Server-side Data Loader

When using server-side pagination, your data loader function receives these parameters:

async function serverDataLoader({
  page,      // Current page number (1-indexed)
  pageSize,  // Number of records per page
  filters,   // Current filter criteria object
  sorts      // Current sort criteria array
}) {
  // Your server request logic here
  const response = await fetch(`/api/data`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ page, pageSize, filters, sorts })
  });

  const result = await response.json();

  // Must return this structure:
  return {
    data: result.records,    // Array of records for this page
    totalRows: result.total  // Total number of records (for pagination calculation)
  };
}

Integration with Filtering and Sorting

Pagination automatically integrates with filtering and sorting:

// When filtering, pagination resets to page 1
await table.filter({ name: 'John' });
console.log(table.getPaginationInfo().currentPage); // 1

// When sorting, pagination resets to page 1
await table.sort([{ column: 'name', direction: 'asc' }]);
console.log(table.getPaginationInfo().currentPage); // 1

For server-side pagination, your data loader will receive the current filter and sort state.

CSS Customization

The pagination controls use CSS classes that you can customize:

/* Main pagination container */
.tablix-pagination { }

/* Information text */
.tablix-pagination-info { }

/* Page size selector */
.tablix-pagination-page-size { }
.tablix-page-size-select { }

/* Navigation controls */
.tablix-pagination-nav { }
.tablix-pagination-btn { }
.tablix-pagination-btn.active { }
.tablix-pagination-btn[disabled] { }

/* Ellipsis */
.tablix-pagination-ellipsis { }

/* Loading indicator */
.tablix-pagination-loading { }

Performance Considerations

Client-side Pagination

• Best for datasets up to 10,000 records
• All data is kept in memory
• Filtering and sorting happen instantly
• No network requests for navigation

Server-side Pagination

• Best for large datasets (100,000+ records)
• Only current page data is kept in memory
• Network request required for each page
• Server handles filtering and sorting

Examples

See the complete examples in:

• examples/pagination.html - Comprehensive pagination examples
• examples/vanilla.html - Basic usage example

Migration from Legacy Code

If you're updating from a version without the pagination manager:

1. Update your table initialization to use the new options structure
2. Replace direct getPageData() calls with pagination methods
3. Add event listeners for pagination events
4. Update your CSS to use the new class names

// OLD
const table = new Table('#table', {
  pagination: { pageSize: 10 }
});

// NEW
const table = new Table('#table', {
  pagination: {
    enabled: true,
    pageSize: 10,
    showPageNumbers: true,
    showPageSizes: true
  }
});