Dashview Docs - Form Widget

1. Core gedrag

Wat deze widget doet

Rendert formuliervelden direct in een dashboardwidget.
Stuurt veldwaarden door naar datasourcefilters, webhook, of beide.
Kan meerdere target datasources tegelijk patchen via targetDataSourceUids.
Kan keuzevelden vullen uit statische opties of uit een datasource.

Belangrijke runtime notities

fields[].key is tegelijk de formulierkey, de datasource filterkey en de webhook param key, behalve voor display-only html-velden.
editor-velden zijn juist wél actief: die sturen rich HTML mee naar filters/webhook.
Form widget vereist geen page filter definitie voor die keys.
Als een datasource filters als request params forwardt, gedraagt een form field zich standaard zoals een normale page filter: request param naar de datasource en, als de kolom bestaat, ook een lokale DuckDB filter.
repeater-velden zijn de uitzondering: die gaan altijd request-only als één JSON datasource-param en worden niet als lokale DuckDB filter uitgelegd.
Laat je targetDataSourceUids leeg, dan gebruikt de widget eerst dataSourceUid en anders de primary datasource.
Breedtes full, half, third, quarter, fifth en sixth mappen naar een interne 60-koloms layout; mobiel valt terug naar één kolom.
date-velden volgen dezelfde daterange-contracten als de normale dashboardfilters: submit gebruikt {key}From en {key}To, waarbij To de exclusieve bovengrens van de gekozen einddag is.
time-velden bewaren een lokale HH:mm-waarde en submitten die direct onder de veldkey, zonder verborgen datum of UTC-conversie.
Zet je een number-veld op valueType: currency, dan rendert de invoer als echte valuta-input met configureerbare currencyCode en currencyDisplay, terwijl submit nog steeds een numerieke waarde verstuurt.
Widget state wordt per gebruiker onthouden in userSettings, gescoped op pagina + widget-id, zodat je bij terugkomen je laatste formulierwaarden terugziet.

Key	Type	Beschrijving
`submitMode`	`filters` / `webhook` / `both`	Bepaalt of submit filters bijwerkt, webhook triggert, of beide doet.
`targetDataSourceUids`	string[]	Optionele lijst van datasources die de filterpatch moeten ontvangen.
`buttonLabel`	string	Tekst op de submitknop.
`buttonIcon`	string	PrimeIcon class, bijvoorbeeld `pi pi-send`.
`buttonSeverity`	PrimeNG severity	Knopstijl zoals `primary`, `info` of `danger`.
`filterSuccessMessage`	string	Optionele succesmelding nadat filters zijn bijgewerkt in `filters`-mode.
`bothSuccessMessage`	string	Optionele succesmelding voor de filterfase in `both`-mode, voordat webhook statusupdates binnenkomen.
`confirmBeforeSubmit`	boolean	Default `true`. Toont eerst een bevestigingsdialoog; die dialoog gebruikt geen backdrop/mask.
`clearAfterSubmit`	boolean	Zet alleen de widgetvelden terug naar hun default/state startwaarde na een succesvolle submit.
`persistedState`	automatisch	De widget bewaart runtime veldwaarden standaard in user settings per pagina + widget, vergelijkbaar met dashboardfilters.
`fields`	array	Schema van de formuliervelden.

2. Veldschema

