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…
| Call | Does |
|---|---|
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.