PPPHP

Master / Detail

A master record (an order) with a grid of detail children (its line items). This guide shows how to read and write the children from the master's page — two-way — and the small touches like locking the child Add button. Each recipe says exactly where the code goes.

Set it up in the Designer. Drop a Detail Grid component on the master's Edit/View page and pick the child table + its foreign-key column. Then script it with Runner.detail('<child_table>') — its whole API is in the PP.js reference.
Filter the child rows. A relation (Tables → Relation) has an optional Filter (WHERE) that scopes which children show under a master — on top of the foreign-key link. It supports SQL variables, e.g. status = 'active', created >= :daysago.30, or assigned_to = :userid.

The API in one line

var items = Runner.detail('order_items');   // a grid object scoped to that child grid

Or reach them all as a map keyed by child table (PHPRunner-style) — every value is a full grid object:

var details = Runner.getDetailsPages();
details['order_items'].hideItem('add');       // hide that child grid's Add button
details['order_items'].getAllRecords();       // …read its rows
Runner.details().length;                       // how many detail grids on the page

hideItem / showItem / disableItem / enableItem are shortcuts for .button(name).hide() etc. — names are add, delete, edit…

CallDoes
items.getAllRecords() / getSelectedRecords()All / ticked child rows.
items.getCellValue(id, field) / getRow(id)One child cell / row.
items.setCellValue(id, field, value)Write + persist one child cell.
items.getRow(id).setValues({…})Write several child cells, one save.
items.editCell(id, field)Open a child cell's inline editor for the user.
items.button('add').hide()Reach the child grid's own buttons.
items.count() / Runner.details()Row count / every detail grid on the page.

Recipes

1 · Total the child lines onto the master

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));

2 · Require at least one child before saving

WhereEvents → orders → Client Events → Before Form SubmitJS
if (Runner.detail('order_items').count() === 0) {
    pp.dialog.toast('warning', 'Add at least one line item.');
    return false;
}

3 · Write a computed value into every child row (two-way)

WhereDesigner → Custom Button (on the master) → Client BeforeJS
var d = Runner.detail('order_items');
for (var it of d.getAllRecords()) {
    await d.setCellValue(it.id, 'line_total', (+it.qty) * (+it.price));   // saves each child row
}
d.reload();
return false;

4 · Copy a master field into all children, then save

WhereDesigner → Custom Button (on the master) → Client BeforeJS
var currency = Runner.getControlValue('currency');
var d = Runner.detail('order_items');
for (var it of d.getAllRecords()) { await d.setCellValue(it.id, 'currency', currency); }
d.reload();
return false;

5 · Add a child, then jump the cursor into its first cell

WhereDesigner → Custom Button (on the master) → Client AfterJS
// after your Server stage inserts a child and returns $result['id']:
Runner.detail('order_items').editCell(result.id, 'sku');

6 · Lock the child Add button when the order is closed

WhereEvents → orders → Client Events → On Page InitJS
if (Runner.getControlValue('status') === 'closed') {
    Runner.detail('order_items').button('add').hide();
    Runner.hideButton('deleteSelected');
}

7 · Keep the master total correct on the server too

Client totals are convenient, but recompute authoritatively on save so it's always right:

WhereEvents → orders → Page Events → After Edit SavePHP
$total = dbValue('SELECT COALESCE(SUM(qty*price),0) FROM order_items WHERE order_id = ?', [$id]);
dbExecute('UPDATE orders SET total = ? WHERE id = ?', [$total, $id]);

8 · Walk every detail grid on the page

WhereEvents → orders → Client Events → On Page InitJS
Runner.details().forEach(function (d) { console.log(d.table + ': ' + d.grid.count() + ' rows'); });
Child writes go through the same permission-gated save endpoint as everything else — the user needs edit rights on the child table. Read the children anywhere; write where the grid is editable.