Field key	Type	Uitleg
`key`	string	Verplicht en uniek binnen het formulier. Dit is de runtime key die naar filters/webhook gaat.
`label`	string	UI label; bij leeg wordt `key` gebruikt.
`type`	`text`, `textarea`, `number`, `date`, `time`, `dropdown`, `multiselect`, `checkbox`, `toggle`, `editor`, `html`, `repeater`	Controleert welke PrimeNG input wordt gerenderd. `date` is een daterange-picker; `time` bewaart een lokale `HH:mm`-tijd.
`placeholder`	string	Optioneel voor tekst-, textarea-, number-, date- en selectvelden.
`content`	string	Alleen voor `html`. Rauwe tekst/HTML die als display-only inhoud in het formulier wordt gerenderd.
`allowDecimals`	boolean	Alleen voor `number`. Laat decimalen toe; `decimal`, `currency` en `percent` forceren dit ook.
`min` / `max`	number	Alleen voor `number`. Optionele onder- en bovengrens.
`step`	number	Alleen voor `number`. Stapgrootte van de PrimeNG InputNumber knoppen/invoer.
`minFractionDigits` / `maxFractionDigits`	number	Alleen voor `number`. Bepaalt hoeveel decimalen zichtbaar/toegestaan zijn.
`currencyCode` / `currencyDisplay`	string	Alleen relevant wanneer `type = number` en `valueType = currency`. Stuurt de zichtbare valuta aan, bijvoorbeeld `EUR` met symboolweergave.
`required`	boolean	Blokkeert submit zolang het veld leeg is.
`width`	`full`, `half`, `third`, `quarter`, `fifth`, `sixth`	Layoutbreedte binnen de widgetgrid.
`valueType`	filter value type	Coercion naar runtime filter/webhook waarde, bijvoorbeeld `number`, `date` of `datetime`.
`visibleWhen`	array	Toont een veld alleen wanneer alle regels matchen.
`enabledWhen`	array	Laat een veld zichtbaar maar disabled totdat alle regels matchen.
`requiredWhen`	array	Maakt een veld conditioneel verplicht bovenop de basis `required`.
`clearOnParentChange`	boolean	Reset het veld naar de default/startwaarde zodra een afhankelijk bronveld verandert.
`submitWhenHidden`	boolean	Stuurt verborgen veldwaarden toch mee; default is verborgen velden overslaan.
`requestOnly`	boolean	Opt-in escape hatch: stuur dit veld alleen als datasource request-param en sla de lokale DuckDB filter over.
`rowFields`	array	Alleen voor `repeater`. Definieert het schema van elk object in de array.
`minRows` / `maxRows`	number	Minimaal en maximaal aantal regels voor een repeater.
`addRowLabel`	string	Tekst op de knop om een extra regel toe te voegen.
`emptyStateText`	string	Tekst die getoond wordt wanneer een repeater nog geen regels bevat.

Layout interpretatie

full: 1 veld per rij.
half: 2 velden per rij vanaf medium/desktop breedte.
third: 3 velden per rij vanaf xl/desktop breedte.
quarter: 4 velden per rij vanaf xl/desktop breedte.
fifth: 5 velden per rij vanaf xl/desktop breedte.
sixth: 6 velden per rij vanaf xl/desktop breedte.
Op small screens vallen alle velden terug naar full width.
editor-velden gebruiken standaard een hogere editorhoogte, maar volgen verder dezelfde breedteregels als andere velden.

Type-specifieke notities

date gebruikt een PrimeNG daterange-picker en submit als {key}From / {key}To. To is de echte exclusieve volgende dag, net als in de filterbalk.
editor gebruikt dezelfde rich HTML editorstijl als de webhook widget en submit de HTML string.
html blijft een passief displayblok voor uitleg of markup en valideert/verstuurt niets.
number kan integer of decimal zijn, met optionele min, max, step en fraction digits.

Repeater / array-of-objects

Gebruik type: "repeater" wanneer één veld eigenlijk een lijst van regels is, bijvoorbeeld business rules of meerdere voorwaarden.
Elke regel gebruikt het schema uit rowFields en levert één object op in de uiteindelijke array.
Webhook submit houdt die waarde als echte JSON-array van objecten.
Datasource submit verstuurt dezelfde array als één JSON query param, zodat Element of API datasources hem kunnen uitlezen zonder querystring flattening.
Gebruikers kunnen repeater-regels in de widget zelf omhoog of omlaag verplaatsen met de inline actieknoppen.
rowFields kunnen binnen dezelfde regel ook hun eigen visibleWhen, enabledWhen, requiredWhen, clearOnParentChange, submitWhenHidden en optionFilterBindings gebruiken.
Nested repeaters worden bewust niet ondersteund; rowFields zijn in v1 alleen normale inputtypes.

