React view controller
The component of a React view works with the form open in the interactive view through its controller, props.controller: it sets current objects and property values, runs actions, and changes sortings, filters and tree nodes.
There is one controller per projection: a React view's props.controller is its own container's, and it names exactly what that container's props.data shows. The object a classic view and a custom cell editor are given as controller.form, an INTERNAL CLIENT action as its argument and a React view as props.controller.form is the FORM's: it projects no data, so it has none of the members below — a member says that data.<group>.<property> is there —, and what it reaches it is given the name of, as a string, which the platform checks when it is called. A view's controller mirrors the shape of props.data: its members are the container's entries, made once, when the form opens, each at the same path as its data — what a view reads as data.o.qty it changes through controller.o.qty, and data.total through controller.total. Each object group a part of which this view draws is a member of the controller under its group SID, each property whose VALUE this view carries is a member of that group under its integration name, and each property of the empty group (the form level) is a member of the controller itself. A form in which one of these names would stand for two properties of one container is refused when it is built. The member is the address — a view's controller has no second, string-addressed set of verbs saying the same thing, and a name typed wrong is a member that does not exist rather than a string the platform has to validate.
A view reads only its own container's parts, and its controller's members change what its props.data carries. What another container draws, or the platform, a view changes through the form's controller, by names (across containers). What containers share is the form itself — its current objects, sortings, filters and session — so a filter or a current object changed in one container shows in another, as it does in the standard client.
Members
Optional arguments are bracketed.
| member | what it does | returns |
|---|---|---|
<group>.change(row[, {selection}]) | set the group's current object — only where the group's rows are drawn. For a group not in a tree, it also takes the first or last row of the whole list, and changes the selected rows | Promise |
<group>.properties.change(column[, {selection}]) | set the current column and change the selected columns — only where the rows of a group not in a tree are drawn | Promise |
<group>.selectAll() | select all the rows and columns — only where the rows of a group not in a tree are drawn | Promise |
<group>.copy() | the text of the selected cells, for the clipboard — only where the rows of a group not in a tree are drawn | Promise |
<group>.paste(text) | paste a text into the selected cells — only where the rows of a group not in a tree are drawn | Promise |
<group>.orders.change(order) | change one of the group's sortings, leaving the rest and their priority — only where the group's rows are drawn. A tree's are <tree>.orders, on the tree's node where its rows are drawn, each property named <group>.<property> | Promise |
<group>.orders.change(orders) | an array states them all, its order being the priority | Promise |
<group>.<property>.change(value[, row]) | set the value — on the current object, or on a given row | Promise |
<group>.<property>.exec([row]) | run the property's change event, or the action — on the current object, or on a given row | Promise |
<group>.<property>.getValues(value[, {row, mode, count}]) | a capped server suggestion list | Promise |
<property>.change(value) / .exec() / .getValues(...) | the same, for a property of the empty group — with no row | Promise |
<group>.expand(row) / .collapse(row) / .toggle(row) | open or close one node of a tree — a node is a row of a group; only where the tree's rows are drawn | Promise |
<group>.expandAll() / .collapseAll() | open every node of the group and of the groups below it — the whole tree on its top group — or close them; where the tree's rows are drawn | Promise |
<group>.filters.change(condition) | change one of the group's user filter conditions, leaving the rest: the first on its property, what it does not state kept, as a property's filter does — where FILTERS(<group>) is. A tree's are <tree>.filters, where FILTERS(TREE <tree>) is, each property named <group>.<property> (Filters) | Promise |
<group>.filters.change(conditions) | an array states all the conditions it can name: replace the condition list — one on a property it names none by keeps its place —, a condition with no value comparing with NULL | Promise |
<group>.addFilter() / .applyFilters() / .resetFilters() | the filter controls' add, apply and reset, as the platform's buttons — where FILTERCONTROLS(<group>) is. A tree's are <tree>.addFilter() and so on, where FILTERCONTROLS(TREE <tree>) is | Promise |
<group>.<filterGroup>.change(index) | select one of a filter group's filters by its index, null for none — where FILTERGROUP(<filterGroup>) is | Promise |
<group>.filter.<property>.change(value[, {compare, negation, or}]) | state the value of a property's filter — in its condition, the first on the property, or, with none, in the filter's own place, with the comparison, the negation and the junction the options state; null takes that one off — where FILTER(<property>) is drawn | Promise |
<group>.viewFilters.change(conditions) | state the group's view filters, the view's own conditions the server filters its rows by beside the user filters: an array states them all, an empty one none — only where the rows of a group not in a tree are drawn | Promise |
<group>.getCount() / .getSum(property) | the number of the group's rows and the sum of a column of them, of the marked rows only where the user has marked any — where TOOLBARSYSTEM(<group>) is, whatever the design's show… flags say — its buttons | Promise |
<group>.export() / .update() / .manual.change(on) / .filterControlsVisible.change(shown) / .listView.change(name) | export the rows, bring the changes the server holds back, turn the manual update on or off, show or hide the platform's filter controls, show the rows in another view type — where TOOLBARSYSTEM(<group>) is, whatever the design's show… flags say | Promise |
<tree>.expandCurrent() | open the tree's current node and every node under it — the tree's own, on the tree's node where its rows are drawn; over the platform's tree, its toolbar's, where TOOLBARSYSTEM(TREE <tree>) is | Promise |
<tree>.export() / .filterControlsVisible.change(shown) / .expandTree() | export the tree, show or hide the platform's filter controls of the tree — on the tree's node, where TOOLBARSYSTEM(TREE <tree>) is (its toolbar); over the platform's tree also open it from the selected node's group down | Promise |
batch(fn) | run fn, the member changes it makes shown at once and sent together in one request when it returns, in the order made — the form's batch, also form.batch(fn) | Promise |
controller.o.note.change('checked'); // the current row of group `o`
controller.o.sum.change(100, row); // ... a given row
controller.o.edit.exec(row); // an action: run it on that row
controller.o.change(row); // the group's current object
controller.o.orders.change([]); // its sortings: an array states them all — here, none
controller.o.filters.change({property: 'name', value: 'an'}); // one condition — data.o.filters is where it lands
controller.o.customer.getValues(text, {mode: 'objects'}); // the Promise of its suggestions
controller.total.change(500); // a property of the empty group
Beside its members and batch, the controller carries form, the form's controller.
A member's change and exec do not ask the confirmation a property's design asks for (CONFIRM on an action, askConfirm in the design): the platform's own editor and button ask it, a view's call goes straight to the server. The property's entry says whether to ask, and what — askConfirm and askConfirmMessage (display options) —, so a view that wants the question asks it before it calls.
The members are what this view can change - the entries it carries, minus what the PLATFORM draws: a property declared NOCUSTOM - or given a CUSTOM render function in the FORM - has an entry (an ordinary column entry, so the view can draw the column header) and no member, because its value is drawn and edited by its own renderer, which this view places with <Platform name row/>, and any other child the platform draws has only the entry that labels it - an action the platform draws, panel or drawn per row, only its entry, with no caption and no image - they are its button's face; the platform's button runs it. So a group is a member of the controller of every container that has data.<group> - an empty one where the container only places what the platform draws of the group -, and a property is a member there when THAT container carries its value: a grid property where the rows are drawn, a panel property where the property itself stands. A member is there as long as its entry is — from the start, hidden or not: a SHOWIF that hides the property leaves the member in place, and a call through it is refused while the entry is hidden, with an error saying the property is not shown by the form now. A property's change event is the one a user fires by editing the cell, so a property the form is not showing has nobody to fire it for. <group>.change(row) is there only where the group's rows are drawn — the current object is chosen among them — and so is orders.change(...) — the group's, or a tree's on the tree's node —, since a sorting is the order those rows are drawn in; and a row is taken only there: by <group>.change itself, and by the member of a list property, which lives where the rows are. The member of a panel property and a member of the empty group take no row: they act on the current objects. What a view cannot see it has no member for either: the rest of the form is reached through the form's controller, form — its methods across containers, and change / exec / eval / evalAction, which take lsf names and code rather than projection names. Where the state a view keeps names a property — a sorting, a user filter's condition — it names it by its integration name, not by a member: a state is data, written in the shape props.data publishes it, and it may name a property no member stands for, such as a column the platform draws. A sorting is {property: 'sum', desc: true} and a condition {property: 'sum', compare: '>', value: 100}, and either name is looked up among the group's properties, wherever they are drawn: a group's state is the group's, not one view's — FILTERS(<group>) need not be anywhere near a column, and the rows need not be drawn beside a property they are sorted by (Sortings, Filters). A call, by contrast, names what it changes by its member. A property grouped in columns is a member nowhere, for the same reason it is not projected: its values are addressed by a row-and-column key. (The classic changeProperty — a CUSTOM object group's, and the form's controller's, form.changeProperty — is another surface, older than this one, and goes on naming the whole form.) The mutating members — a property's change and exec, and those that change a group's current object, selection, sortings, user filters, view filters or filter group, or a tree's nodes, the filter controls' too — return the Promise of their request: the new state arrives with the next form update. A toolbar's export(), update(), manual.change() and listView.change() also return the Promise of their request. The form's server calls (form.exec / form.eval / form.evalAction / form.change) return a Promise, and so do a property's getValues(), which asks the server for suggestions, and a toolbar's getCount() and getSum() — and the form's controller's getCount, getSum and getValues —, which ask it for a number.
The Promise of a mutating member's call is resolved once its request is over — the server has run it to its end, any dialog it opened answered, and the form has taken in its answer — and rejected with an Error with the reason the request failed, which the platform shows the user, as it shows a failed edit, so a call whose Promise the view does not wait for reports nothing more. After the form has been closed, it is rejected with Form is closed; a call made while the close is still being processed is sent — see Server calls. A property's change or exec the platform makes no request for — a delete with no row to delete, a closing of the form the user does not confirm — resolves its Promise at once outside a batch; when the server fails to give a new object its id, the Promise is rejected with the reason, as a failed request's is. Calls on the user filters — including a change the manual apply mode holds back and an applyFilters with nothing waiting — wait for the table's latest filter request in flight. A tree's expandCurrent and expandTree likewise wait for its latest expansion request in flight. With none in flight they resolve at once, as do other calls that make no request outside a batch.
Member names
A name that is not a JavaScript identifier is addressed with brackets: a property with EXTID 'unit price' is controller.o['unit price'].change(v). A group SID is always an identifier — a group of several objects, whose SID would be their names joined with dots, is refused when the form is built until it is named (OBJECTS pair = (d = X, t = Y)).
A name that would shadow a member of the surface itself is refused when the form is built, the same way the projection's own reserved names are: a group SID, a tree's name where a view draws its rows or another part of the tree, or a property of the empty group coinciding with what the controller carries beside its members (form, batch), or with each other — a controller is one namespace for its own projection, so a group and a property of the empty group the same container projects cannot both be total, while two different containers may — and a group property named like one of the group's own members in the same container. The fix is to rename it, or give it an EXTID. A tree's sortings, its current row and its own expandCurrent, where its rows are drawn, and its user filters, toolbar and filter controls are on the tree's node, which carries no property.
Form edits and server calls
Running an action through its member — controller.o.edit.exec(row), outside a batch — is the same request as clicking it on the form: synchronous, blocking input until it completes and showing the busy indicator after its delay, unless the action is drawn with NOWAIT (the syncType property option). The form's exec, eval, evalAction and change go as asynchronous requests. So a refresh on a timer is not made through the controller — see Live data.
Editing the form and calling the server also differ along two more axes — whether they are gated, and how an object is addressed in them:
| group | methods | gate | how an object is passed |
|---|---|---|---|
| editing the form | <group>.change / <property>.change / <property>.exec; on the form's controller, changeObject / changeOrders / … (across containers) | none | the target row — a data row (row), a raw handle (row.objects), or its key (a member's only); an object as a value (FK) — its id |
| calling the server | exec / eval / evalAction / change on the form's controller, form | @@api / admin rights / the form's CUSTOMS | an object — its id |
A custom view normally reads state from props.data and changes it through the form-edit members — including running an action drawn on the form with controller.<action>.exec(). Its members change what the view draws — rows, their current row and the selected ones, sortings, filters, tree nodes and the toolbar. There is no member for a tab or container the platform draws: place a form action with ACTIVATE TAB, COLLAPSE CONTAINER or EXPAND CONTAINER in the view's container and run it through its member. The form's server calls (exec / eval / evalAction / change) are an escape hatch, used only for what the form does not express — ad-hoc server computation, a global write, or creating an object.
Editing the form goes through the ordinary edit channel and is not gated. The server calls are (see Server calls). The edited row is addressed by a handle, while any other object — an FK value or an action parameter — is passed as its numeric id (an lsFusion object cannot be passed from JS).
Changes to the current object and property values
controller.<group>.change(row) sets the current object of that group. It is there only in the container that draws the group's rows — another container sets it through the form's controller, controller.form.changeObject('<group>', row) (across containers) —, and the row is a data row of the group, a raw objects handle, or the key the projection gave it (see the identity rules). Where the view draws the rows of a group not in a tree, change also takes the first or last row of the whole list in place of a row and says what happens to the selected rows, and properties.change and selectAll change the current column and the selection (selected rows and columns).
For the move to the first or last row, pass the group's change an edge of the list instead of a row — {to: 'home'} or {to: 'end'}, which the form's controller also has as form.HOME and form.END:
<>
<button onClick={() => controller.o.change(controller.form.HOME)}>First</button>
<button onClick={() => controller.o.change(controller.form.END)}>Last</button>
</>
The rows read by the move replace list. The same call can change the selected rows. An action with ACTIVATE FIRST / LAST placed in the view's container and run through its member performs the same move.
A group of an object tree takes no edge, and its list contains all rows under open nodes without paging (object search in a tree). To move to the first or last node, call controller.<group>.change(row) through the member of that node's group, passing the row of the first or last node the view draws in its own order — parent then children — rather than the first or last element of one group's list.
controller.<group>.<property>.change(value) changes the property for the group's current object, and .change(value, row) for the given row. The arguments come in this order, and nothing is guessed from them: the value first — it is required, and null clears it — then the row, which is optional. .exec() runs the property's change event, the one a user fires by editing the cell, on the current object — for an action, it runs the action — and .exec(row) does it on the given row. An action has no value to set, so .change on one is refused: call exec. A row is taken only by the member of a list property, which lives where the group's rows are drawn. The member of a panel property and a member of the empty group take none, and act on the current objects. A selection is changed by what is picked — the forms are given there.
A member takes a row only where the group's rows are drawn — <group>.change(row), and the member of a list property, which lives there — and there it takes the row object, its objects handle, or the key string the projection gave it, looked up in this view's byKey. A panel property's member and a member of the empty group take no row: they act on the current objects. Row identity says what each of the three means.
For controller.<g>.<p>.exec(row), .change(value, row) or .getValues(query, {row}), the property or action must be in GRID view, in a group in GRID view. Add a row action as PROPERTIES(i) addToCart GRID: actions default to PANEL. PANEL, TOOLBAR and POPUP properties refer to the current object, have no cells in list / byKey, and refuse member calls naming a row at runtime with '<p>' is a panel property. Per-row editors placed with <Platform name row/> or usePlatform(name, {row}) also require a GRID property.
A value passed to change reaches a property's change handler only when it requests a value from the user — the default handler, or a handler with a value request: the passed value is taken instead of the user's input. null is a value like any other. An action has no value to set: its member's change is refused, and it is run with exec, which passes none — controller.o.edit.exec(row) — so an action that asks the user for a value cannot be given one through its member.
A member's call has no cell for the user to enter a value in, so it asks the user for none. Where the platform asks the user for the value before it runs the change handler — the asynchronous input of the default handler, for one — the member's exec is refused: the view gives a property's value itself, with change(value), and no member can give an action one. A value the handler requests only as it runs — an input in one branch of it, say — is cancelled, as the user cancels an input, and the handler goes on as it then does; the browser console says why.
A built-in primitive-class object group — a DATE navigator, for instance — is moved to a value by writing the object's value (controller.<g>.VALUE.change(d)), by controller.<g>.change(row) with a row from props.data.<g>.list (which carries the objects handle), or, when the group is filtered by a data property, by changing that filter property. A date is given as a JS Date (new Date(year, month - 1, day)) or as the string a date input of the class has for its value ('2026-11-18' for a DATE), as for any date property (see value formats); any other value — a timestamp, the string Date.toISOString() gives, a day its month does not have — is refused: change throws <value> is not a date: ….
Like a user edit in the standard table, the change is made in the form's change session: the view sees the new value in props.data at once, while it reaches the database when the session is applied — with the Save button or an action with the APPLY operator. If the edited property is marked with the APPLY option on the form, its standard change handler applies the change at once (by default, by committing the whole form session), so .change needs no separate save. The details are described with the option. For a simple edit from a view — a move, a resize, an in-place value edit — this is preferable to a separate server action. The server action (controller.form.exec) stays for what a property change cannot express: creating an object (NEW), multi-step logic, opening a form.
When a view sets a property's value with its member's change several times without waiting for the server's answers, props.data shows the last value set while the answers to the earlier changes arrive: the server's answer replaces it only when the server stored something else or refused the change.