Add & Edit pages
The data-entry forms. Set defaults, validate, calculate fields, and make fields react to each other — each recipe below says exactly where the code goes.
Events these pages fire
| Event | Where | Use for |
|---|---|---|
| Before Add / Edit Load | Table → Page Events (PHP) | Defaults, prefill, hide fields before the form shows. |
| Before Add / Edit Save | Table → Page Events (PHP) | Validate + change data before it's written. |
| After Add / Edit Save | Table → Page Events (PHP) | Email, log, side-effects after it's stored. |
| On Page Init | Table → Client Events (JS) | Your “on load” — focus, wire fields, initial UI. |
| Before Form Submit | Table → Client Events (JS) | Last-second client validation; return false to stop. |
| On Change / On Blur (a field) | Table → Fields → <field> → Client | React when one field changes. |
| Calculate / Validate (a field) | Table → Fields → <field> → Server | Compute or check one field on the server. |
What every form checks for you
Before you write a single rule, the generated Add and Edit forms already protect your data — on every database engine, in the browser and on the server:
| Rule | Where it comes from | Example |
|---|---|---|
| Text length | The column's size (e.g. VARCHAR(80)) | The box stops at 80 characters; a longer value pasted or sent by code is refused with “Label: the value is too long.” |
| Choice lists | A column with a fixed list of values (ENUM) | The dropdown offers exactly those values (draft / published / archived) even when you never configured a control for it. |
| Blank means “use the default” | A required column that has a default | Leave Status on “— Select —” and the record is saved with draft, instead of failing. |
| Required | The field's Required setting | Checked even when the field is missing from the submitted form. |
What the messages mean
If the database itself refuses a save, the form explains it in plain words and names the field — it never shows SQL:
| Message | What happened | How to fix |
|---|---|---|
| “Customer: the selected value does not match an existing record.” | A linked field points at a record that does not exist (or was deleted). | Pick a value from the list; if you type ids by hand, use a Lookup control instead. |
| “Email: that value is already used by another record.” | The column must be unique. | Use a different value, or edit the existing record. |
| “Title is required.” | The column cannot be empty and has no default. | Fill it in — or give the column a default in Tables. |
| “Status: that value is not allowed.” | The value is outside the column's allowed list. | Choose one of the offered values. |
| “Badge: the value is too long.” | The value exceeds the column size. | Shorten it, or make the column longer in Tables. |
The same messages appear in the visitor's language (they are part of the Label Editor catalogue). Deleting a record that other records still point to shows “…other records still point to this one.” — remove or re-link those first.
Recipes
1 · Default values for a new record
WhereEvents → orders → Page Events → Before Add LoadPHP
$data['status'] = 'draft';
$data['order_date'] = today();
$data['created_by'] = \PpPhp\Core\Security::CurrentUsername();
Most rules need no code. In the Designer, double-click a field and open Validation:
Required, Text length, Date / range / age (not in the past, not in the future, minimum age),
e-mail, phone, number ranges, Unique and more. Each rule runs live in the browser and again on the server, and
its message names the limit you set — “Due Date can’t be in the past.”, “Title must be at least 3 characters.” —
unless you type your own. A Required rule marks the field with *. Today-relative date checks judge a date someone
enters or changes, never one already stored, so an overdue task can still be edited. Use the event below only for rules
that compare several fields or look things up.
2 · Server-side validation
WhereEvents → orders → Page Events → Before Edit SavePHP
if (($data['discount'] ?? 0) > ($data['total'] ?? 0)) {
$errors[] = 'Discount cannot exceed the total.';
return false; // block the save; the message shows on the form
}
// you can also change the data before it's written:
$data['updated_at'] = now();
3 · Calculate a field live as the user types
WhereEvents → orders → Fields → quantity → On Change (Client)JS
function recalc() {
var qty = +Runner.getControlValue('quantity') || 0;
var price = +Runner.getControlValue('price') || 0;
Runner.setControlValue('line_total', (qty * price).toFixed(2));
}
recalc();
Runner.getControl('quantity').onChange(recalc);
Runner.getControl('price').onChange(recalc);
4 · Show a field only when another has a certain value
WhereEvents → customers → Fields → type → On Change (Client)JS
function sync() { Runner.getControl('vat_number').visible(Runner.getControlValue('type') === 'company'); }
sync();
Runner.getControl('type').onChange(sync);
5 · Autofill from the server when an email is entered
WhereEvents → orders → Fields → email → On Blur (Client)JS
var contact = await pp.run('findContact', { email: Runner.getControlValue('email') });
if (contact) Runner.setData({ customer_name: contact.name, phone: contact.phone });
// server side: Custom Functions → PHP → function action_findContact($params) { … return $row; }
6 · 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;
7 · Require at least one detail line (Master/Detail)
WhereEvents → orders → Client Events → Before Form SubmitJS
if (Runner.detail('order_items').count() === 0) {
pp.dialog.toast('warning', 'Add at least one line item first.');
return false;
}
8 · Total the child lines onto the master before saving
WhereEvents → orders → Client Events → Before Form SubmitJS
var items = Runner.detail('order_items').getAllRecords();
Runner.setControlValue('total', items.reduce(function (s, it) { return s + (+it.qty) * (+it.price); }, 0));
9 · Email a receipt after saving
WhereEvents → orders → Page Events → After Add SavePHP
pp_send_email($data['customer_email'], 'Order received', 'Your order #' . $id . ' is confirmed.');
10 · Lock the form to read-only for some users
WhereEvents → orders → Client Events → On Page InitJS
Runner.fields().forEach(function (f) { Runner.getControl(f).readonly(true); });
Runner.button('save').hide();
Client helpers (
Runner.getControl, setData, detail, dialogs) →
PP.js reference. Server helpers (dbExecute,
pp_send_email) → DB &
Helpers.