Samir Boulahtit
f7e3382b10
- Rewrite pagination.md for server-side pagination approach - Update quick-start guide with new implementation pattern - Document shared pattern across Vendors, Companies, Users pages - Add examples for filters, search, and API integration 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
179 lines
5.0 KiB
Markdown
179 lines
5.0 KiB
Markdown
# 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
|
|
```javascript
|
|
// 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
|
|
```json
|
|
{
|
|
"vendors": [...],
|
|
"total": 45,
|
|
"skip": 0,
|
|
"limit": 10
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
### Change Items Per Page
|
|
|
|
Edit in JavaScript file:
|
|
```javascript
|
|
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:
|
|
```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.
|