Parameters and events

Parameters and events are the primary mechanisms for widgets to interact with host applications like Workshop. Parameters allow host applications to pass data into the widget, while events enable widgets to communicate back to the host application.

When developing custom widgets, you define parameters to allow users to configure widget behavior and interact with the host application, and you define events to enable two-way communication. This page explains the available parameter types, their formatting requirements, and how to use events.

Available parameter types

Parameters can be defined as either primitive types or arrays of primitive types.

Primitive types

Usage in parameter definitions

When defining parameters in your widget configuration file, use the appropriate type designation:

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  parameters: {
    // Primitive parameter example
    startDate: {
      type: "date",
      displayName: "Start Date"
    },
    // Array parameter example
    tags: {
      type: "array",
      subType: "string",
      displayName: "Tags"
    }
  }
}

Unavailable parameter types

Types such as object sets, object set filters, and structs are currently unsupported as first-class parameter types for custom widgets.

Events

Events allow widgets to communicate with the host application (such as Workshop) and trigger side effects or update parameters. Events can be defined in your widget configuration file alongside parameters.

Defining events

Events are defined in the widget configuration file with the following structure:

Copied!
1
2
3
4
5
6
7
8
{
  events: {
    myEventId: {
      displayName: "Human-readable event name",
      parameterUpdateIds: ["parameter1", "parameter2"],
    },
  },
}

The parameterUpdateIds field specifies which parameters can be updated when this event is triggered.

Using parameters and events

Below is a complete example showing both the widget configuration and usage in React.

First, define parameters and events in your configuration file:

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
import { defineConfig } from "@osdk/widget.client";

export default defineConfig({
  id: "simple-counter",
  name: "Simple Counter",
  description: "A minimal counter example",
  type: "workshop",
  parameters: {
    name: {
      displayName: "Name",
      type: "string",
    },
    count: {
      displayName: "Count",
      type: "number",
    }
  },
  events: {
    updateCount: {
      displayName: "Update Count",
      parameterUpdateIds: ["count"],
    }
  }
});

Then, use these parameters and events in your widget component:

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
import { type FoundryWidgetClientContext, useFoundryWidgetContext } from "@osdk/widget.client-react";
import React, { useCallback } from "react";
import type SimpleCounterConfig from "./simple-counter.config.js";

const useWidgetContext = useFoundryWidgetContext.withTypes<typeof SimpleCounterConfig>();

export const Widget = () => {
  const { parameters, emitEvent } = useWidgetContext();

  const name = parameters.values.name ?? "World";
  const count = parameters.values.count ?? 0;

  const increment = useCallback(() => {
    emitEvent("updateCount", {
      parameterUpdates: { count: count + 1 },
    });
  }, [emitEvent, count]);

  return (
    <div>
      <h1>Hello, {name}!</h1>
      <p>Count: {count}</p>
      <button onClick={increment}>Increment</button>
    </div>
  );
};

Parameter and event binding in Workshop

In Workshop, widget parameters can be bound to Workshop variables and widget events can be bound to Workshop events in the Widget setup panel. This allows for two-way communication where:

1. Workshop can pass data to widgets through parameter bindings, and a widget can update these parameters by emitting events
2. Workshop events can also be bound to widget events in order to trigger side-effects in Workshop