Widget reference

Element widget: Python-logica direct op je dashboard

De Element widget is de meest flexibele dashboardwidget in Dashview. Zij voert een gepubliceerd Element uit en kan een renderbare widgetconfig, interactieve UI of beide teruggeven. Daarmee kun je dynamische widgets bouwen die standaard widgettypes combineren met Python-logica en eigen knoppen of formulieren.

Naar Elements hub Runtime reference Runtime Thema context Resultaatcontract Interactieve UI

Element widget: Python-logica direct op je dashboard overzicht screenshot placeholder — Maak hier een screenshot van het hoofdscherm voor Element widget: Python-logica direct op je dashboard overzicht, met de belangrijkste controls en een representatieve zichtbare state.

1. Wanneer kies je voor een Element widget?

Dynamische visualisatie

Gebruik deze widget wanneer het uiteindelijke widgettype of de inhoud pas tijdens runtime bepaald kan worden.

Python-first logica

Geschikt voor complexe berekeningen, custom renderinglogica of output die niet netjes in een gewone chart of tabel past.

Herbruikbaar bouwblok

Wanneer hetzelfde Element ook in een automation of datasource-transform terugkomt, houd je logica gecentraliseerd.

Niet voor

Gebruik geen Element widget voor simpele KPI’s, tabellen of charts die met standaardopties al onderhoudbaar zijn.

2. Runtime-instellingen

Optie	Verplicht	Beschrijving
`elementId`	Ja	Het Element dat de widget aanstuurt. Zonder deze waarde kan de widget niet draaien.
`elementVersion`	Nee	Laat leeg voor de laatste gepubliceerde versie of pin bewust een specifieke release.
`entrypoint`	Nee	Override op de standaard entrypoint als je Element meerdere uitvoerpaden heeft.
`timeoutSeconds`	Nee	Beschermt het dashboard tegen te lange runs; houd dit laag genoeg voor een prettige UX.
`runnerTier`	Nee	Kies `tiny` voor lichte runs (512Mi), of alleen een grotere tier als het Element meer geheugen of CPU nodig heeft.
`tableName`	Nee	Naam voor inline row-output wanneer het Element naast de widgetconfig ook rijen terugstuurt.

3. Filterdoorgifte en params

Een Element widget kan de actieve dashboardcontext meekrijgen. Dat maakt haar krachtig, maar ook gevoelig voor verkeerde aannames. Test daarom altijd met echte paginafilters.

Schakel filterdoorgifte in wanneer het Element moet reageren op dezelfde filters als de rest van de pagina.
Gebruik een expliciete filterbron als de widget met een specifieke datasourcecontext moet werken.
Gebruik een duidelijke filters-sleutel of eigen param key zodat collega’s meteen begrijpen wat er wordt doorgegeven.
Extra params moeten een JSON-object zijn. Gebruik geen losse array of scalar als rootwaarde.

{
  "from": "2026-03-01",
  "to": "2026-03-31",
  "segment": "enterprise",
  "showWarnings": true
}

4. Thema context

Bij elke Element widget-run voegt Dashview runtime metadata toe aan params.__dashview. Gebruik dit om HTML of CSS passend te maken voor lightmode en darkmode.

{
  "__dashview": {
    "theme": {
      "mode": "dark",
      "isDark": true,
      "isLight": false
    },
    "widget": {
      "id": "widget_dynamic_html",
      "type": "element"
    }
  }
}

def run(context, params):
    theme = (params.get("__dashview") or {}).get("theme") or {}
    dark = theme.get("mode") == "dark"
    bg = "#111827" if dark else "#ffffff"
    fg = "#f9fafb" if dark else "#111827"

    return {
        "widget": {
            "id": "theme_aware_html",
            "type": "html",
            "options": {
                "content": f"<div style='background:{bg};color:{fg}'>Theme aware</div>",
                "sanitizeHtml": True
            }
        }
    }

5. Resultaatcontract

