Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Widgets

Widgets enable the presentation of case-specific data, either from the case's own data objects or from external data sources. This approach standardizes the display of case data across all cases and eliminates the need for knowledge of Form.io or HTML to present case data effectively.

Configuring widgets

Widget configuration is part of tab configuration for a case definition.

  • Go to the Admin menu

  • Go to the Cases menu and select the case to configure widgets for

  • Select the Case details tab

  • Select the Tabs tab

The list of configured tabs for a case is displayed within the case settings. To configure widgets, select an existing tab with its type set to Widgets, or add a new widget-type tab to the configuration by clicking the Add tab button as documented in the tabs documentation. Upon selection, the widget configuration for the chosen tab will open, displaying a list of widgets created for that tab.

Widget configuration UI

Layout algorithm

The way a widget tab's widgets are arranged can be chosen per tab. The same options are available for dashboards and IKO tabs.

Selector label

Stored value (widgetLayout)

Behaviour

Default (less gaps)

MUURI_GAP_FREE

An algorithm that fills small gaps, while keeping widgets in their configured order as much as possible. Used when nothing is configured (the original behaviour).

Default

MUURI

Plain layout algorithm without gap filling. Keeps the configured order, but empty gaps can remain.

Gap free

BEAUTIFUL

Custom dense-packing algorithm. May reorder widgets within a section to remove gaps and almost always produces a clean layout without holes.

Trade-off: Default and Default (less gaps) keep the widgets in the order you configured (predictable) but can leave empty space, while Gap free reorders widgets to eliminate gaps at the cost of changing their order.

Open the widget tab and click Edit widget tab. Pick an option in the Layout algorithm dropdown of the modal and save. An information block underneath the dropdown summarises the trade-off.

Add the optional widgetLayout property (one of the stored values above) to the tab object in the *.case-widget-tab.json file. When omitted, the layout falls back to MUURI_GAP_FREE.

Adding widgets

Click Add widget to open the create new widget modal that will guide the widget creation in 4 steps.

1

Choose widget type

The following widget types are currently supported:

  • Fields A set of single data elements in a widget.

  • Custom component An option to direct to a custom Angular component in de codebase.

  • Form.io form This type makes is possible to display a Form.io form within a widget. The form is prefilled with case data.

  • Table Present array case data in a table within a widget.

  • Collection Present array case data in a collection of cards within a widget.

  • Map Render geographic data on a map using GeoJSON sources.

  • Metroline Visualise the progression of a case as an ordered set of steps, driven either by the internal case status history or by the zaak status.

  • Person card Display personal data for a single person (full name, birth date, BSN, phone, email and city) in a compact card.

  • Highlight Compact widget that highlights a single value or the count of items in a collection.

  • Image Display image files stored on the case, either in a grid or as a carousel.

  • Text Show a fixed explanatory text, authored in markdown. The text is part of the widget configuration and is the same for every case.

Choosing widget type
2

Choose widget width

The widget can be configured to display on any number of columns between 1 and 4.

Choosing widget width
3

Choose widget appearance

For the Fields, Collection and Table widgets you can also choose an appearance color. This color controls the background, accent and text colors rendered by the widget. The available options are Default, Blue, Periwinkle, Purple, Turqoise, Green, Brown, Red, Orange and Yellow. The same value is stored in the widget configuration under the color property (using the enum names WHITE, BLUE, PERIWINKLE, etc.), so exported files and autodeploy definitions can set it directly as well.

4

Choose widget density

A widget can either have a "Default" density or it can be "Compact" to display data in a more efficient manner. For now, Compact mode is only available for the Fields, Table and Collection widgets

Choosing widget density
5

Choose widget content

Depending on the widget type, the content is filled in differently. Click the widget type below to view the details for configuration.

6

Choose widget conditions

By default each widget is shown in the UI. However, it is possible to add conditions to a widget that need to be met in order for the widget to be shown. This helps keep the widget page clean by hiding widgets that are not relevant to the current case.

Choosing widget conditions
Fields widget

To create a fields widget the following configurations need to be done.

  • Widget title The widget title is presented in the UI at the top-left corner of the widget and should describe the content for that widget.

  • Configure widget fields Each field can be configured to display case data in a certain way.

