Overlay parameters | Docs

A parameter is a value the operator can change in your overlay’s settings, live, without touching your design: a name, a size, a colour. You declare each in the manifest, and your page receives them all as an event. The Starter Lower Third uses one of every kind.

Declaring a parameter

Each parameter is an entry in the manifest’s parameters list:

{
  "id": "name",
  "label": "Name",
  "type": "text",
  "default": { "kind": "text", "value": "Alex Morgan" }
}

id is how your page reads it. Keep it short and never change it: a renamed id is a new parameter, and the operator’s value for the old one is lost.
label is what the operator sees.
type is one of the seven below.
default is the value before the operator changes it, as a kind and a value. The kind is the one your page receives, which for two types is not the same word as the type.

The seven types

Text

{ "id": "name", "label": "Name", "type": "text", "default": { "kind": "text", "value": "Alex Morgan" } }

A one-line field. Add "multiline": true for a larger box that takes line breaks. The value is still plain text; to show the operator’s line breaks, give the element white-space: pre-line.

Number

{
  "id": "textSize", "label": "Name size (pixels)", "type": "number",
  "minimum": 32, "maximum": 96, "step": 1,
  "default": { "kind": "number", "value": 56 }
}

A number field. With both a minimum and a maximum, the operator also gets a slider between them, moving in steps. Declaring a range is worth it: it keeps the operator from setting something your design cannot take.

Colour

{ "id": "accent", "label": "Accent colour", "type": "color", "default": { "kind": "color", "value": "#FA705C" } }

A colour picker with an opacity control. The value is # and six hex digits, or eight when the operator has made the colour see-through: the last two digits are its opacity (#FA705C99). A stylesheet reads either as it is, so you can hand the value straight to CSS. Don’t add an opacity slider beside a colour to make it see-through, since the colour already carries that.

On or off

{ "id": "showTagline", "label": "Show the tagline", "type": "boolean", "default": { "kind": "boolean", "value": true } }

A switch. The value is true or false.

Image

{ "id": "logo", "label": "Logo", "type": "image", "default": { "kind": "image" } }

One picture the operator chooses, such as a logo. The default has no value: there is no picture until one is chosen. Your page receives the picture itself, ready to use as an image’s src. A file over 8 MB, or one that cannot be read, arrives as no picture.

Folder of images

{ "id": "sponsors", "label": "Sponsor logos", "type": "imageFolder", "default": { "kind": "image" } }

Every picture in a folder the operator chooses, in filename order: sponsor logos, a gallery. Files over 8 MB, or that cannot be read, are left out, and a folder whose pictures come to more than 48 MB altogether arrives as an empty list.

Choice

{
  "id": "alignment", "label": "Position", "type": "choice",
  "options": [
    { "value": "left", "label": "Left" },
    { "value": "center", "label": "Centre" },
    { "value": "right", "label": "Right" }
  ],
  "default": { "kind": "text", "value": "left" }
}

Buttons side by side, one for each option, showing your labels. Your page receives the chosen option’s value. Every value must be different, and the default must be one of them. Use a choice wherever a typed value could only be wrong.

Reading them in your page

Your page is sent every parameter’s value at once, whenever any one changes, as the interdirector:parameters event:

window.addEventListener("interdirector:parameters", function (event) {
  var values = event.detail;
  // values.name   is { kind: "text", value: "Alex Morgan" }
  // values.accent is { kind: "color", value: "#FA705C" }
});

Each value comes with its kind. Check it before using the value:

function valueOf(parameter, kind) {
  if (!parameter || parameter.kind !== kind) return null;
  return parameter.value;
}

var name = valueOf(event.detail.name, "text");
if (name !== null) document.getElementById("name").textContent = name;

What each type sends:

`type`	`kind`	`value`
`text`	`text`	the text
`number`	`number`	a number
`color`	`color`	`"#RRGGBB"`
`boolean`	`boolean`	`true` or `false`
`image`	`image`	`{ data, name }`, or no `value` while there is no picture
`imageFolder`	`imageFolder`	a list of `{ data, name }`, empty if there are none
`choice`	`text`	the chosen option’s `value`

For an image, data is the picture itself, for an image’s src, and name is its filename without the extension, for an alt or a caption.

Two habits keep a page right:

Set text with textContent, never innerHTML. What the operator types is text and must never become part of your page’s markup.
Change things in place. Every value is sent again when any one changes, so a page that rebuilds itself each time restarts its animation whenever the operator touches an unrelated colour. Set text, CSS custom properties and src directly, and rebuild a list only when that list changed. The starter packages show both.

Your page is sent its values before it is told whether it is on air, so an entrance always knows what it is showing.

Values from a data source

The operator can fill any parameter from a spreadsheet or a feed instead of typing it, as described in Binding data to an overlay. Your page does nothing for this: a value from a data source arrives exactly as a typed one does, with the same kind.

Countdowns, clocks and dates

The operator can type a countdown, a clock, a date or a stopwatch into any text value, such as Live in [countdown to="20:30" format="{mm}:{ss}"], as described in Countdowns, clocks and stopwatches. Your page receives the text already worked out, and receives it again each second while the text holds one. So your handler may run once a second: one more reason to change things in place. Only text parameters are filled in this way; a choice is never changed.