PPPHP

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.

Two places to write events. Most live in the Events module (open your project → Events). A few client-side ones can also be typed right on the component — e.g. a Custom Button's three code boxes. Wherever you write it, the app records it as one event.

Contents

The page lifecycle

When a visitor opens a page, events fire in order. A record being saved on the Add page, for example, runs:

onPageInit (JS)→ Before Add Load (PHP)→ Before Form Submit (JS)→ Before Add Save (PHP)→ DB insert→ After Add Save (PHP)

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/ImportTable → 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 fieldTable → Fields → pick the field → Client (On Change…) or Server (Calculate…)
Login, register, email, app start-upGlobal Events → Authentication / Email / Application…
A named routine you call from JSCustom 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.

EventPageFiresKey variables
After List LoadListafter the rows are read$rows
Before Add LoadAddbefore the empty form shows$data (defaults)
Before Add SaveAddbefore insert — validate/alter$data (by ref), $errors
After Add SaveAddafter insert — email/log$data, $id
Before Edit LoadEditbefore the form is filled$data, $id
Before Edit SaveEditbefore update$data (by ref), $old, $id, $errors
After Edit SaveEditafter update$data, $old, $id
Before / After DeleteList/Viewaround a delete$id
Before View LoadViewbefore the record shows$data, $id
Before SearchListbefore a search runs$searchFor
Before / After Export · ImportExport/Importaround data transfer$data / rows
On PrintPrint/PDFwhen a printable page renders$data
Process Record ValuesList/Viewto reshape a value for display$data

Client events — browser (JS)

Reached at Events → <Table> → Client Events. Here the Runner / pp.js API shines.

EventPageFires
On Page Initanyas soon as the page is ready — your “on load” hook
After List RenderListafter the grid is drawn (colour rows, add handlers)
On Row Click · On Row SelectListwhen a row is clicked / ticked
Before Form SubmitAdd/Editbefore the form posts — return false to stop it
After Delete SuccessList/Viewafter 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.

WhereEvents → orders → Fields → quantity → On Change (Client)JS
// 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.

WhereGlobal Events → Authentication → After LoginPHP
// 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

WhereEvents → orders → Page Events → Before Add LoadPHP
$data['status']     = 'draft';
$data['created_by'] = \PpPhp\Core\Security::CurrentUsername();
$data['order_date'] = today();

Validate before saving

WhereEvents → orders → Page Events → Before Add SavePHP
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

WhereEvents → orders → Page Events → After Add SavePHP
pp_send_email($data['customer_email'], 'Order received', 'Thanks! Your order #' . $id . ' is being prepared.');

Keep an audit trail of edits

WhereEvents → orders → Page Events → After Edit SavePHP
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

WhereEvents → orders → Client Events → On Page InitJS
if (Runner.getPageMode() === 'add') Runner.getControl(Runner.fields()[0]).focus();

Confirm before the form submits

WhereEvents → orders → Client Events → Before Form SubmitJS
if (!await pp.dialog.confirm('Submit this order?', 'You can’t edit it afterwards.')) return false;
Every example here also autocompletes in the Events editor — start typing 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.