For each field that is added to the widget the following configuration is required in order to display the data correctly in the UI.

  • Field title This is presented as the label of the field

  • Field value Add the exact path to the data in the JSON document.

  • Display type Select the way the data is presented in the UI. Please find the available display types below.

Display types

The following display types are supported in the case widgets configuration.

Display type
Presentation

Text

Value is presented in the UI as regular text.

Yes/No

This converts a Boolean value to "Yes"/"No".

Date

Accepts a UTC date string as input. A format can be specified for how you wish the date to be displayed (this is optional).

Number

The number display type is based on the DecimalPipe* from Angular. Optional formatting can be specified for how you wish the number to be displayed.

Percentage

The percentage display type is based on the PercentPipe* from Angular. Optional formatting can be specified for how you wish the percentage to be displayed. By default any value is divided by 100, unless a format is specified. This has been done because of the values that the Angular PercentPipe* expects.

Currency

The currency display type is based on the CurrencyPipe* from Angular. Optional formatting can be specified for how you wish the currency to be displayed.

Enum

Enum (or enumerate) is meant to assign a value to a key as to display data more accurately. The key is stored in the JSON document, the value is configured in the enum, based on the key the corresponding value is displayed.

Below descriptions are from the following Angular documentation pages:

*Angular DecimalPipe

The value's decimal representation is specified by the digitsInfo parameter, written in the following format:

  • minIntegerDigits: Minimum number of integer digits before the decimal point. Default is 1.

  • minFractionDigits: Minimum number of digits after the decimal point. Default is 0.

  • maxFractionDigits: Maximum number of digits after the decimal point. Default is 3.

If the formatted value is truncated it will be rounded using the "to-nearest" method:

*Angular PercentPipe

Decimal representation options, specified by a string in the following format: {minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}.

  • minIntegerDigits: Minimum number of integer digits before the decimal point. Default is 1.

  • minFractionDigits: Minimum number of digits after the decimal point. Default is 0.

  • maxFractionDigits: Maximum number of digits after the decimal point. Default is 0.

*Angular CurrencyPipe

The format for the currency indicator. One of the following:

  • code: Show the code (such as USD).

  • symbol(default): Show the symbol (such as $).

  • symbol-narrow: Use the narrow symbol for locales that have two symbols for their currency. For example, the Canadian dollar CAD has the symbol CA$ and the symbol-narrow $. If the locale has no narrow symbol, uses the standard symbol for the locale.

  • String: Use the given string value instead of a code or a symbol. For example, an empty string will suppress the currency & symbol.

  • Boolean (marked deprecated in v5): true for symbol and false for code.

Widget columns

The fields widget is also able to display data on multiple columns. As such a column can be added or removed. However you cannot have more columns than the width of the widget (For example, if a widget has a width set to Medium you cannot add more than 2 columns to it)

Custom component widget

Knowledge requirements

  • Angular

Once a component is configured in Angular any user is able to configure the component in a widget. Adding the component itself is a developers task and programming skills are required. Documentation is available on this page to register a custom Angular component.

Adding a custom component widget to a page is easily done.

  • Widget title The widget title is presented in the UI at the top-left corner of the widget and should describe the content for that widget.

  • Angular component Registered Angular components in the front-end implementation of Valtimo will be listed in a dropdown menu. This component defines the widget content.

  • Key/Value custom values Here custom key/value pairs can be configured. In order for these to work, the component needs to have @Input fields that match the 'keys' configured in this screen. The values become accessible through the properties defined in the custom component

Form.io widget

For the Form.io widget there's only two fields that need to be configured:

  • Widget title The widget title is presented in the UI at the top-left corner of the widget and should describe the content for that widget.

  • Form.io form A dropdown is available with all Form.io definitions that are available in the implementation

Color tokens:

For the Form.io forms to be properly displayed in both normal and high contrast widgets, some custom CSS adjustments might be necessary. Form.io text should use the Carbon color tokens instead of regular hex values. For example:

Table widget

Knowledge requirements

  • Basic knowledge of JSON file structure.

A table widget can be used when arrays (lists) are stored in the case data structure and need to be presented as such in the case UI. The following fields need to be configured for a table widget.

  • Widget title The widget title is presented in the UI at the top-left corner of the widget and should describe the content for that widget.

  • Rows per page If the content exceeds the number of rows pagination will be added in the UI.

  • Path to table data The exact path in the JSON document that contains the array with data.

  • Table columns Columns need to be based on the available fields within the array data.

