orion/docs/frontend/shared/pagination-quick-start.md

Pagination & Search - Quick Start Guide

Overview

All admin list pages use consistent server-side pagination with search and filters.

Pages using this pattern:

• /admin/vendors - Vendor Management
• /admin/companies - Company Management
• /admin/users - User Management

---

Visual Layout

┌──────────────────────────────────────────────────────────────────┐
│ Page Title                                    [+ Create Button]  │
├──────────────────────────────────────────────────────────────────┤
│ [Stat 1] [Stat 2] [Stat 3] [Stat 4]              ← Stats Cards   │
├──────────────────────────────────────────────────────────────────┤
│ [🔍 Search...    ] [Filter ▼] [Filter ▼] [Refresh] ← Search Bar  │
├──────────────────────────────────────────────────────────────────┤
│ Column 1 │ Column 2 │ Column 3 │ Actions                         │
├──────────┼──────────┼──────────┼─────────────────────────────────┤
│ Row 1    │ ...      │ ...      │ 👁 ✏️ 🗑                        │
│ Row 2    │ ...      │ ...      │ 👁 ✏️ 🗑                        │
│ ...      │ ...      │ ...      │ ...                             │
├──────────────────────────────────────────────────────────────────┤
│ Showing 1-10 of 45                  ← 1 2 [3] 4 ... 9 →          │
└──────────────────────────────────────────────────────────────────┘

---

Key Features

Feature	Description
Server-side pagination	Uses skip/limit API params
Debounced search	300ms delay before API call
Filter dropdowns	Status, Verification, Role filters
Smart page numbers	Shows ellipsis for large page ranges
Refresh button	Manually reload data
Contextual empty state	Different message when filters applied

---

State Structure

JavaScript State

// Filters
filters: {
    search: '',
    is_active: '',      // 'true', 'false', or ''
    is_verified: '',    // 'true', 'false', or ''
}

// Pagination
pagination: {
    page: 1,
    per_page: 10,
    total: 0,
    pages: 0
}

---

Computed Properties

Property	Purpose
totalPages	Total number of pages
startIndex	First item number on current page
endIndex	Last item number on current page
pageNumbers	Array of page numbers with '...'

---

Methods

Method	Purpose
debouncedSearch()	Triggers search after 300ms
previousPage()	Go to previous page
nextPage()	Go to next page
goToPage(num)	Jump to specific page

---

Page Number Display

Few pages (7 or less):

← 1 2 3 4 5 6 7 →

Many pages, at start:

← [1] 2 3 ... 10 →

Many pages, in middle:

← 1 ... 4 [5] 6 ... 10 →

Many pages, at end:

← 1 ... 8 9 [10] →

---

API Integration

Request

GET /admin/vendors?skip=0&limit=10&search=acme&is_active=true

Response

{
    "vendors": [...],
    "total": 45,
    "skip": 0,
    "limit": 10
}

---

Configuration

Change Items Per Page

Edit in JavaScript file:

pagination: {
    page: 1,
    per_page: 25,  // Change from 10
    total: 0,
    pages: 0
}

---

Files Reference

Page	Template	JavaScript
Vendors	templates/admin/vendors.html	static/admin/js/vendors.js
Companies	templates/admin/companies.html	static/admin/js/companies.js
Users	templates/admin/users.html	static/admin/js/users.js

---

Adding to a New Page

1. Add state to JavaScript:

filters: { search: '', is_active: '' },
pagination: { page: 1, per_page: 10, total: 0, pages: 0 }

2. Add computed properties: totalPages, startIndex, endIndex, pageNumbers

3. Add methods: debouncedSearch(), previousPage(), nextPage(), goToPage()

4. Update load function to use query params

5. Add HTML for search bar and pagination footer

See docs/frontend/shared/pagination.md for full implementation details.