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
$data['status'] = 'draft';
$data['order_date'] = today();
$data['created_by'] = \PpPhp\Core\Security::CurrentUsername();
Three choices sit with the rule, in the Designer, when you double-click the field and open Validation → Unique:
- Check while they type — on by default. Switch it off and the check waits until they leave the field.
- Say when it is free — the green line. Without it, silence has to mean “probably fine”.
- Start checking after — how many characters to wait for before the first question (three by default), so nobody is told “available” after one letter. An e-mail field also waits for something shaped like an address.
The server re-checks on save regardless, so a value that was free a second ago and is taken now is still refused — the live check is courtesy, never the guard.
2 · Server-side validation
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
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
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
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
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)
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
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
pp_send_email($data['customer_email'], 'Order received', 'Your order #' . $id . ' is confirmed.');
10 · Lock the form to read-only for some users
Runner.fields().forEach(function (f) { Runner.getControl(f).readonly(true); });
Runner.button('save').hide();
Runner.getControl, setData, detail, dialogs) →
PP.js reference. Server helpers (dbExecute,
pp_send_email) → DB &
Helpers.