Actions

Actions are operations provided by plugins, e.g. to pause media playback, change the volume or run a program. Users trigger actions from their dashboards. Plugins define and register actions, see Plugins: Action.

There are two ways a widget can trigger actions:

• Any widget can trigger an action when clicked. This doesn't require any code.
• Widgets can define action fields to trigger actions from code, e.g. different actions for different buttons.

Actions on Any Widget

In the dashboard builder, users can enable an action for every widget and select the action to execute. Clicking the widget on the dashboard then executes the action and shows a ripple effect.

Your widget doesn't need to do anything to support this. It's the right choice for widgets that trigger a single action, e.g. a button.

Action Fields

To trigger actions from code, add a field of type action for each action to the widget configuration. Users select the action for each field in the dashboard builder, including the settings the action requires.

useActionField returns a callback that executes the selected action:

src/widgets/play-pause/mobro-widget-config.json

{
  "name": "play_pause",
  "displayName": "Play / Pause",
  "filename": "PlayPause.tsx",
  "config": [
    {
      "name": "play_action",
      "label": "Play action",
      "type": "action"
    },
    {
      "name": "pause_action",
      "label": "Pause action",
      "type": "action"
    },
    {
      "name": "playing_metric",
      "label": "Playing metric",
      "type": "metric",
      "filters": {
        "valueTypes": ["Boolean"]
      }
    }
  ]
}

src/widgets/play-pause/PlayPause.tsx

import React, {MouseEvent} from 'react'
import {useActionField, useMetricField, useRipple} from '@modbros/dashboard-sdk'

export default function PlayPause() {
  const play = useActionField({field: 'play_action'})
  const pause = useActionField({field: 'pause_action'})
  const playing = useMetricField({field: 'playing_metric'})
  const ripple = useRipple()

  const isPlaying = Boolean(playing?.value.value)

  const onClick = (event: MouseEvent) => {
    ripple(event.clientX, event.clientY)

    if (isPlaying) {
      pause()
    } else {
      play()
    }
  }

  return (
    <button style={{width: '100%', height: '100%'}} onClick={onClick}>
      {isPlaying ? 'Pause' : 'Play'}
    </button>
  )
}

The callback returned by useActionField does nothing while the dashboard is edited in the dashboard builder, or if the user didn't select an action.

useRipple shows the same ripple effect as clicking a widget with an action enabled, giving users visual feedback that the action was triggered.

tip

Actions often change the state that a metric reflects, e.g. whether media is playing. Display that metric in the widget, as in the example above, so users see the result of the action.

For complete examples, check out the Actions and Media Controls widget packs.