Configuring table columns

For each column in the table the following configurations needs to be done.

  • Title The title will be displayed as the label of the field in the widget.

  • Value The value itself will not actually be configured, the path targeting the value in the JSON document is configured. The value is passed through by the widget.

  • Display type Select the way the data is presented in the UI. Please find the available display types below.

The available display types are the same as for the fields widget.

Table widget configuration example

Below example shows the configuration for a table that displays uploaded files by there name and creation date.

The path in the JSON document for the array: doc:/uploadedFiles

The information from the array that is shown:

Since the location of the array itself is known it is no longer need to define a full JSON path for the values of the table columns. Only define the data location within the array like so: data/name

data/createdOn

To gather the data the widget code will combine the "Path to table data" field with the value fields from the column configuration. This results in the following JSON paths where x is filled by iterating over the array data.

doc:/uploadedFiles[x]/data/name

doc:/uploadedFiles[x]/data/createdOn

This configuration is based on below JSON. The uploadedFiles object exists in the root of this JSON document. Below the JSON a screenprint of the configuration in the Widget configuration UI.

Uploaded files table widget configuration

Table widget options

Below option there is a toggle available named "First column is the title of the row". Enabling this will display the first column with italics and no underline. See below screenshots for the difference in presentation in the result of above configuration. 6 files where uploaded for this example so 3 pages of each 2 files are shown in the widget.

Uploaded files with first column set as title column
Collection widget

Knowledge requirements

  • Basic knowledge of JSON file structure.

A collection widget can be used when arrays (lists) are stored in the case data structure and need to be presented as such in the case UI. The following fields need to be configured for a collection widget.

  • Widget title The widget title is presented in the UI at the top-left corner of the widget and should describe the content for that widget.

  • Number of cards per page If the content exceeds the number of rows pagination will be added in the UI.

  • Path to collection data The exact path in the JSON document that contains the array with data.

  • Card title display type Same as each text field, the title of the card can also be set to a certain display type.

Configuring cards

For each card in the collection the following configurations needs to be done.

  • Card title The title of each card can be set to a value from the array items. So the card title is not a label in this case, but a value from a array item.

  • Display type Select the way the card title is presented in the UI. Please find the available display types below.

Configuring card fields

A set of fields can be configured that will display the data for each card. The following configuration needs to be done to add a field to a card.

  • Title Will be displayed as the fields label in the UI.

  • Value The value itself will not actually be configured, the path targeting the value in the JSON document is configured. The value is passed through by the widget.

  • Display type Select the way the data is presented in the UI. Please find the available display types below.

  • Field width For each field the choice can be made to use the full width of the card or half.

The available display types are the same as for the fields widget.

Collection widget configuration example

Below example shows the configuration for a collection that displays uploaded files. Each card in the collection will get it's title and the card fields from the array data. The card name will be set to the file name. The card fields will show following information:

  • Created on

  • Storage bucket

  • Size (in bytes)\

The path in the JSON document for the array: doc:/uploadedFiles

The information from the array that is shown:

Since the location of the array itself is known it is no longer need to define a full JSON path for the values of the card fields. Only define the data location within the array like so: Card title: data/name Card fields:

data/createdOn

data/storageBucket

data/sizeInBytes

To gather the data the widget code will combine the "Path to collection data" field with the value fields from the card configuration. This results in the following JSON paths where x is filled by iterating over the array data.

doc:/uploadedFiles[x]/data/name

doc:/uploadedFiles[x]/data/createdOn

doc:/uploadedFiles[x]/data/storageBucket

doc:/uploadedFiles[x]/data/sizeInBytes

This configuration is based on below JSON. The uploadedFiles object exists in the root of this JSON document. Below the JSON a screenprint of the configuration in the Widget configuration UI.

Uploaded files collection widget configuration

Presentation in the UI

See below screenshot for the presentation result of a collection. 6 files where uploaded for this example so 3 pages of each 2 cards are shown in the widget.

Person card widget

Knowledge requirements

  • Basic knowledge of JSON file structure.

A person card widget displays personal data for a single person in a compact card. It is intended for cases that revolve around a natural person (for example a citizen) and surfaces the most common identifying details next to each other.

