Widget Reference
The following sections describe the platform widgets and which configuration options are available for them. You can create custom widgets and use them just like platform widgets. Please refer to the section Developing a Custom Widget. Note that all widgets have the title option:
- title: when the widget is a direct child of the page container, the widget is placed in a card with this title
Apart from title, all widgets support the following options:
- roles: show container only if user is in one of these roles
- if: show the widget if the expression is true
- style: CSS widget styles (e.g. width and height of the widget)
These can be edited using Dashjoin Studio. Some widgets, like the container, expose them via the layout editor as well.
Widgets can be grouped into the following three categories. See appendix widgets for examples.
Container Widgets
Container widgets can contain other widgets. All container widgets have features that control under which conditions content is shown or hidden. Please note that these features are enforced on the client and thus can be manipulated by malicious users. Specifically, do not rely on these features to implement security and data privacy. You can safely restrict access on the server side by applying access control to functions, databases, tables, and queries.
card
Layout card with a title and nested widgets:
- text: card title
- roles: show container only if user is in one of these roles
container
Container with a plain layout
- roles: show container only if user is in one of these roles
- if: show the widget if the expression is true
- redrawInterval: redraw interval (seconds). Periodically refreshes the container and all contained content.
- foreach: expression that evaluates to an array of objects. The first child of the container is rendered for each object, with the "value" context set to the respective array item (Dashjoin Studio only)
- layout: if foreach is used, use "horizontal" or "vertical" layout (Dashjoin Studio only)
expansion
Collapsible container with nested widgets
- text: card title
- roles: show container only if user is in one of these roles
- expression: optional expression to compute whether the widget's initial expansion state
page
The page widget is implicitly present at the root on any platform page. It cannot be edited via the layout editor, but changes can be made in Dashjoin Studio.
- onRender: expression that is evaluated when the page renders in the browser. This is useful if you need to initialize variables that are used in expressions of other widgets. Note that variables are stored per browser tab whereas the login session applies to the entire browser. Therefore, variables should be set using onRender instead of on-login.
stepper
The stepper widget allows stepping through its children. It displays the step number and title along with the child at the current step position. Note that the widget does not display back and next buttons. The stepper child widgets are responsible for advancing the current page via the JSONata functions stepBack, stepForward, and setActiveStep.
tabs
The tabs widget displays its children in a container which allows selecting the current tab on top. The child titles are used as a label. Only the active tab is shown.
- foreach: expression that evaluates to an array of objects. The first child of the container is rendered for each object, with the "value" context set to the respective array item (Dashjoin Studio only)
Form Widgets
Like containers, form widgets allow adding input elements. Every input widget must use a unique name which is in turn used as the key in the resulting JSON structure. See appendix inputs for examples. Inputs can be of the following type:
- boolean: displays an on/off toggle and returns a boolean value
- string; a regular text box that returns a string
- number: a number input returning a number
- auto complete: an input field with auto-complete options (which are generated by a JSONata expression)
- select: like auto complete, but uses a select widget instead of a text field
- multi select: like select but allows multiple selections, returns an array
- key value: allows entering any key value pairs, returns an object
- password: like string but hides the input
- textarea: like string but uses a multi-line input
- date: like string but uses a date picker
- time: like string but uses a time picker
- datetime: like string but uses a datetime picker
- file: like string but uses the content of an uploaded file are the value
- binary file: like file, but uses base64 encoding
- file with metadata: like file but includes file metadata
- binary file with metadata: like binary file but includes file metadata
- voice: like string, but offers a speech to text input option (language option is available via Dashjoin Studio)
- qrcode: like string, but offers a QR Code scanner
Further options include:
- an optional title for the input element
- a description which shows up as a tooltip
- an optional expression to compute select options (must return an array of strings or an array of objects containing name and value)
- CSS options (e.g. width: 500px)
- Read only flag (input is inactive)
- Required flag
- An optional format validation
- An expression to determine whether to show the input
Not all form options can be edited in the form edit dialog. If you would like to create a form for nested objects and arrays, you can add the JSON schema to the form in Dashjoin Studio. This example displays a form to enter an object with a field emails which is an array of strings (setting reorder: true, also displays controls to change the order of the array elements):
{
"print": "form",
"widget": "button",
"schema": {
"type": "object",
"properties": {
"emails": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
If you choose one of the file upload widgets, you can add the attribute multiple: true via Dashjoin Studio. This allows you to upload multiple files at once. Note that the return value changes from a single value to an array if you do so.
In addition to the attribute multiple, you can specify capture: user or capture: environment. This setting allows taking and uploading a photo using the inward or outward camera. Setting accept: video/* takes a video instead of a photo. The field accept can also be set to a comma-separated list of file allowed extensions. Finally, the field limit can be used to restrict the maximum file size in MB.
There may be cases, where parts of a form should be shown or hidden depending on other inputs. This can be achieved via the "if" expression. Consider the following example:
{
"print": "form",
"widget": "button",
"schema": {
"type": "object",
"properties": {
"has_foreign_income": {
"widget": "boolean",
"title": "Did you have foreign income?"
},
"foreign_income": {
"if": "form.has_foreign_income",
"widget": "textarea",
"title": "Please describe your foreign income"
}
}
}
}
The notes input is only shown once the "has_foreign_income" switch is set to "true". Note that you can only use simple expressions to lookup values, similar to the template variables in the HTML and markdown widgets. The expression evaluates to true if the result is true, a non empty string, or a number other than 0.
button
Runs / evaluates an expression when clicked.
- text: text shown for the run button (default is "Run")
- print: evaluates this expression when clicked
- expression: optional expression - the form fields are initialized with the result of this expression
- schemaExpression: optional JSONata expression that computes a JSON Schema driving the input form (this option is only available in Dashjoin Studio). Note that forms drawn using schemaExpression do not use the layout editor. You can arrange input elements using the "order" field explained in this example.
- deleteConfirmation: optional confirmation message before performing the action (this option is only available in Dashjoin Studio - you can prompt the user via JSONata as follows):
- icon: icon to show left of the text (this option is only available in Dashjoin Studio)
- onScan: allows filling out the form using a QR code - onScan contains an expression that is called when the data is scanned. The expression can compute a value similar to the "expression" above. The QR code is passed in the context field "scanned" (this option is only available in Dashjoin Studio)
The form content (if a form is present), is added to the context using the key "form". This widget is a container. Any form elements are defined by adding an "Input" widget for each form field.
create
Creates new database records:
- text: text shown for the create button (default is "Create")
- database: optional database to create the record in (defaults to the database of the table you are currently displaying)
- table: optional table to create the record in (defaults to the table you are currently displaying)
edit
allows editing a database record. Note that the form layout can be customized in the layout editor. Please also refer to the FAQ for information on how to further customize the input form.
- text: text shown for the save button (default is "Save")
- deleteConfirmation: optional confirmation message before deleting the record (this option is only available in Dashjoin Studio - edits on database tables can be undone within five seconds)
- editRedirect: redirect after save (Dashjoin Studio only) - table: back to table view (default), record: stay on record page, page/Dashboard, db/table, db/table/id: navigate to fixed page
- deleteRedirect: redirect after delete (Dashjoin Studio only) - table: back to table view (default), record: stay on record page, page/Dashboard, db/table, db/table/id: navigate to fixed page
- mutationMode: determines how the edit is processed (Dashjoin Studio only) - undoable (default): edit is applied after some seconds in which the user can undo the change, pessimistic: wait until the edit is written
variable
Displays a form that allows setting session variables. If a variable "x" is defined and set, it can be referenced in other widgets using "variable.x". A variable can be set via a URL query parameter. Appending ?a=1&b=test to the URL will set variable.a to "1" and variable.b to "test". Note that only string variables can be set this way, so you might have to use $number(variable.a) when using the variable.
- text: text shown for the apply button (default is "Apply")
This widget is a container. Any form elements are defined by adding an "Input" widget for each form field.
Regular Widgets
actionTable
The Action table widget works like the table widget. In addition, it allows selecting several rows in the table. If rows are selected, action buttons become visible. The actions are configured via a set of key value pairs. The key specifies the action button's label, the value contains the expression that is run if the button is pressed.
- expression: allows configuring the widget data via JSONata which must evaluate to an array of objects. Note that the table is able to display links, images, and lists thereof. Please refer to the display widget for information on how the JSON data must be structured. If omitted, the widget uses $query(database, query, arguments)
- properties: a set of key value pairs. For every key, an action button with the key used as its label is displayed. When the button is pressed, the JSONata expression specified in the value is run
- perPage: default number of rows to display
- columns: columns to display. Use this option if you need certain fields to be included in the selection value but don't want those values to be included in the table. Note that this option is only available in Dashjoin Studio
- hideColumns: columns to hide on the display. Use this option if you need certain fields to be included in the selection value but don't want those values to be included in the table. Note that this option is only available in Dashjoin Studio
- hideTablePagination: if true, hide table pagination (Dashjoin Studio only)
- hideTableActions: if true, hide export and filter buttons on the table (Dashjoin Studio only)
aichat
Chat widget for interacting with large language models.
- expression: an expression to compute the initial state of the widget. This is an object with the following fields:
{
"messages": [{role, content}], // the chat messages
"uploadEnabled": boolean // like the widget setting, allows the setting to be dynamic
"placeholder": string // shows an input placeholder for the initial user input (e.g. like How may I help?)
}
The content is usually a string, but may also contain images and documents (see the OpenAI documentation). Messages can also contain hints to the tools and sources that were used to compute the answer.
-
onChat: an expression that is called when the user sends a request. The expression is called with the context: messages and newMessage. Messages represent the current conversation state of the widget. NewMessage is the message sent by the user. The expression returns the AI's answer. Usually you can use "$call('aia', $append(messages, newMessage))" and "$sse('aia', $append(messages, newMessage))", where "aia" is the name of the AIApp function to call. The function sse will stream the answer, call works synchronously.
-
voice: true if voice input and output is activated
- language: language to use for voice (defaults to i18n setting)
- uploadEnabled: allow user to upload files
- extensions: supported upload file extensions
- limit: maximum file size (MB)
- placeholder: shows an input placeholder for the initial user input (e.g. like How may I help?)
The following example shows a minimal configuration with the parrot AI showing an initial message.
{
"onChat": "newMessage.content",
"expression": "{'messages': [{'role': 'assistant', 'content': 'I am a parrot'}]}",
"widget": "aichat"
}
This is a normal configuration using an AIApp:
{
"onChat": "$sse('aia', $append(messages, newMessage))",
"uploadEnabled": true,
"widget": "aichat",
"voice": true
}
analytics
Like chart and table, but allows exposing query filters to the user. The query can be based on a table or a base query. The widget configuration allows defining projection, aggregation, and filters in the widget configuration (i.e. without having to rely on the query catalog).
- database: database to run the query on
- table: the table to query and filter
- chart: chart type or table
- style: see chart widget
- columns: a list of columns to project / aggregate from the table or query
- filter: a list of filters to expose to the user
- hideTablePagination: if true, hide table pagination (Dashjoin Studio only)
- hideTableActions: if true, hide export and filter buttons on the table (Dashjoin Studio only)
The following settings are available in Dashjoin Studio only:
- query: optionally base the widget on this query instead of a single table
- arguments: optional expression resulting in query arguments
chart
Chart for visualizing query results.
- database: database to run the query on
- query: query to run; the query is expected to project the following column structure:
- label followed by a value column: in this case, a chart with a single series is shown. The first column is used as the series axis label and the second column is used as the value range
- two label columns followed by a value column: in this case, a chart with a multiple series is shown. The first column identifies which series the row belongs to. From there, the process described above is repeated
- arguments: optional expression resulting in query arguments
- chart: chart type
- style: key value pairs that construct chart option object - for instance, scales.y.min = 0 makes sure the y-axis starts at 0. By default, the chart limits the number of data points to 1000. This can be overridden by setting "limit" to the desired value
- graph: specifies whether the query is a graph query
- expression: allows configuring the widget via JSONata. If omitted, the widget uses $query(database, query, arguments)
Examples: * chart-stacked-bar * chart-timeline
datagrid
Allows editing records from a grid.
- expression: Expression that returns a table (list of objects) that populates the grid
- onchange: Expression to run when a value is changed. The expression gets passed "id", which is the primary key of the row and "updatedRow" which is the new row value object.
- ondelete: Expression to run when a row is deleted. The expression gets passed "id", which is the primary key of the row
- oncreate: Expression to run when a row is created.
- columns: Optional array of column description objects. The object can use the fields described here. Defaults to an editable column with the name and type found in the data.
- idColumn: Optional name of the column that serves as the primary key. Note that the primary key column is removed from the display and cannot be edited. Any column name containing the substring "id" is used as the default.
Consider this example to edit the northwind employee table. Note that the oncreate expression must create a unique primary key (select max + 1) and also provide default values for the values required by the database constraints:
{
"widget": "datagrid",
"expression": "$all('northwind', 'EMPLOYEES')",
"onchange": "$update('northwind', 'EMPLOYEES', id, updatedRow)",
"ondelete": "$delete('northwind', 'EMPLOYEES', id)",
"oncreate": "$create('northwind', 'EMPLOYEES', {'EMPLOYEE_ID': $adHocQuery('northwind', 'select max(EMPLOYEE_ID)+1 as X from EMPLOYEES').X, 'LAST_NAME': ' ', 'FIRST_NAME': ' '})",
"idColumn": "EMPLOYEE_ID",
}
diagram
Allows displaying and editing data as a graph of nodes and edges.
Nodes are represented by the following JSON structure:
{
id: node id
database: database name
table: table name
position?: {
x: coordinate
y: coordinate
},
data?: {
label: display label
}
}
Edges are represented by the following JSON structure:
- nodes: JSONata that generates a list of nodes
- edges: JSONata that generates a list of edges
- moveNode: optional JSONata to persist new coordinates (e.g. $update("northwind", "EMPLOYEES", node.id, {"Y": node.position.y}))
- addNode: optional JSONata to persist new node that was added via SHIFT click (e.g. ($x := {"id": node.name, "x": node.position.x, "y": node.position.y}; $create("db", "table", $x); $x) )
- removeNode: optional JSONata to remove node in the DB (passed via node.id)
- addEdge: optional JSONata to create a relationship (passed via edge.source, edge.target)
- removeEdge: optional JSONata to remove a relationship (passed via edge.source, edge.target)
display
Displays the result of an expression:
- display: expression to display
- icons: if display evaluates to an object, icons maps the object keys to material icons
- hideTablePagination: if true, hide table pagination (Dashjoin Studio only)
- hideTableActions: if true, hide export and filter buttons on the table (Dashjoin Studio only)
Depending on the result of the evaluation, one of the following cases applies:
- a single result value is displayed as is
- an object is displayed as a key-value list
- if the object has exactly the keys "database", "table", and "pk1", the result is displayed as a link to the record identified by these values
- if the object has exactly the keys "database", "table", "pk1", and "page", the result is displayed as a link to the record identified by these values and uses the specified page to visualize the record
- an array of objects is displayed as a table
- if the object has exactly the key "img" (with optional width and height), the result is displayed as an HTML image with the value of the img field being used as the image src attribute
- if the object has exactly the key "href" or the keys "href" and "label", the object is displayed as a hyperlink (note that absolute or relative links to another page in the app are specified without the "slash hash" part of the URL - for instance, the href "Info" or "/page/Info" links to the Info page)
- if the object has exactly the key "qrcode", the string is displayed as a QR code
Example:
"display": {
"item one": "this item's value",
"item two": "another value",
"item three": "last value",
},
"icons": {
"item one": "traffic",
"item two": "turn_left"
}

Item one will be displayed with the "traffic" icon, item two with the "turn_left" icon. When no item is specified for a key, the default item is used. In the above example, "item three" will display the default icon.
When icons is "*": "icon", all icons will be mapped to that same specified icon.
editRelated
Allows editing related records of a database record:
- prop: foreign key column on the related table
- columns: columns to display in the editRelated table display
graph
Displays data as a directed graph
- nodes: expression to generate nodes, this can either be the result of an OpenCypher query or a list of nodes
- _3d: if true, displays the graph in 3D, 2D otherwise
To add a single starting node, you can simply use the following expression for "nodes":
To add all employees, you can select all employee IDs and convert them into resource objects as shown above:
$all("northwind", "EMPLOYEES").EMPLOYEE_ID.{
"database": "northwind",
"table": "EMPLOYEES",
"pk": [$]
}
Alternatively, you can use an OpenCypher query:
The previous examples only added nodes to the canvas. You can use OpenCypher to pre-select a path:
html
Displays custom HTML
- html: HTML to display
- context: an expression that allows setting additional context variables that can be referenced via
${context.VARIABLE} - script: JavaScript function definitions that can be called from HTML onClick or other event handlers
As in the Markdown widget, hyperlinks to other pages in the app have to include the "slash hash" part of the URL.
Please note that if you are displaying multiple HTML widgets on a page, these widgets share (and subsequently overwrite) the contents of context. If you only display the context in the widget, this is no problem. If you use context from an event handler (e.g. onClick), you have to use the following workaround that uses a session variable. This allows you to choose different variables for each widget:
{
"html": "<button onClick='go()'>",
"script": "function go(){ console.log(JSON.parse(sessionStorage.variable).x) }",
"context": "$setVariable('x', 'my value')",
"widget": "html"
}
icon
Displays a hyperlink icon with tooltip
- href: optional link target
- icon: icon to display (see https://material.io/resources/icons/?style=baseline)
- tooltip: icon tooltip
- roles: show container only if user is in one of these roles
links
Displays links to related records
map
Displays a map for a given location.
- display: expression that results in a location - this value is resolved using the q query parameter of the Open Streetmap API service. The expected result structure is explained below
- css: CSS code to apply to the map
- card: determines if the map is shown on a card (paper background)
The map can be fed with the following data:
{
center: {lat, lon} // map center
zoom: number // zoom level where globe=1 and street=15
points: [ // array of marker points
{
address: string // address where marker is placed or marker coordinates
location: {lat, lon}
color: string // marker color
radius: number // marker radius
tooltip: any // additional info to be displayed in tooltip or popup
popup: any // any JSON is displayed like in the display widget
}
]
}
Note that most information is optional. The platform chooses good defaults. For instance, you can display a single address with a link to a record page as follows:
{
"points": [
{
"address": "London",
"popup": {
"database": "northwind",
"table": "CUSTOMERS",
"pk": [ "AROUT" ]
}
}
]
}
If you would just like to show a marker at London, you can simply pass the string:
markdown
Displays markdown
- markdown: markdown to display
- context: an expression that allows setting additional context variables that can be referenced via
${context.VARIABLE} - card: determines if the markdown is shown on a card (paper background)
Note that the HTML generated by the markdown engine is sanitized in order to avoid XSS vulnerabilities. Specifically, if you are using HTML tags, style attributes are filtered. A common task is to add margins to images. You can achieve this by adding a class attribute to the element and setting the value to a predefined material class like mat-elevation-z8. Alternatively, the markdown widget defines the styles margin1 to margin5 which set the element margin to 1em to 5em.
As in the HTML widget, hyperlinks to other pages in the app have to include the "slash hash" part of the URL.
mdxeditor
This component offers a full fledged WYSIWYG markdown editor that can be extended with custom menus to call any JSONata or JavaScript expressions.
- markdown: markdown to display
- context: an expression that allows setting additional context variables that can be referenced via
${context.VARIABLE} - card: determines if the editor is shown on a card (paper background)
- expression: an optional expression to compute the structure of additional menus that call expressions defined using "properties". Please see the example below.
- properties: a set of key value pairs composing the widget's expression library. The keys are the expression names, the values are the actual expression to be called
Consider the following example. The markdown and context work just like the markdown widget above. This widget allows the user to edit the text and call expressions via the custom menu.
{
"widget": "mdxeditor",
"markdown": "# Hello ${user} ${context}",
"context": "'my context expression'",
"properties": {
"alert": "$alert('selection: ' & selection & '. markdown: ' & markdown)",
"replace": "selection ? {'selection': 'replace'} : {'markdown': 'replace'}",
"sleep": "($progress({'message': 'working'});$sleep(1000))"
},
"expression": "{... see below}"
}
The widget defines three expressions:
- alert: shows that we can use the context fields markdown and selection to access the entire document (with the user's changes) or the text selected in the editor
- replace: if a text is selected, replaces the text with "replace", otherwise, replaces the entire text with "replace"
- sleep: an example for how to provide feedback for operations with a longer runtime
The menu structure is defined by an expression the yields the following JSON:
{
"menu": [
{
"type": "select",
"title": "tooltip",
"label": "longer operation",
"value": "sleep",
"items": [{}]
},
{
"type": "select",
"title": "tooltip",
"label": "Label",
"items": [
{
"label": "alert popup",
"value": "alert"
},
{
"label": "replace",
"value": "replace"
}
]
}
]
}
The first menu items displays clickable button in the menu bar that runs expression "sleep". The second item displays the menu "Label" that has two submenus, calling "alert" and "replace" respectively.
notebook
This widget is the JSONata equivalent of a Jupyter notebook. It allows composing and running several expressions. The result of every expression is stored in the browser session. You can also assign variables and use them in other expressions.
The widget offers a save function at the bottom. This saves the entire page and the expressions contained within. Please note that the notebook widget should only be used as the sole widget on the page, since saving the notebook will delete other widgets you might place on the page.
table
Displays query results as a table
- database: database to run the query on
- query: query to run
- arguments: optional expression resulting in query arguments
- graph: specifies whether the query is a graph query
- expression: allows configuring the widget data via JSONata which must evaluate to an array of objects. Note that the table is able to display links, images, and lists thereof. Please refer to the display widget for information on how the JSON data must be structured. If omitted, the widget uses $query(database, query, arguments)
- columns: if no query or expression is specified, this array allows specifying the columns to be projected. Note that this option is only available in Dashjoin Studio
- hideColumns: if no query or expression is specified, this array allows specifying the columns to be hidden. Note that this option is only available in Dashjoin Studio
- perPage: default number of rows to display
- deleteConfirmation: optional confirmation message before bulk deleting records (this option is only available in Dashjoin Studio - edits on database tables can be undone within five seconds)
- mode: defines how the table is displayed. 'desktop' shows the normal wide table with all columns (this is the default). 'mobile' shows a narrow list view with up to three column values and an icon. 'auto' uses the other two modes depending on the user's device
- hideTablePagination: if true, hide table pagination (Dashjoin Studio only)
- hideTableActions: if true, hide export and filter buttons on the table (Dashjoin Studio only)
The following options are only available in Dashjoin Studio. The define how the narrow table version is populated. The text properties are optional. If omitted, the platform chooses a table column to display in the respective slot. To choose a specific column, specify the column name. To make sure the slot stays empty, please choose a non-existing name.
- primaryText: Text to be displayed on the upper left of the list
- secondaryText: Text to be displayed on the lower left of the list
- tertiaryText: Text to be displayed on the right of the list
- leftIcon: Optional name of the column that contains the icon name
Database and table can be omitted on table pages. In this case, the widget displays the equivalent of a select all from the respective table.
Tables allow the user to add filters to specific columns. If a filter value is provided, the table will only show rows where the respective cell is equal to the filter value. If the cell contains an array, the row is shown if the array contains the filter value. If the table displays the result of a query or an expression, the filters are only applied on the results (i.e. they are not pushed down to the database). In turn, you can prefix the filter with one of these operators:
- < less than
- > greater than
- <= less than or equal
- >= greater than or equal
- <> not equal
- != not equal
- ~ contains substring
text
Displays a simple text
- href: optional link target
- text: text to display
- icon: optional icon to display in front of the text
tree
Displays a tree based on a recursive query
- database: database to run the query on
- query: query that projects a single column with the keys of the current node's children. The primary key of the current node (null for the tree root) is passed as a query argument. The query typically has the form: select id from recursiveTable where fk=parameter
- expression: allows configuring the widget via JSONata. The result must be a node or an array of nodes. A node has the fields data and an optional field children. The widget displays the contents of data similar to the display widget. If data includes an icon field, the tree is displayed like this.
uploadfile
Allows uploading files to the upload directory. Note that WebDAV must be turned on using the DASHJOIN_WEBDAV_ENABLED environment variable (see Installation - Environment). Uploading requires one of the roles listed in DASHJOIN_WEBDAV_ROLES (defaults to "admin"), and the target folder must be within DASHJOIN_WEBDAV_ROOTS (defaults to "upload"). For instance, set DASHJOIN_WEBDAV_ROLES=admin,authenticated to allow uploads by API / non-admin users.
- allowFolderSelectionRecursive: Recursively get subdirectories
- preserveFolders: Preserve recursive folder structure at the destination