PPPHP

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.

Where to find it. In the Designer, open the Dashboard Widgets group in the components palette and drag Page Filter onto a dashboard or custom page.

Contents

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

  1. Drag a Page Filter onto the page.
  2. Set its URL parameter name — e.g. year. (Letters, numbers and _ only.)
  3. 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:

ModeWhat 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 pageA 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

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 fromWhat you set
Table columnA 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 SQLA 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 listHand-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.

Expressions are authored by you in the Designer (never by end users) and are compiled with the same safe, single-statement rule the platform uses for Add-page default values — anything that isn’t a valid one-line expression is treated as ordinary text, so it can’t run stray code.

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