The following fields can be configured. Each field accepts a value path into the case document (for example doc:/applicant/fullName) — the widget resolves the path and renders the resulting value.

  • Widget title (required) The widget title is presented in the UI at the top-left corner of the widget and should describe the content for that widget.

  • Widget icon (optional) An MDI icon shown next to the widget title.

  • Full name (required) Path to the person's full name. This is the only required person field; the widget cannot be saved without it.

  • Birth date (optional) Path to the person's birth date.

  • BSN (optional) Path to the Dutch citizen service number (Burgerservicenummer).

  • Phone (optional) Path to the person's phone number.

  • Email (optional) Path to the person's e-mail address.

  • City (optional) Path to the person's city of residence.

Optional fields that resolve to an empty value are hidden in the rendered card, so the widget only shows fields that are actually filled in for the case.

Field paths:*

doc:/applicant/fullName

doc:/applicant/birthDate

doc:/applicant/bsn

doc:/applicant/phone

doc:/applicant/email

doc:/applicant/city

This configuration is based on below JSON.

Metroline widget

The metroline widget shows the progression of a case as an ordered set of steps, similar to a metro-line diagram. Each step represents a status the case has gone through or still needs to go through, and the currently active step is highlighted. Completed steps display the date and time they were reached.

Widget configuration

The metroline widget requires the following fields to be configured.

  • Widget title The widget title is presented in the UI at the top-left corner of the widget and should describe the content for that widget.

  • Widget icon (optional) An MDI icon shown next to the widget title.

  • Orientation Determines how the steps are laid out in the widget. Choose between Horizontal (steps run left-to-right) and Vertical (steps run top-to-bottom).

  • Status source Determines where the steps and their completion data come from. See the section below for the available sources.

Status sources

Status source
Description

Internal status

The steps are derived from the case's internal case status history. Each entry in the history becomes a step, in chronological order. The most recent entry is rendered as the current step; all earlier entries are rendered as completed and show the date and time at which the case moved into that status. The step title comes from the configured internal status title, with the status label shown in an info toggletip next to the step.

Zaak status

The steps are derived from the statustypen of the zaaktype linked to the case. All statustypen for the zaaktype are rendered in their defined order, so future statuses are visible up-front as incomplete steps. A step is marked complete once the matching status has been set on the zaak, and shows the date and time it was reached. The first not-yet-reached status is rendered as the current step. This source is only selectable when the zaken-api module is on the classpath; without it, the status source dropdown will not offer this option and the widget will fail to load data if it has been configured for it via JSON or autodeploy.

Step states

Each step in the rendered metroline is in one of the following states:

  • Current — the step the case is currently on. Highlighted with a distinct icon and styling.

  • Complete — a step the case has already passed. Displays the completion date and time.

  • Incomplete — a step the case has not yet reached. Only relevant for the Zaak status source, where future steps are known up-front.

The metroline widget does not use the Appearance (color) or Density (compact) options from the widget creation wizard. Those steps are still shown but do not affect the metroline rendering.

Text widget

The text widget shows a fixed block of explanatory text on a widget tab. Unlike the other widget types it does not read anything from the case document: the text is part of the widget configuration and is therefore identical for every case of that case definition. Use it to explain what is expected of a case handler, to point to a work instruction, or to introduce the widgets around it.

Configuration

  • Widget title The widget title is presented in the UI at the top-left corner of the widget and should describe the content for that widget.

  • Widget icon (optional) An MDI icon shown next to the widget title.

  • Text The content of the widget, authored as markdown. See the supported markdown below.

  • Accent color The color palette that is also available for the other widgets. For the text widget the color is chosen in the content step itself, because the separate Appearance step of the wizard is not shown for this type.

The widget width can be set to 1 up to 4 columns like any other widget. The Density (compact) step of the wizard is not shown for text widgets, as there is no data density to vary.

Supported markdown

