The List page
The List page shows many records in a grid — with search, sort, selection and bulk actions. This guide walks its events and gives copy-ready recipes, each labelled with exactly where the code goes.
Events this page fires
| Event | Where to write it | Use for |
|---|---|---|
| Custom WHERE | Table → SQL Modifiers | Filter which rows appear. |
| Custom ORDER BY | Table → SQL Modifiers | Set the default sort. |
| After List Load | Table → Page Events (PHP) | Read/adjust the rows after they're fetched. |
| Process Record Values | Table → Page Events (PHP) | Reshape a value just for display. |
| After List Render | Table → Client Events (JS) | Colour rows, add handlers, totals. |
| On Row Click / On Row Select | Table → Client Events (JS) | React to a click / a tick. |
Filtering the list no code
Every list has a built-in, Excel-style Set Filter — no setup, no SQL:
- Filter panel (the toolbar button) — one control per field you flagged “Filter” in the Fields module. Pick values and press Apply; the active filters show as removable chips with a Clear all.
- Column funnels — turn on Header filters on the grid (Designer → Data Grid), or the per-column Header filter, and each column header gets a you can click to filter right there.
- It picks the right control for the field: a text or coded field opens a searchable value list (distinct values, counts, Select-all, and friendly labels — “Male”, not “1”); a number or date field opens a range (min–max / from–to) instead. Values load live and never show rows a user isn’t allowed to see.
- Want a specific control? Open the field’s Filter control in the Designer and choose Value / Lookup dropdown, Yes-No, Number range, Date range, or plain Text — each with the same Variant / Colour / Size styling as the input controls. Auto = the smart Set-Filter above.
Filtering multi-select and lookup fields
A multi-select field (a lookup that stores several values, e.g. Tags = “2,5,9”) matches a row when it holds any value you tick — tick “5” and a record tagged “2,5,9” is found, one tagged “15” is not. Lookup values are listed and searched by their display name, including a custom display such as “first name + last name”.
Recipes
1 · Show only the current user's records
WhereEvents → orders → SQL Modifiers → Custom WHEREPHP
// Return a WHERE clause (no leading "WHERE"). Non-admins see only their own rows.
if (!\PpPhp\Core\Auth\Permissions::isAdmin()) {
return 'created_by = ' . (int) (\PpPhp\Core\Security::CurrentUserData()['id'] ?? 0);
}
return ''; // admins see everything
2 · Newest first by default
WhereEvents → orders → SQL Modifiers → Custom ORDER BYPHP
return 'created_at DESC';
3 · Colour rows by a condition
WhereEvents → orders → Client Events → After List RenderJS
Runner.rows().forEach(function (row) {
if ((+row.get('balance') || 0) < 0) row.highlight('rgba(220,38,38,.12)'); // overdue → red tint
else if (row.get('status') === 'shipped') row.highlight('rgba(34,197,94,.10)');
});
4 · Show a running total under the grid
WhereEvents → orders → Client Events → After List RenderJS
var total = Runner.getAllRecords().reduce(function (s, r) { return s + (+r.amount || 0); }, 0);
pp.dialog.toast('info', 'Total on this page: ' + total.toFixed(2));
5 · Bulk action on the ticked rows (toolbar Custom Button)
Drop a Custom Button on the list toolbar in the Designer, then fill its three boxes:
WhereDesigner → Custom Button → Client BeforeJS
params.ids = Runner.getSelectedKeys();
if (!params.ids.length) { pp.dialog.toast('warning', 'Select at least one row.'); return false; }
WhereDesigner → Custom Button → ServerPHP
$ids = array_map('intval', (array) ($params['ids'] ?? []));
if ($ids) {
$in = implode(',', array_fill(0, count($ids), '?'));
dbExecute("UPDATE orders SET status = 'shipped' WHERE id IN ($in)", $ids);
}
$result['count'] = count($ids);
WhereDesigner → Custom Button → Client AfterJS
pp.dialog.toast('success', result.count + ' order(s) marked shipped.');
Runner.reloadGrid();
6 · Hide the bulk “Delete selected” for non-admins
WhereEvents → orders → Client Events → On Page InitJS
// (expose a flag from PHP with pp_set_proxy, or check a data attribute you render)
Runner.hideButton('deleteSelected');
7 · Row click opens a custom action instead of the record
WhereEvents → orders → Client Events → On Row ClickJS
// `record` is the clicked row's data; return false to prevent the default open
pp.dialog.alert('Order ' + record.reference, 'Total: ' + record.total);
return false;
8 · React to selection changes
WhereEvents → orders → Client Events → On Page InitJS
Runner.onSelectionChange(function (keys, records) {
var sum = records.reduce(function (s, r) { return s + (+r.amount || 0); }, 0);
console.log(keys.length + ' selected · ' + sum);
});
All the grid helpers —
Runner.rows(), getSelectedRecords(),
reloadGrid(), row .highlight() — are in the
PP.js reference. Filtering/sorting SQL is trusted, like
DB helpers.