Skip to main content
Version: 7.0

Trees, sortings and selection in React

A React view that draws the rows of an object group gets in props.data the same state of those rows as the platform's table has, and changes it through props.controller: the hierarchy of an object tree and which of its nodes are open, the sortings, and the selected rows and columns. It also copies and pastes the selected cells as that table does.

Trees​

A group of a tree is projected like any other group: what a container has of it is what its own components put there, and where the TREE's rows are drawn that is list, byKey, keys and the rows themselves. Each of those rows says where it sits in the hierarchy:

{
key, current, objects, ...cells,
parent, // the key of the row it hangs under
hasChildren, // whether it has children, loaded or not
expanded, // whether it is open
loading, // true while its children are being loaded
}

Each field a row of a tree adds is reserved where the tree's rows are drawn, as key is: a property drawn on such a row may not take its name.

parent is the key of the row this one hangs under, null at the top of the tree; it points into whichever group that parent belongs to (a tree's rows are keyed by the whole path down to them, so the keys of its groups do not collide — short of an object of a STRING class whose value contains |). It is written the way a key is, so row.parent === parentRow.key holds rather than merely looking alike. Rows arrive under a loaded parent, so the parent a row names is usually there — until something takes it away: a filter on an upper group drops the parent row while its children stay (the server keeps sending them), and from then on parent can name a row this client does not have. So a view that indexes rows by key must decide what to do with a row whose parent it cannot find, rather than assume the lookup succeeded. A view finds a row's ancestors the same way, following parent through the byKey of the group the parent belongs to, and stopping at a parent it does not have; the depth a row is indented by needs no such walk, as it comes from drawing the tree from its roots down.

hasChildren is what the server says the node has, loaded or not — not a design attribute, but the tree's live state.

expanded says the node is open: its children are loaded — or a view asked to open or close it and the rows of the answer have not arrived yet, and then it says what was asked, as a changed value is shown before the answer and as the platform's own tree turns its expander glyph at the click. A node is closed at once, while its children stay in list until the answer takes them away, so a view that draws a node's children only under an expanded node hides them at once. Only a node with children opens: one whose hasChildren is false stays closed, as it does in the platform's tree. It is live state as well.

If an expand or collapse request fails without updating the rows, expanded keeps the requested state until the server sends rows for the node's group or the immediately following group in the tree in response to that request or a later one.

loading is true while the node's children are being loaded: a view asked to open it, and the rows of the answer have not arrived — as a cell's loading says a change of it waits for its answer. Closing a node loads nothing, and neither does opening one whose hasChildren is false; the field is absent but while it is true.

Rows arrive as the tree is opened — past the roots, a group of a tree returns only the rows under nodes that are currently expanded, which is why, before anything is opened, its lower groups project an empty list.

A row of a group below carries the path above it, so a row made current — through change(row), or by the server — makes the rows on that path current in their groups as well. current follows the path up, as the platform's tree selects one node. The groups below it have no current row — the server clears their current objects when a row above is chosen. Every row in those groups has current set to false until a row is chosen there again.

controller.<g>.expand(row) / .collapse(row) / .toggle(row) open and close one node: a node is a row of a group, so they are the group's. Each takes a row (the row, its objects handle, or its key) and returns the Promise of its request: the row's expanded changes at once, and its children arrive as rows. toggle asks for the opposite of what the row's expanded says now, so two toggles before the answer open the node and close it again. controller.<g>.expandAll() opens every node of the group and of the groups below it: on the tree's top group, the whole tree; on a group below, its nodes under the nodes open above it. controller.<g>.collapseAll() closes the same nodes and every node below them, so a node opened again afterwards shows its children closed. Their rows' expanded changes at once too. A group outside a tree has no such members at all: the five are installed on a group of a tree and nowhere else, and they are reserved on that group's node, as list is.

These verbs are members of the group's node, so a container has them exactly where it has that group's rows: the tree React draws. A tree the platform draws is opened by the platform's own expander, and no React container has node verbs for it; a view that draws its toolbar opens it through the toolbar's two buttons.

FORM catalogue
TREE t c = Category PARENT parent(c), i = Item
PROPERTIES(c) name
PROPERTIES(i) name
FILTERS category(i) == c
;

What is a tree's, one for all its groups, is on a node of the tree's own, data.<tree> and controller.<tree>, where <tree> is the tree's name in the form, the t of TREE t (a tree with no name gets a generated one, so a tree a view draws a part of is named): at the top level, beside its groups' nodes. A container has it wherever it draws a part of the tree: the tree's rows — as a group's node is where its rows are — with its sortings, its user filters, its toolbar and filter controls. It carries no property, so a property of a group of the tree may take any name its parts take there. Where a view draws any part of the tree, the tree's name is taken at the top level there, so it may not be like a group the view carries, a container or a component it projects, a property of the empty group or a member of the controller.

Where a view draws the tree's rows, the tree's node says which of them is current, and has the one verb that needs to know it — no group's rows know it alone:

on the nodememberwhat it is
currentthe key of the tree's current row — the current row of the group whose current object was set last, by the view or by the server, as the platform's tree has its selected row —, null while there is none
expandCurrent()the current node opened, and every node under it

current is written the way key is, so row.key === data.t.current holds, as row.parent === parentRow.key does. It is null while the tree has no current row loaded: before a row is chosen, while the current node's group is on no row, and while its row has not arrived or has gone — never the row above it in its stead. A row is made current through its group's change(row); current only says which, and has no member of its own. controller.<tree>.expandCurrent() reads the current node when it is called, and does nothing while there is none or while it has no children; the nodes it opens are expanded at once, and loading until their rows arrive. Inside a batch it goes with the batch, so the row a change(row) made current earlier in the same batch is the node it opens.

Sortings​

As after a change of the filters, after a change of the sortings the server reads rows around the current row.

A view that draws the rows of a group not in a tree carries orders — the group's sortings, in priority order — beside list and keys: a sorting is the order the rows are drawn in, so it is projected where they are, and a container holding only a panel property of the group has neither. Where it is there it is always there, and empty when the group is sorted by nothing. Each entry is an object:

FieldMeaning
propertyThe sorted property's integration SID — on a tree's node, with its group's name, as below
descWhether it sorts descending

The same shape the ORDER ... FROM operator applies and ORDERS ... TO reads, with one difference: orders names a property the way the rest of the node does — by its integration SID — while those operators name it by its SID on the form (sum(o)).

A sorting names a property of the group, as a condition does, not an entry of the node: the property need not be one this view draws — a panel property of the group drawn in another container, or by the platform, is listed by its name as any other, and the view can name it back. So a name the group draws twice would name no sorting: a form whose rows a React view draws is refused when it is built until such properties have explicit EXTIDs, even when one of the two is drawn by the platform.

controller.<group>.orders.change(...) is a member in the same place, and only there. It changes one sorting, leaving the group's other sortings and their priority alone: a property already sorted keeps its place when its direction changes, and a new one is appended. An order with no desc is not a sorting, so it stops sorting by that property. An array — controller.<group>.orders.change(orders) — states the list as a whole, so what it leaves out stops sorting the group.

A change through the controller is sent at once, as the group's whole list — the same request a click on a standard header sends —, and orders shows it straight away, before the rows sorted by it come back; an answer to a request made before it does not take it back.

A tree's sortings are the tree's, as its user filters are: where a view draws the tree's rows, data.<tree>.orders lists the sortings of all its groups, group by group, top down — each group's in its own priority order, as no group's sortings outrank another's —, each property named by its group's name and its own, c.name; its groups' nodes have no orders. controller.<tree>.orders.change(...) changes them the same way: one order merges into its group's sortings, and an array states the tree's whole list — each group gets the entries on its own properties, and a group none of them names stops being sorted. Each group's list is sent as a group's is.

orders describes the sorting the user can change, whoever stated it. A fixed sorting is not part of it and cannot be: ORDERS ... FIXED, and an ORDERS entry that is an expression rather than a property drawn on the form, are applied on the server and never sent to the client at all. Neither is the implicit ordering by the group's own objects that makes a read stable. So the rows can be ordered by more than orders says, and a view cannot show an indicator for the part it is not told about.

orders is what the form has: its own ORDERS when it opens, then every list the server reports — an ORDER action's too. It is rebuilt only when that list changes: it keeps its identity across renders in which the sortings stay the same — a change to a property value, to the rows or to the current object leaves it as it was — so a view can compare it across renders and memoize on it.

Two more kinds of sorting are not listed, and a console message says so when one appears: a sorting on a property with no integration SID (NOEXTID), which the projection has no name for, and a sorting on a property grouped in columns, as a sorting here names a property, not one of its columns.

Handing data.<group>.orders back through the array form would therefore take those two sortings off — the one on a NOEXTID property and the one on a property grouped in columns — while changing ONE sorting never touches what it does not name.

Each property says whether a view should offer sorting by it: data.<group>.<property>.noSort is true for a property whose design says so:

DESIGN orders {
PROPERTY(number(o)) { noSort = TRUE; }
}

It is stated on the property itself, so a panel property answers it as a column does. A view that draws its own headers reads it to avoid making that header clickable.

noSort refuses a sorting the USER states, not one the form does. What the form states may name such a property — a default ORDERS entry on it, and an ORDER action naming it — the server sorts the rows by it, and orders says so, as the standard grid's header shows it too: what is not offered is only the click that would sort by it.

Asking to sort BY a property declared noSort is refused, and so is a list naming one property twice, a name the group does not carry, and a property grouped in columns. Taking a noSort sorting off is stating an order with no desc, which is allowed: what is refused is sorting by such a property, not stopping.

Selected rows and columns​

A view that draws the rows of a group not in a tree selects rows and columns as the platform's table does. The selected rows are a range the server keeps, in the group's current order (selection), so the range also holds rows the view has not read. A row in the range has selected in list; a change to a row changes the range on the rows of list at once, before the server answers — unless 'extend' runs it on from a current row list does not have, which the answer brings. The columns are the list properties the view draws in its rows, except actions, in the order of properties. The entry of a column — the one its caption is in — has current, whether the column is the current one, and selected, whether the range of selected columns holds it. A cell is selected where its row and its column are.

The members that change the selection are on the group's member where its rows are drawn, and only there:

MemberWhat it does
change(row[, {selection}])Makes the row current and changes the selected rows
change({to: 'home'}[, {selection}]), change({to: 'end'}[, {selection}])Performs the move to the first or last row and changes the selected rows. The form's controller has the two edges of the list as form.HOME and form.END
properties.change(column[, {selection}])Makes the column current, named by its property, and changes the selected columns
selectAll()Selects all the rows the filters leave and all the columns. The current row and the current column stay

Each returns the Promise of its request. What a call does to the selection, selection says:

selectionRowsColumns
'start', or not givenNo row is selected, and a range starts from this rowThis column alone is selected, and a range starts from it
'extend'The rows from the row the range starts from to this one are selectedThe columns from the column the range starts from to this one are selected
'keep'The selected rows stay. While no row is selected, a range starts from this rowThe selected columns stay

The two ranges are independent: a change of the row leaves the selected columns as they are, and a change of the column leaves the selected rows. The platform's table changes both by one move of the cell; a view does it by the two calls, which a batch sends in one request — a click on a cell, for example:

function Cell({ row, name, controller }) {
const select = selection => controller.batch(() => {
controller.i.change(row, { selection });
controller.i.properties.change(name, { selection });
});
return <td onClick={e => select(e.shiftKey ? 'extend' : 'start')}>{row[name].value}</td>;
}

The view takes the keys of the platform's table itself, as it takes the other keys of the table:

function onKeyDown(e, controller) {
const selection = e.shiftKey ? 'extend' : 'start';
if (e.ctrlKey && e.key === 'Home')
controller.i.change(controller.form.HOME, { selection });
else if (e.ctrlKey && e.key === 'End')
controller.i.change(controller.form.END, { selection });
else if (e.ctrlKey && e.key === 'a')
controller.i.selectAll();
}

The server finds the first or last row when it reads the rows of the group, after all the changes of the request are made, as it does for an action's ACTIVATE FIRST / LAST. So a call made after such a move in the same batch still acts on the row that was current before it.

The form sees this selection as it sees the selection in the platform's table: the properties of SELECT, SELECT ACTIVE and SELECT PROPERTY return it, the current column is the active property (ACTIVE PROPERTY), and the form's SELECT and SELECT PROPERTY events occur.

A column the form does not show now — its entry is hidden — cannot be made current, and a name that is not a column is refused. A group of a tree has no selection: its change takes a row only, with no selection but 'keep'. useSeekOnScroll moves the current row with 'keep', as a scroll of the platform's table leaves its selection.

The selection is the view's that draws the rows. Another container changes it through the form's controller — controller.form.changeObject('<group>', row, {selection}), changeColumn('<group>', column, {selection}) and selectAll('<group>') (across containers). Where the platform's table draws the rows, the same calls change the table's own selection: a column is made current where the table shows it now and lets the user move to it, and a property grouped in columns has no column of that name. While the table shows the rows as another view — a pivot, a map, a calendar, a custom view — the calls are refused, as they are for a group of a tree: changeObject takes a row there, with no selection but 'keep'.

Clipboard​

A view that draws the rows of a group not in a tree copies and pastes the selected cells by two more members in the same place:

MemberWhat it does
copy()Returns the Promise of the text of the selected cells
paste(text)Pastes the text into the selected cells and returns the Promise of its request

copy uses the platform table's value formatting: the value's type and the property's format. For a current row copied without a server request, a cell's own format takes precedence when supplied. Selected rows read from the server use the property's format. paste accepts this tab- and line-separated text, including text copied from the platform's table or a spreadsheet.

While no row of list is selected, the row is the current one, and while no column is selected, the column is the current one. copy returns the text of the current row without a request to the server. With no current row in list nothing is pasted, and with no column copy returns an empty text. paste('') does nothing.

copy and paste are calls of their own. A batch does not carry them, and inside one they are refused. paste does not ask, so a view that needs the question asks it itself.

The view takes the browser's copy and paste events itself and gives the text to the clipboard when it has it:

<div tabIndex={0}
onCopy={e => {
e.preventDefault();
controller.i.copy().then(text => navigator.clipboard.writeText(text));
}}
onPaste={e => {
e.preventDefault();
controller.i.paste(e.clipboardData.getData('text/plain'));
}}>
...
</div>

Another container copies and pastes through the form's controller, controller.form.copy('<group>') and paste('<group>', text), which are refused where the selection's calls are. In these calls over the platform's table, a column of an action or of a property grouped in columns is none of the cells, and several values are not pasted while such a column is the current one.