Skip to main content

Make the Widget Configurable

Our Text widget currently displays a static text. Let's allow users to change the text and its alignment.

How Configuration Works​

Users configure widgets in the sidebar of the dashboard builder. The form in the sidebar is generated from the config array in the mobro-widget-config.json. The widget reads the values the user entered using a hook of the Dashboard SDK. The name of a field connects the two:

Changing the Text​

Add a config array to the mobro-widget-config.json of the Text widget, containing a field of type string:

src/widgets/text/mobro-widget-config.json
{
  "name": "text",
  "displayName": "Text",
  "filename": "Text.tsx",
  "config": [
    {
      "name": "text",
      "label": "Text",
      "type": "string"
    }
  ]
}

After saving the file, select the Text widget on the dashboard. The sidebar now shows a text input labeled "Text". Entering a text doesn't change the widget yet, since the widget doesn't read the value.

caution

The name of a field must be unique within the widget, since it identifies the value stored for the field.

tip

Set up the JSON schemas in your IDE to get auto-completion for all field types and their properties.

Reading the Text​

For every field type, the Dashboard SDK provides a hook that returns the current value of a field by its name. For a string field, this is useStringField:

src/widgets/text/Text.tsx
import React from 'react'
import {useStringField} from '@modbros/dashboard-sdk'

export default function Text() {
  const text = useStringField({field: 'text', defaultValue: 'Text'})

  return <h1>{text}</h1>
}

The widget now re-renders with the new text whenever the user changes the field. The defaultValue is returned as long as the field is empty.

Aligning the Text​

Next, we'll allow users to align the text horizontally and vertically. Add two select fields to the configuration:

src/widgets/text/mobro-widget-config.json
{
  "name": "text",
  "displayName": "Text",
  "filename": "Text.tsx",
  "config": [
    {
      "name": "text",
      "label": "Text",
      "type": "string"
    },
    {
      "name": "align_horizontal",
      "label": "Align horizontal",
      "type": "select",
      "options": [
        {"label": "Left", "value": "flex-start"},
        {"label": "Center", "value": "center"},
        {"label": "Right", "value": "flex-end"}
      ]
    },
    {
      "name": "align_vertical",
      "label": "Align vertical",
      "type": "select",
      "options": [
        {"label": "Top", "value": "flex-start"},
        {"label": "Center", "value": "center"},
        {"label": "Bottom", "value": "flex-end"}
      ]
    }
  ]
}

Then read both values using useSelectField and align the text using a flex container. The container fills the whole widget, so the text can be aligned within it:

src/widgets/text/Text.tsx
import React from 'react'
import {useSelectField, useStringField} from '@modbros/dashboard-sdk'

export default function Text() {
  const text = useStringField({field: 'text', defaultValue: 'Text'})
  const alignHorizontal = useSelectField({field: 'align_horizontal', defaultValue: 'flex-start'})
  const alignVertical = useSelectField({field: 'align_vertical', defaultValue: 'flex-start'})

  return (
    <div
      style={{
        display: 'flex',
        width: '100%',
        height: '100%',
        alignItems: alignVertical,
        justifyContent: alignHorizontal
      }}
    >
      <h1>{text}</h1>
    </div>
  )
}

Resize the widget on the dashboard and change the alignment in the sidebar to see the text move.

Besides inline styles, you can also style widgets using styled-components, which MoBro provides to all widget packs.

More Options​

All available field types are described in In-depth: Configurable Widget Fields. With many fields, you can structure the sidebar using tabs and fieldsets.

For a complete text widget with font, font size and color options, check out the Text widget of the Shapes widget pack.

Next, let's build a widget that displays a metric.

Last updated on