Skip to content
npm

Data sources ​

A data source is a named connection to data, usually an API endpoint. You define sources once per view in the Data sources tab below the canvas, then bind elements to them. Sources are referenced everywhere by name.

The source editor ​

Click New data source in the Data sources tab below the canvas. Every source has:

FieldWhat it does
NameThe technical name used everywhere else (loadClients, saveOrder). Renaming it updates everything bound to the old name: tables and selects loading from it, actions running it, data source variables, and runDataSource("…") in expressions.
TitleA friendly display title for the list.
TypeREST, Route data, Local JSON, and WebSocket or Event stream when your developer has enabled them.

REST ​

FieldWhat it does
UrlThe endpoint, with optional {placeholders}: https://api.example.com/clients/{clientId}. Required: actions using a URL-less REST source warn in the editor.
MethodGET, POST, PUT, PATCH or DELETE, picked in the request bar next to the URL. When a Table loads from a POST source, a switch Send the table's paging, sorting and filters appears: turned on, the request still goes out as a POST, with the current page, sort and search state added to the body. Ask your developer to read Table: server-side paging & filtering for the exact shape.
Request body (optional)JSON template with {…} placeholders. Example: {"rows":"{__table.el1.selectedRows}"}. Use {id} style tokens for the URL and {__table.el1.selectedRows} style paths in the body.
Data pathWhere the useful data lives in the response (e.g. data.items).

With the OpenAPI plugin, an API row above the request lets you pick the endpoint from your application's API instead of typing it, and fills in the URL, method and body for you. See API.

{placeholders} are filled from the request params you map on the element or action. Where the placeholder sits decides what an empty value does:

  • In the path, /api/cities/{countryId}, the value is required. Until a country is picked the request is skipped and the city list stays empty.
  • In the query string, /api/customers?q={search}&status={status}, the placeholder is an optional filter. An empty value leaves that name=value pair out, so with nothing picked the request is /api/customers and the table shows everything. Fill in a status and the request becomes /api/customers?status=active.

Route data ​

FieldWhat it does
Route data keyKey in the Angular route's resolver/data object.
Data path (optional)Path inside that object.

Local JSON ​

FieldWhat it does
Local modeJSON (inline data) or Another question value (points at existing form data).
JSON dataThe inline JSON when mode is JSON.
Local functionOptionally call a JS function for the data. Example: window.myFunction or this.myFunction.

WebSocket Experimental ​

Experimental

Live sources are new. They work, but details may change in a coming release. Your developer decides whether they are turned on.

A REST source answers once, when something asks it. A WebSocket source stays connected and keeps handing you whatever the server sends, so the view moves on its own: a dashboard counter, a queue, an order that someone else just changed.

The connection opens the first time something on the page uses the source, and closes when the last thing using it goes away. Every message after that lands in the bound elements without anyone pressing anything.

FieldWhat it does
UrlThe endpoint: wss://..., or a path on the same site such as /api/ws/orders, which becomes wss:// automatically on a secure page.
Protocols (optional)Comma separated subprotocol names, if your server asks for them.
Message (optional)Sent once, right after the connection opens. This is where a subscribe or handshake payload goes. It is not sent again later.
Message path (optional)Where the useful part of each message lives, for example rows. Leave it empty to take the whole message.
Message modeReplace current keeps only the latest message, which is what a live value or a refreshing table wants. Push values in array collects messages into a growing list, for a feed or a log. The list keeps the most recent 500 entries.

Binding works exactly like any other source. Point a table at it with Use as: Value, or feed a variable from it and read the variable in expressions.

Two sources, one connection

Several sources pointing at the same url share a single connection, so a page with a table on rows and a counter on the whole payload still opens one socket. Give each source its own Message path rather than duplicating the endpoint.

Showing whether the data is live ​

Stale numbers that look live are worse than an honest gap, so the runtime publishes the state of every socket under __socket.<source name>:

PathWhat it holds
{__socket.liveFeed.connected}true while the connection is up, false while it is not.
{__socket.liveFeed.lastMessageAt}Timestamp of the last message received.
{__socket.liveFeed.reconnects}How many times the connection came back by itself.
{__socket.liveFeed.url}The endpoint actually connected to.

A read-only text element with visibleIf: {__socket.liveFeed.connected} == false and a label like "Connection lost, values are from a moment ago" is usually all a form needs.

Reconnecting is automatic. A dropped connection is retried with a growing delay, and once the server is back the view carries on without a page refresh.

Sending something back ​

The Message field only fires at connection time. To push something later, put a Send socket message action on a button: pick the WebSocket source and write the payload. See Actions.

Event stream Experimental ​

Experimental

