Skip to main content
Version: 7.0

Brief: custom views

Choosing a custom view​

A custom view hands drawing to the application's client code when the standard table, pivot table (PIVOT), calendar (CALENDAR) or map (MAP) does not fit: a kanban board, a card feed, a timetable, or a different layout or interaction. React views suit new views, while classic render functions remain available for existing JavaScript views.

PlaceWhat the client code drawsWhen to use it
A DESIGN container's customThe container's whole subtreeA region of a form with its own layout and interaction
A component's own customA tree's table, a toolbar, filter controls, a filter group or a property's filter, in that component's placeReplace just that part of the form
A property's CUSTOMOne value of one object, in a table cell or on a panelA widget for one field
An object group's CUSTOMThe rows of one group, where its table standsAnother view of one list, with the platform's toolbar and filters around it
A WINDOW's CUSTOM or NAVIGATOR CUSTOMA window's content or the arrangement of the windowsA menu, a forms window, a message panel or the application's window layout

These are web-client views. On forms the desktop client keeps the standard views and the container's regular subtree. A container's custom can also be an HTML template: it places platform-drawn children by name and receives no data. A React component is used when the drawing needs to read data or provide interaction of its own.

Form projection​

A React component receives props.data, the form projection: the properties, object-group parts and design entries that its view draws or places. Each React container has a projection of its own. Ordinary DESIGN containers can lay out several such regions on one form.

Data reaches a custom view through object groups, with server-side paging and filters: the group's rows in props.data.<g>.list for a React container, props.data.list for a React component in CUSTOM registered as reactView, and the update list for a classic CUSTOM object-group view. A JSON property carries one object's value, not a pageable object group.

A projected property carries its value and display attributes. The projection also carries the current object and, where the view draws them, sortings, filters, selection and toolbar state. What remains drawn by the platform is placed by the component rather than redrawn from property values.

View and form controllers​

A custom view receives data and a local controller for what it shows. A React component receives that controller as props.controller: its members mirror the projection and change property values, run form actions, select current objects, and change sortings, filters and tree nodes. The form remains responsible for selecting and ordering the rows and for calculations over them. Changes go into the form's change session, as edits in the standard table do.

The form controller is reached as controller.form, in both React and classic views and in editors. It changes what another container or the platform draws by name, groups edits in a batch, and provides server calls (exec, change, eval, evalAction). A form's CUSTOMS lists actions and properties callable from this form without exposing them through the external HTTP API. Server calls specify the authorization and parameter formats.

Outside a form the navigator controller activates navigator elements and provides server calls. A call there has a session of its own, rather than the session of an open form.

Rendering and form behavior​

The platform supplies components and hooks for a React view, so client code can draw its own interface while using the form's data and behavior:

ArticleCapabilities to reach for
Rendering in ReactList for rows, Buckets for placing rows into visual cells, useSeekOnScroll for paging with the scroll, Image and Caption for the platform's images and captions
Components the platform draws<Platform> places a child or a row's property that keeps its own view and editor, useShown reports which regions are shown
Form behavior in ReactFocus and form loading, keyboard and mouse bindings, live data through the form's SCHEDULE, and hidden views
Trees, sortings and selection in ReactTree nodes, server-side sortings, selected rows and columns, copying and pasting
Filters and toolbar in ReactUser filters, property filters (FILTER), view filters, filter controls, FILTERGROUP and toolbar operations

Windows and window layout​

Windows in React use props.data for the window's content and props.controller for its operations. CUSTOM on the WINDOW statement selects the window's renderer, and EXTEND WINDOW ... CUSTOM changes the renderer of an already declared window.

ViewWhat it receives and draws
Navigator windowIts navigator elements and the navigator controller, whose activate selects a folder or runs an element. A React component draws from the data, or an HTML template places the platform's buttons
FORMS window — System.forms or one declared by the applicationIts open forms and operations for selecting and closing them. A React component places the forms with <Platform> and draws the controls around them
System.logIts logged messages and the pin operation. A React component places the platform's message markup with <Platform>
NAVIGATOR CUSTOMThe windows and the navigator controller. A React component sizes and places the windows with <Platform>, replacing their standard arrangement by POSITION

The forms and log windows accept only a React component: they receive what the window holds instead of navigator elements. Other NATIVE windows contain no navigator elements and accept neither a component nor a template. Custom windows and the window layout are drawn only by the desktop web client. The mobile web client and the desktop client keep their standard interface.

Classic render and edit functions​

CUSTOM can hand drawing to a classic JavaScript render function or to a React component explicitly registered as reactView. An object group uses CUSTOM renderFunction [OPTIONS optionsExpr] in object blocks, a property uses CUSTOM renderFunction [CHANGE [editFunction]] in the properties and actions block.

A classic render function returns render, update and optional clear: the platform gives them an element, a local controller and, on update, the group's rows or the property's one value. The group's controller reads property values and provides row and property changes, incremental updates through diff and server-side view filters. A property's controller changes its value and looks up suggestions. Both reach server calls through controller.form.

An edit function replaces the editing of one value, independently of its display: it can extend the standard text input, draw an editor in the cell, or open a window editor. It is named after CHANGE in a property's CUSTOM, or in the CUSTOM block of INPUT. Its editor controller commits or cancels the edit. Committed values go through the property's ordinary change channel. Use it when the field needs an editor of its own while the rest of the view stays standard.

Client JavaScript modules​

Client JavaScript modules hold React components, classic render and edit functions, and functions called by INTERNAL CLIENT actions.

ProjectWhere the code lives and how it is reached
With the build.js, .jsx, .ts and .tsx under src/main/web; each file outside lib becomes an auto-loaded bundle, shared helpers in lib are imported. Named exports are auto-registered under the names the lsFusion code uses
Without the build.js or .jsx under src/main/resources/web; web/init auto-loads files independent of load order, other files are listed in onWebClientInit[STRING]. JSX is transformed when served. Scripts share globals rather than import local modules

The platform supplies React and ReactDOM. A React component for a container, a window or NAVIGATOR CUSTOM is selected by an identifier starting with an uppercase letter. A component used in a property's or object group's CUSTOM needs explicit registration as reactView even when it is a named export. Classic functions use the same window.lsfusion.custom registry, with names on window as a fallback for existing scripts. CSS modules provide component-local styles, and a bundle's CSS is loaded with it.