The content is rendered as GitHub Flavored Markdown. The following is supported and styled by the widget:

  • Headings (#, ##, ###, ####)

  • Bulleted (-) and numbered (1.) lists

  • **bold** and *italic* text

  • Links: [link text](https://example.org)

  • Inline code and fenced code blocks

  • Block quotes (>), tables, images and horizontal rules (---)

A single newline is rendered as a line break, so the text appears the way it is typed in the editor — an empty line is not needed to break a line.

Asterisks must sit directly against the text

**bold** and *italic* only work without spaces between the asterisks and the text. ** bold ** is shown as plain text including the asterisks, and a line starting with * is read as a list item rather than as italic text. This is standard markdown behaviour.

Links open in a new tab

Every link in a text widget opens in a new browser tab, because the target is typically outside the case (an intranet page or a work instruction, for example). Relative links (/handbook), fragments (#top), mailto: and tel: links are supported as well.

The text widget resolves no case data, so a value resolver path (for example doc:/customer/name) placed in the content or in the URL of an action button is not substituted — it is shown as-is.

Sanitization

The rendered markdown is sanitized before it is displayed. Scripts, event handler attributes and links with a dangerous scheme (such as javascript: or data:) are removed. Raw HTML in the content is therefore not a way to work around the widget: anything the sanitizer considers unsafe is stripped, and the surrounding text stays visible.

Example

JSON Editor

Widgets for a case can also be configured directly through a JSON editor. For process engineers, configuring widgets in JSON may offer greater control and efficiency. In the second tab of the Widget configuration UI, a JSON editor displays the complete widget configuration in JSON format. This editor includes error-checking functionality to ensure the JSON structure is correct.

Access control

Access to the case widgets can be configured through access control. More information about access control can be found in the access control documentation.

Resources and actions

Resource type
Action
Effect

com.ritense.case_.domain.tab.CaseWidgetTabWidget

view

Allows viewing a case widget

Examples

Permission to view all case widgets
Permission to view all case widgets of one specific case type
Permission to view one specific case widget
Highlight widget

The highlight widget is a compact widget that draws attention to a single value or to the count of items in a collection. It is rendered one column wide and has a coloured accent border on the left.

Configuration

The widget configuration is split into three sections:

  1. Widget identity

    • Widget title — the label displayed at the top of the widget.

    • Icon — an optional MDI icon, identical to the icon picker used by the other widgets. The icon is rendered in the selected accent color in the top-right corner of the widget.

  2. Action

    • Action button type — optionally choose between a process action (start a process from the widget) or an external link, identical to the action button on the other widgets.

  3. Value & Accent color

    • Value — the value resolver path that will be displayed (for example doc:/customer/firstName or doc:/uploadedFiles). If the path resolves to a single primitive value (string, number, boolean) the value itself is rendered. If it resolves to an array, the number of items in the array is rendered instead.

    • Accent color — the same color palette that is available for the other widgets. The selected color is applied to the left-hand border and to the icon. The title and value text keep the default text colors so the highlighted value stays legible against any accent. In the color picker, colors that have a Carbon tag equivalent (Blue, Purple, Turquoise, Green, Brown, Red, High contrast) are previewed using the same canonical Carbon tones as the case status tags; the remaining colors (Periwinkle, Orange, Yellow, Default) keep their widget-specific tones.

The widget width is fixed to one column for highlight widgets and the width step in the wizard is hidden accordingly.

Empty / invalid path handling

When the configured path does not resolve to a value (path missing in the document, value is null/undefined, or the resolved value is a non-primitive object), the widget renders a discreet "No value" placeholder rather than a stringified representation of the underlying object.

Image widget

The image widget displays image files that are stored on the case. It resolves a value resolver path to one or more uploaded file resources and renders the ones that are browser-renderable images. Each image is shown with its file name and with buttons to open the image in a new tab or download it.

Configuration

The widget configuration is split into three sections:

  1. Widget identity

    • Widget title — the label displayed at the top of the widget.

    • Icon — an optional MDI icon, identical to the icon picker used by the other widgets.

  2. Action

    • Action button type — optionally choose between a process action (start a process from the widget) or an external link, identical to the action button on the other widgets.

  3. Value

    • Value — the value resolver path that points to the file resources to display (for example doc:/uploadedFiles). The path must resolve to one or more uploaded file resources.

    • Display as carousel — when enabled, the images are presented one at a time in a carousel with navigation dots and previous/next arrows instead of the default grid. The carousel is only used when more than one image is resolved; with a single image the carousel controls are hidden.

Supported formats

Only browser-renderable image files are shown: png, jpg, jpeg, gif, webp, avif, svg, bmp and ico. Resources that resolve to other file types (for example a PDF) are filtered out so they are not rendered incorrectly.

Empty handling

When the path resolves to no renderable images, the widget renders a "No image found" placeholder.

PreviousTabs
NextCase Header Widget

Last updated