Live sources are new. They work, but details may change in a coming release. Your developer decides whether they are turned on.

An event stream is the listening-only cousin of a WebSocket: the server keeps an ordinary web request open and writes an event whenever something happens. It is the simpler choice when the form only needs to watch, such as an order moving from Confirmed to Shipped, an import at 40%, or a log of changes.

FieldWhat it does
UrlThe address that sends the events, for example /api/orders/{orderId}/events. {placeholders} work as in REST.
Event types (optional)Comma separated, for example order.updated. Leave it empty to take every event.
Message path (optional)Where the useful part of each event lives. Empty takes the whole event.
Update modeReplace current value keeps the latest event: a status, a progress figure. Push values in array adds each event to a list, which a table shows as a live log (the latest 500 stay).

Binding, sharing one connection and the __socket.<source name> status work exactly as for a WebSocket, described above. When the connection drops, the runtime reconnects on its own and the server can carry on from the last event.

There is nothing to send back on an event stream. To change something on the server, use a REST source from a button as usual.

Building JSON without typing it ​

Local JSON data, a REST request body and a WebSocket message all have a Build visually link above their editor. It opens a builder that writes the JSON for you, with the result shown on the right as you go.

The first choice is the shape: A list of items ([ ], for options, rows, records) or One record ({ }, named fields such as a request body). An empty builder also offers four starting points: Dropdown options (a value and a label per choice), Table of records, Simple list and One record. You can rename and add fields afterwards.

A list of flat records opens as a table, which is the quickest way to type demo data or dropdown options:

In the tableWhat it does
Column headerClick the name to rename it; the type underneath is Text, Number or Yes / No.
Column / Add rowAdd a column to every row, or a new row with the same columns.
Paste from ExcelCopy cells from Excel or Google Sheets, header row included, and paste them. The first row becomes the field names; columns that hold only numbers become numbers, only true/false become yes/no. You can replace the current items or add below them.

Anything else (one record, nested groups, lists inside records) is edited in the Fields view, one line per field: its name, its type and its value.

TypeValue
Text, Number, Yes / No, Empty (null)A fixed value.
Form field valuePick a field or variable; it is saved as {path} and filled in when the request runs.
Group of fields { }A nested object; Add field to … adds inside it.
List [ ]A nested array. A new item copies the fields of the item above it, so a list of records only needs its fields defined once.

Problems are shown next to the field that causes them (a missing or repeated name, a number that is not a number), and Apply stays blocked until they are fixed. Ctrl + Enter applies.

Binding a source to an element ​

Choice elements, tables, list grids, and charts have a Data source binding in the Primary source section of the properties sidebar:

FieldWhat it does
Data sourceWhich source feeds this element. Dependent fields are supported via the param map and refresh paths.
Use asOption loads selectable options (select, radio, checkbox); Value loads the field's own value.
Option value key / Option label keyWhich response fields become the stored value and the visible label. A path into the item works too: info.label, names[0].
Items pathWhere the array lives in the response (e.g. data.items).
Filter options byLegacy conditional filter, leave empty if unused. Prefer the Filter if equal / not equal option properties.
Param mappingOne row per {placeholder}: Param (the placeholder name) → Value / {path} (a form path, variable, or plain value). Auto from params pre-fills rows from the URL/body placeholders. Only used for REST URL/body placeholders.
Reload source when mapped question value changes (React to change)Auto-reload when a mapped param's value changes.
Listen fieldsComma-separated extra paths to watch (e.g. el1 or panel.userId). If empty, the system auto-detects from URL placeholders and the param mapping.
Lazy loadFetch on demand: tables load per page/sort. Autocomplete has its own Search datasource for this, see Autocomplete.

Example: country → city dropdowns ​

  1. Define sources: loadCountries (GET /api/countries) and loadCities (GET /api/cities?country={countryId}).
  2. Element country (Select): data source loadCountries, use as Option, value key code, label key name.
  3. Element city (Select): data source loadCities, param countryId = {country}, React to change on.

Picking a country now reloads the city list automatically; before any pick, the city list stays empty because {countryId} is missing.

Filling values (not options) ​

With Use as: Value, the response is written into the element. A whole panel of read-only fields can be populated by one GET /api/clients/{id} source whose params come from {__variables.route.id}.

Saving data ​

Saving goes through actions: a button's dataSource action calls a POST/PUT source, passing fields via Placeholder mapping or the whole form as the body template. Combine with Validate whole form before action, Elements to reload, and Show toast after successful action.

Reloading from expressions ​

runDataSource("loadUsers") inside any expression re-runs a source, which is occasionally useful in advanced logic. Prefer element bindings with React to change for normal flows.