Data sources & variables

Method	Returns	In short
reloadDataSource(element, source?, context?)	Promise<unknown | null>	Reload one element's source
reloadElementDataSource(element, context?)	Promise<unknown | null>	Same, the element's own source
reloadElementsByDataSource(source, context?)	Promise<unknown[]>	Every element using a source
setDefaultDataSources(sources, overwrite?)	void	Add host sources to every view
setDataSourceTypeSettings / getDataSourceTypeSettings	void / settings	Switch optional source types on
setWebsocketAuthorizer(fn)	void	Put credentials on websocket connections
setRuntimeVariableContext(values, merge?)	void	The {__external.*} context
getRuntimeVariableContext / clearRuntimeVariableContext	object / void	Read or clear it
setRuntimeVariableDefinitions(defs, replace?)	void	Define {__variables.*}
getRuntimeVariableDefinitions()	IRuntimeVariableDefinition[]	Read them
configureRuntimeVariables(config)	void	Both in one call

Data sources

Requests go through your Angular HttpClient, so interceptors apply. Every load fires onDataSourceLoading, onDataSourceLoaded or onDataSourceLoadFailed.

reloadDataSource()

reloadDataSource(elementNameOrPath: string, dataSourceName?: string, runtimeContext?: Record<string, unknown>): Promise<unknown | null>

Loads the source bound to an element again (or another source, for that element) and returns the result. runtimeContext fills placeholders the element's own parameters do not.

await api.reloadDataSource('country');
// [{ code: 'LT', name: 'Lithuania' }, { code: 'LV', name: 'Latvia' }, { code: 'EE', name: 'Estonia' }]

await api.reloadDataSource('clientCard', 'loadClient', { id: 42 });
// { id: 42, name: 'Harbor Foods', ... }  with url /api/clients/{id}

Resolves to null when the element or source does not exist. A failed request fires onDataSourceLoadFailed with the error, so one global handler can report it.

reloadElementDataSource()

reloadElementDataSource(elementNameOrPath: string, runtimeContext?: Record<string, unknown>): Promise<unknown | null>

The element's own source, no name needed.

reloadElementsByDataSource()

reloadElementsByDataSource(dataSourceName: string, runtimeContext?: Record<string, unknown>): Promise<unknown[]>

Reloads every element bound to the source, one result per element. Handy after a save: everything that shows clients refreshes.

await http.post('/api/clients', client);
await api.reloadElementsByDataSource('loadClients');

setDefaultDataSources()

setDefaultDataSources(dataSources: IDataSource[], overwriteExisting = false): void

Adds sources your application owns to the view, so creators can bind elements to them without defining them. They are remembered: a view loaded or a runtime created later gets them too. A view's own source of the same name wins unless you pass overwriteExisting.

api.setDefaultDataSources([
  { name: 'countries', title: 'Countries', type: 'rest', params: { url: '/api/countries', method: 'GET' } },
  { name: 'currentUser', type: 'rest', params: { url: '/api/me', method: 'GET' } },
]);

api.getStructure()?.dataSources?.map((s) => s.name);
// ['loadClients', 'countries', 'currentUser']

runtimeSettings.defaultDataSources on the components does the same declaratively.

setDataSourceTypeSettings() / getDataSourceTypeSettings()

setDataSourceTypeSettings(settings: { enableWebsocket?: boolean }): void
getDataSourceTypeSettings(): { enableWebsocket?: boolean }

Optional source types creators may pick in the builder. Fires onDataSourceTypeSettingsChanged.

api.setDataSourceTypeSettings({ enableWebsocket: true });
api.getDataSourceTypeSettings(); // { enableWebsocket: true }

setWebsocketAuthorizer()

setWebsocketAuthorizer(authorizer: (context: { sourceName: string; url: string; protocols: string[] }) =>
  { url?: string; protocols?: string[] } | null | Promise<{ url?: string; protocols?: string[] } | null>): void

Runs before every websocket connection and reconnection; return a changed url or subprotocol list to carry credentials, or null to leave it.

api.setWebsocketAuthorizer(async ({ url }) => {
  const token = await auth.getToken();
  return { url: `${url}?token=${encodeURIComponent(token)}` };
});

See WebSocket security.

Runtime variables

Expressions read host context as {__external.name} and variables as {__variables.name}. The Runtime variables page explains the variable types.

setRuntimeVariableContext()

setRuntimeVariableContext(values: Record<string, unknown>, merge = true): void

The external context. Set it once at startup and every view sees it; change it later and expressions that read it recalculate.

api.setRuntimeVariableContext({ userId: 'u-42', userRole: 'admin', tenant: 'acme' });
// in the view:  disableIf: {__external.userRole} != "admin"

getRuntimeVariableContext() / clearRuntimeVariableContext()

getRuntimeVariableContext(): Record<string, unknown>
clearRuntimeVariableContext(): void

api.getRuntimeVariableContext(); // { userId: 'u-42', userRole: 'admin', tenant: 'acme' }

setRuntimeVariableDefinitions()

setRuntimeVariableDefinitions(definitions: IRuntimeVariableDefinition[], replace = true): void

Writes the view's variable definitions (the Variables tab) and resolves them. With replace = false they are added to the view's own, a definition with the same name replacing the old one.

api.setRuntimeVariableDefinitions([
  { name: 'clientId', sourceType: 'route', source: 'id', fallbackValue: '' },
  { name: 'isEdit', sourceType: 'expression', expression: 'notEmpty({__variables.clientId})' },
  { name: 'apiBase', sourceType: 'constant', constantValue: '/api/v2' },
], false);

api.getData().__variables; // { route: {...}, clientId: '42', isEdit: true, apiBase: '/api/v2', ... }

getRuntimeVariableDefinitions()

getRuntimeVariableDefinitions(): IRuntimeVariableDefinition[]

api.getRuntimeVariableDefinitions().map((d) => d.name); // ['clientId', 'isEdit', 'apiBase']

configureRuntimeVariables()

configureRuntimeVariables(config: { mappings?: IRuntimeVariableDefinition[]; external?: Record<string, unknown>; mergeExternal?: boolean }): void

Definitions and context in one call.

api.configureRuntimeVariables({
  mappings: [{ name: 'clientId', sourceType: 'route', source: 'id' }],
  external: { userName: auth.userName },
});

Values an action or setValue() writes into __variables stay through navigation, including a change of the query string; they belong to the session until the view is closed.