PPPHP

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

EventWhere to write itUse for
Custom WHERETable → SQL ModifiersFilter which rows appear.
Custom ORDER BYTable → SQL ModifiersSet the default sort.
After List LoadTable → Page Events (PHP)Read/adjust the rows after they're fetched.
Process Record ValuesTable → Page Events (PHP)Reshape a value just for display.
After List RenderTable → Client Events (JS)Colour rows, add handlers, totals.
On Row Click / On Row SelectTable → 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:

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.