PPPHP

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

EventWhereUse for
Before Add / Edit LoadTable → Page Events (PHP)Defaults, prefill, hide fields before the form shows.
Before Add / Edit SaveTable → Page Events (PHP)Validate + change data before it's written.
After Add / Edit SaveTable → Page Events (PHP)Email, log, side-effects after it's stored.
On Page InitTable → Client Events (JS)Your “on load” — focus, wire fields, initial UI.
Before Form SubmitTable → Client Events (JS)Last-second client validation; return false to stop.
On Change / On Blur (a field)Table → Fields → <field> → ClientReact when one field changes.
Calculate / Validate (a field)Table → Fields → <field> → ServerCompute 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:

RuleWhere it comes fromExample
Text lengthThe 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 listsA 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 defaultLeave Status on “— Select —” and the record is saved with draft, instead of failing.
RequiredThe field's Required settingChecked 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:

MessageWhat happenedHow 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.
“Is this one already taken?” — answered while they type. The Unique rule does not wait for the Save button. A moment after typing stops, the field asks the server whether that value already exists and answers underneath itself: Checking…, then a green Available, or the red message in your own words. It is the difference between fixing an e-mail address in two seconds and filling in a whole form to be told it was wrong.

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

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.