Page Filter
A Page Filter turns one dropdown into the key for the whole page. The user picks a value — an academic year, a branch, a status — and every data component on the page (Table Cards, KPI tiles, charts, mini-tables…) re-shows its numbers for that selection. It is how you build a “Select Academic Year”-style dashboard where one control drives the entire screen.
Contents
- How it works — a URL key
- Set it up in three steps
- Make components react to it
- An “All” / show-everything option
- Instant refresh (AJAX) vs full reload
- Where the dropdown’s choices come from
- Static options can be dynamic (PHP)
- More than one filter on a page
- Appearance
- Notes & gotchas
How it works — a URL key
The Page Filter writes its value into the page’s web address as a query parameter. Choosing
2083 in a filter whose parameter is year takes the page to ?year=2083. Because the
generated app renders on the server, the page runs every component’s query again — and any component that mentions
:get.year in its filter now sees 2083. No wiring between components, no JavaScript to write.
By default this happens instantly, in place (AJAX — see below) rather than as a
full reload.
① User picks 2083 ② Address becomes ?year=2083 ③ Every component re-queries
in the Page Filter (pagination resets) WHERE academic_year = :get.year
Set it up in three steps
- Drag a Page Filter onto the page.
- Set its URL parameter name — e.g.
year. (Letters, numbers and_only.) - Point its Options at where the choices live — a table column, a SQL query, or a static list (see below).
That’s the control done. Now tell your components to listen to it.
Make components react to it
In any data component, reference the filter’s parameter with :get.<param> (or the friendlier
alias :param.<param>). For a Table Card:
-- Table Card in Table mode → its Filter (WHERE) box:
academic_year = :get.year
-- Table Card in Custom SQL mode (a "Top 10" card scoped to the year):
SELECT school AS 'School', SUM(qty) AS 'Books'
FROM chalans
WHERE academic_year = :get.year
GROUP BY school ORDER BY SUM(qty) DESC LIMIT 10
The same token works anywhere a query does — KPI tiles, charts, mini-tables, the list page’s WHERE. The value is inserted safely (escaped and quoted for you) — you never add quotes yourself.
An “All” / show-everything option
By default, before anything is picked the parameter is empty, so academic_year = :get.year matches
nothing and the cards start blank — which is often what you want (“choose a year first”). To make the empty
choice mean All instead, tick Empty option means “All” on the filter and write the WHERE like
this:
(:get.year = '' OR academic_year = :get.year)
When nothing is selected the first half is true → every row shows; once a year is picked it filters. One line, and the card does both.
Instant refresh (AJAX) vs full reload
Under Behaviour → On change you choose how the page updates:
| Mode | What happens |
|---|---|
| Refresh in place (AJAX) (default) | The page quietly re-fetches itself for the new value and swaps the fresh data in — no full reload, no white flash, no scroll jump. The address bar still updates, so the view stays bookmarkable and the browser’s Back / Forward buttons move between selections. |
| Reload page | A classic full page navigation. Simplest and identical in result; you’ll see the page reload. |
AJAX mode is self-healing: if a refresh ever fails (network blip, session timeout) it automatically falls back to a real reload, so the page can never be left showing stale data.
What gets refreshed
- Whole page content (default) — replaces everything in the page body. The simplest choice; every component on the page updates, no matter what it is.
- Only matching components — surgically replaces just the elements you name with a CSS selector (blank = all built-in data widgets). The filter keeps its place and untouched areas don’t even flicker. Use this when a page mixes filtered cards with static content you’d rather leave alone.
You can also show a loading state (the refreshing area dims with a spinner) and optionally scroll to top after each change. It all works the same across every database engine.
Where the dropdown’s choices come from
| Options from | What you set |
|---|---|
| Table column | A table + a value column (and an optional label column). It lists the distinct values — e.g. every academic_year in chalans. Respects Row-Level Security. |
| Custom SQL | A read-only SELECT returning a value column (aliased value) and an optional label. e.g. SELECT year AS value, CONCAT('BS ', year) AS label FROM academic_years ORDER BY year DESC. |
| Static list | Hand-typed value/label pairs — perfect for a small fixed set that isn’t in a table. Each value/label can also be a PHP expression, so a “static” list can stay current. |
Static options can be dynamic (PHP expressions)
A static option’s Value or Label can be a small PHP expression that is evaluated every time the page loads — so a hand-typed list never goes stale. Type plain text for a fixed value, or an expression for a rolling one:
Value Result (in 2026)
date('Y') 2026 ← this year
date('Y')-1 2025 ← last year
date('Y')+1 2027 ← next year
2025 2025 ← plain text stays literal
'FY '.date('Y') FY 2026 ← a computed Label
So a “last year / this year / next year” academic-year picker needs just three options —
date('Y')-1, date('Y'), date('Y')+1 — and it’s always right, no yearly edit.
More than one filter on a page
Add several Page Filters with different parameter names (year, branch,
status). Each one only changes its own parameter and keeps the others intact, so components can combine
them:
academic_year = :get.year AND branch_id = :get.branch
Appearance
Set an optional caption above the dropdown, choose align (left / center / right), size and width, and style the control’s background, text, font, border colour and corner radius. Turn Reload on change off if you’d rather show an Apply button (useful when you have several filters and want to change them all before reloading).
Notes & gotchas
- The parameter name is the contract. If the filter’s parameter is
year, components must reference:get.year— the two must match exactly. - Picking a value resets pagination (the
pageparameter is cleared) so a filtered list starts on page 1. - It works on any page — dashboards, custom pages, even a list page (combine with the list’s own WHERE).
- Bookmarkable. Because the selection lives in the URL, a filtered view can be shared or bookmarked and it reopens on the same selection.
- Every engine. Options queries are written in MySQL and auto-translated, so a Page Filter works the same on PostgreSQL, SQL Server and SQLite.