Volgorde aanpassen

De volgorde van top-level velden en repeater rowFields volgt direct de arrayvolgorde in de widgetconfig.
In de widget editor kun je die volgorde aanpassen met de up/down knoppen op elk veldblok; er is geen aparte sort-index nodig.

3. Afhankelijkheden en parent/child gedrag

Rule key	Type	Beschrijving
`fieldKey`	string	De key van het bronveld waar deze regel naar kijkt.
`operator`	`equals`, `notEquals`, `in`, `notIn`, `isEmpty`, `isNotEmpty`, `truthy`, `falsy`	Vergelijkingsoperator voor de parent/child logica.
`value`	any	Single waarde voor `equals` of `notEquals`.
`values`	array	Lijst van waarden voor `in` of `notIn`.

Hoe de widget dit interpreteert

Elke block visibleWhen, enabledWhen en requiredWhen werkt als AND: alle regels moeten matchen.
Je kunt hiermee bijvoorbeeld een tekstveld pas tonen als een toggle aan staat, of een child veld pas verplicht maken als een parent dropdown een bepaalde waarde heeft.
Verborgen of disabled velden worden standaard niet meegestuurd naar filters of webhook, tenzij submitWhenHidden expliciet aan staat.
clearOnParentChange is handig voor child dropdowns of tekstvelden die niet geldig blijven als de parentkeuze verandert.
requestOnly gebruik je alleen wanneer een veld wel een datasourceparam moet zijn, maar niet als lokale filter op de gerenderde DuckDB rows mag landen.
Voor repeater-velden werken dezelfde dependencyblokken ook binnen één regel: een rowField kan dus reageren op andere velden in dezelfde regel.

4. Keuzevelden en optiebronnen

Key	Gebruik	Notities
`optionsSource`	`static` / `datasource`	Alleen relevant voor `dropdown` en `multiselect`.
`options[]`	array van `{ label, value }`	Statische keuzes; `value` mag string, number, boolean of JSON-parsebare literal zijn.
`optionsDataSourceUid`	string	Optionele aparte datasource voor keuzeopties. Bij leeg valt de widget terug op de widget datasource of primary datasource.
`optionsValueField`	string	Kolom die als option value gebruikt wordt. Bij leeg valt dit terug op de veld `key`.
`optionsLabelField`	string	Kolom voor het zichtbare label. Bij leeg wordt de value getoond.
`optionsFilter`	object	Extra filterobject bovenop de actieve dashboard filters voor de option lookup.
`optionFilterBindings`	array	Mapt waarden uit andere formuliervelden naar datasource filterparams voor de option lookup.

Lookup gedrag

Datasource-backed keuzevelden gebruiken distinct values uit de gekozen datasource.
Actieve dashboardfilters worden meegenomen in de option lookup.
De huidige veldkey zelf wordt uit die option lookup filters verwijderd om self-filter loops te voorkomen.
optionFilterBindings laat child dropdowns of multiselects reageren op eerdere veldkeuzes zonder aparte page filters.
Binnen een repeater kijkt optionFilterBindings van een rowField alleen naar sibling velden in dezelfde regel, niet naar andere regels.
Resultaten worden alfabetisch/numeriek gesorteerd op label.

5. Submit modes en webhook

Mode	Gedrag	Benodigde keys
`filters`	Patcht veldwaarden naar datasource filterparams.	`fields`
`webhook`	Stuurt veldwaarden als webhook params.	`fields` plus `webhookId` of `url`
`both`	Doet eerst de filterpatch en start daarna de webhook.	`fields` plus `webhookId` of `url`

Webhook key	Type	Beschrijving
`webhookId`	string	Optionele technische ID voor tracing/logica.
`url`	string	Webhook endpoint.
`method`	GET/POST/PUT/PATCH/DELETE	HTTP methode, default `POST`.
`headers`	object of array	Extra request headers.
`auth`	object	Zelfde auth schema als de losse Webhook widget.
`refreshAfterRun`	boolean	Herlaadt dashboarddata na een succesvolle webhookrun.