Wat het Element terug moet geven

Een renderbare widgetconfig, meestal onder result.widget.
Of een interactieve UI onder result.ui, bijvoorbeeld met tekst, knoppen of formulieren.
Je mag result.widget en result.ui tegelijk teruggeven. De interactieve UI staat standaard onder de widget; gebruik placement: "before" om haar erboven te tonen.
Optioneel extra rows of feed-data als de uiteindelijke widget die zelf nodig heeft.
Een stabiele, begrijpelijke outputvorm zodat het dashboard voorspelbaar blijft bij volgende releases.

Wat je beter vermijdt

Een tweede Element widget als resultaat. Dat maakt de runtimeketen onnodig moeilijk te begrijpen.
Te zware of te trage renderlogica voor elke dashboardrefresh.
Verborgen afhankelijkheden van secrets, runtime vars of filters zonder documentatie.

6. Interactieve UI

Met result.ui kan een Element widget kleine interactieve applicaties renderen zonder aparte frontendcode. Ondersteunde nodes zijn container, row, text, html, button, form, divider en spacer. Formuliervelden ondersteunen text, textarea, number, select, checkbox en hidden.

def run(context, params):
    dashview = params.get("__dashview") or {}
    interaction = dashview.get("interaction")
    state = dashview.get("state") or {"count": 0}

    if interaction and interaction.get("id") == "increment":
        state["count"] = int(state.get("count") or 0) + 1

    return {
        "widget": {
            "type": "html",
            "options": {"content": "<p>De normale widget-output blijft werken.</p>"}
        },
        "state": state,
        "ui": {
            "type": "container",
            "placement": "after",
            "children": [
                {"type": "text", "variant": "title", "text": f"Teller: {state['count']}"},
                {"type": "button", "id": "increment", "label": "Verhoog", "severity": "success"},
                {
                    "type": "form",
                    "id": "feedback",
                    "label": "Feedback",
                    "fields": [
                        {"id": "message", "label": "Bericht", "type": "textarea", "required": True},
                        {"id": "urgent", "label": "Urgent", "type": "checkbox"}
                    ],
                    "submitLabel": "Verstuur"
                }
            ]
        }
    }

Een klik of formulier-submit voert hetzelfde Element opnieuw uit. Dashview stuurt de actie mee als params.__dashview.interaction en de vorige state als params.__dashview.state. HTML-nodes worden door de frontend gesaneerd en zijn bedoeld voor markup; JavaScript en inline event handlers worden niet uitgevoerd.

7. Aanbevolen werkwijze

Bouw en test het Element eerst los in de Elements-sectie.
Publiceer daarna pas een stabiele versie.
Koppel die gepubliceerde versie in de widget-editor.
Controleer met echte dashboardfilters en tenantrechten of de widget exact de verwachte output geeft.
Gebruik een pinned versie voor kritische dashboards wanneer voorspelbaarheid belangrijker is dan automatisch meeliften op de laatste publish.

8. Veelvoorkomende problemen

Probleem	Wat meestal helpt
Widget slaat niet op	Controleer of `elementId` gevuld is en extra params geldig JSON-object zijn.
Runtimefout bij openen dashboard	Controleer publish-status, runtime vars/secrets en of het Element nog een geldige widgetconfig retourneert.
Output verandert onverwacht	Pin een specifieke `elementVersion` in plaats van altijd de nieuwste release te gebruiken.
Filters lijken niet mee te gaan	Controleer filterdoorgifte, filterbron en de sleutel waaronder filters in params belanden.

8. Editoruitleg

Element widget editor

Kies eerst het juiste Element en beslis daarna of je een vaste versie wilt pinnen.
Timeout, filterdoorgifte en JSON-params bepalen het runtimegedrag van de widget.
Test altijd de uiteindelijke widgetoutput op de pagina, niet alleen het losse Element.

De widget is pas af wanneer zowel de editorconfig als de teruggegeven runtimeweergave klopt.