Events & the page lifecycle
Your app runs your code at events — precise moments in a page's life. This guide shows every event, when it fires, and exactly where to paste your code. Two kinds: Server events run in PHP on the server; Client events run in JS in the browser.
Contents
- The page lifecycle
- Where each event lives in the Events module
- Page events (server · PHP)
- Client events (browser · JS)
- Field events
- Button events
- Global events
- Worked examples (with “Where”)
The page lifecycle
When a visitor opens a page, events fire in order. A record being saved on the Add page, for example, runs:
Pick the event by what you need: change what the user sees before they type → a Before … Load event; validate or change data before it's written → a Before … Save event; react after it's stored (email, log, redirect) → an After … Save event.
Where each event lives in the Events module
Open Events in your project. Events are grouped so you always know where to click:
| You want… | Go to |
|---|---|
| Something on one table's List/Add/Edit/View/Print/Export/Import | Table → pick the table → Page Events (PHP) or Client Events (JS) |
| Change the rows a list shows (filter/sort) | Table → SQL Modifiers → Custom WHERE / ORDER BY |
| React when one field changes / format one field | Table → Fields → pick the field → Client (On Change…) or Server (Calculate…) |
| Login, register, email, app start-up | Global Events → Authentication / Email / Application… |
| A named routine you call from JS | Custom Functions → PHP (action_<name>) — call it with pp.run('name', {…}) |
Page events — server (PHP)
Reached at Events → <Table> → Page Events. Each hands you variables to work with.
| Event | Page | Fires | Key variables |
|---|---|---|---|
| After List Load | List | after the rows are read | $rows |
| Before Add Load | Add | before the empty form shows | $data (defaults) |
| Before Add Save | Add | before insert — validate/alter | $data (by ref), $errors |
| After Add Save | Add | after insert — email/log | $data, $id |
| Before Edit Load | Edit | before the form is filled | $data, $id |
| Before Edit Save | Edit | before update | $data (by ref), $old, $id, $errors |
| After Edit Save | Edit | after update | $data, $old, $id |
| Before / After Delete | List/View | around a delete | $id |
| Before View Load | View | before the record shows | $data, $id |
| Before Search | List | before a search runs | $searchFor |
| Before / After Export · Import | Export/Import | around data transfer | $data / rows |
| On Print | Print/PDF | when a printable page renders | $data |
| Process Record Values | List/View | to reshape a value for display | $data |
Client events — browser (JS)
Reached at Events → <Table> → Client Events. Here the Runner / pp.js API shines.
| Event | Page | Fires |
|---|---|---|
| On Page Init | any | as soon as the page is ready — your “on load” hook |
| After List Render | List | after the grid is drawn (colour rows, add handlers) |
| On Row Click · On Row Select | List | when a row is clicked / ticked |
| Before Form Submit | Add/Edit | before the form posts — return false to stop it |
| After Delete Success | List/View | after a delete completes |
Field events
Per-field, at Events → <Table> → Fields → <field>. Server (PHP): Format, Calculate, Validate, Before Set, After Set. Client (JS): On Change, On Focus, On Blur, On Key Up.
// recompute the line total whenever quantity changes
var qty = +Runner.getControlValue('quantity') || 0;
var price = +Runner.getControlValue('price') || 0;
Runner.setControlValue('line_total', (qty * price).toFixed(2));
Button events
A Custom Button has its own 3-stage flow — Client Before (JS) → Server (PHP) → Client After (JS) — typed right in the button's Properties panel (and mirrored into the Events module). See its guide for the full story.
Global events
App-wide, at Global Events: Authentication (Before/After Login, After Register…), Email (Before/After Send), Application (App Init, Before Display, JS OnLoad, Menu Modify), File, API. Use these for cross-cutting logic that isn't tied to one table.
// stamp the user's last login time
dbExecute('UPDATE users SET last_login = ? WHERE id = ?', [now(), $user['id']]);
Worked examples (with “Where”)
Set a default value on a new record
$data['status'] = 'draft';
$data['created_by'] = \PpPhp\Core\Security::CurrentUsername();
$data['order_date'] = today();
Validate before saving
if (($data['total'] ?? 0) <= 0) {
$errors[] = 'Total must be greater than zero.';
return false; // stops the save and shows the error
}
Email the customer after an order is created
pp_send_email($data['customer_email'], 'Order received', 'Thanks! Your order #' . $id . ' is being prepared.');
Keep an audit trail of edits
dbExecute('INSERT INTO audit_log (table_name, record_id, changed_by, changed_at) VALUES (?,?,?,?)',
['orders', $id, \PpPhp\Core\Security::CurrentUsername(), now()]);
Focus the first field when the Add form opens
if (Runner.getPageMode() === 'add') Runner.getControl(Runner.fields()[0]).focus();
Confirm before the form submits
if (!await pp.dialog.confirm('Submit this order?', 'You can’t edit it afterwards.')) return false;
Runner., pp., db… and pick from the suggestions, each with its own
example. See the PP.js reference and
Database Helpers for the full API.