Praktische use-cases

Element datasource trigger: submit naar filters zodat een datasource opnieuw laadt met runtime params.
Lead/contact formulier: submit naar webhook zonder datasourcekoppeling.
Workflow + dashboard refresh: gebruik both om filters te updaten én een audit/side-effect webhook te sturen.

Statusmeldingen en validatie

Gebruik filterSuccessMessage en bothSuccessMessage om de groene submitmelding aan te passen.
Webhook statusmeldingen zoals running/completed blijven uit de webhook stream komen en kunnen de eerdere filtermelding overschrijven.
Validatie- en webhookfouten worden in de widget niet dubbel getoond wanneer summary en detail dezelfde tekst hebben.

6. Voorbeeld form options JSON

{
  "submitMode": "both",
  "targetDataSourceUids": ["customer_search"],
  "buttonLabel": "Zoeken",
  "buttonIcon": "pi pi-search",
  "buttonSeverity": "primary",
  "clearAfterSubmit": false,
  "fields": [
    {
      "key": "customerId",
      "label": "Klantnummer",
      "type": "text",
      "required": true,
      "width": "half"
    },
    {
      "key": "status",
      "label": "Status",
      "type": "multiselect",
      "width": "half",
      "visibleWhen": [
        { "fieldKey": "includeInactive", "operator": "truthy" }
      ],
      "clearOnParentChange": true,
      "optionsSource": "static",
      "options": [
        { "label": "Actief", "value": "active" },
        { "label": "Inactief", "value": "inactive" }
      ]
    },
    {
      "key": "country",
      "label": "Land",
      "type": "dropdown",
      "width": "third",
      "optionsSource": "datasource",
      "optionsDataSourceUid": "country_options",
      "optionsValueField": "code",
      "optionsLabelField": "name",
      "optionsFilter": { "enabled": true },
      "optionFilterBindings": [
        { "sourceFieldKey": "customerId", "targetFilterKey": "customerId" }
      ]
    },
    {
      "key": "includeInactive",
      "label": "Inclusief inactief",
      "type": "toggle",
      "width": "third"
    },
    {
      "key": "notes",
      "label": "Opmerking",
      "type": "textarea",
      "width": "full",
      "placeholder": "Optionele context voor de webhook"
    },
    {
      "key": "rules",
      "label": "Business rules",
      "type": "repeater",
      "width": "full",
      "requestOnly": true,
      "addRowLabel": "Regel toevoegen",
      "emptyStateText": "Nog geen regels toegevoegd.",
      "rowFields": [
        {
          "key": "field",
          "label": "Veld",
          "type": "text",
          "width": "third"
        },
        {
          "key": "operator",
          "label": "Operator",
          "type": "dropdown",
          "width": "third",
          "optionsSource": "static",
          "options": [
            { "label": "Is gelijk aan", "value": "equals" },
            { "label": "Is niet gelijk aan", "value": "notEquals" }
          ]
        },
        {
          "key": "value",
          "label": "Waarde",
          "type": "text",
          "width": "third"
        }
      ]
    }
  ],
  "webhookId": "audit_customer_search",
  "url": "https://api.example.com/audit",
  "method": "POST",
  "headers": [
    { "key": "X-Flow", "value": "customer-search" }
  ],
  "refreshAfterRun": true
}

Form widget: volledige instelling reference

1. Core gedrag

Wat deze widget doet

Belangrijke runtime notities

2. Veldschema

Layout interpretatie

Type-specifieke notities

Repeater / array-of-objects

Volgorde aanpassen

3. Afhankelijkheden en parent/child gedrag

Hoe de widget dit interpreteert

4. Keuzevelden en optiebronnen

Lookup gedrag

5. Submit modes en webhook

Praktische use-cases

Statusmeldingen en validatie

6. Voorbeeld form options JSON