Syntax for Forms public beta

About YAML Syntax

YAML is a human-readable data-serialization language. It is commonly used for configuration files and in applications where data is being stored or transmitted. YAML targets many of the same communications applications as Extensible Markup Language (XML). YAML is a superset of JSON, and YAML files can be parsed as JSON.

Native Inputs

Native inputs are inputs that are already available in the browser source. They are not defined in the form file. These are the native inputs:

Title
Transform
Shadow
Filters (only available for images and videos)
Opacity

Creating Forms For Extensions

In opposite to native inputs, custom inputs are defined in the form file. These allow you to create custom inputs for your extension. Even our internal widgets are using this system. The following example shows how to create a form for a browser source:

Creating forms for browser sources is very easy. We use YAML syntax to define the inputs. The following example shows the syntax for a form with different input types:

Each form must contain a uuid (id) and an array of inputs (inputs). The uuid is used to identify the form in the scene editor which must match with your extension id. The inputs array contains all the inputs that are available in the form.

id: 98f9fab0-0714-46d8-ac77-d57130a1dc88
inputs:
  - type: input
    id: text
    attributes:
      label: Text
      description: This is a description
      value: Hello World
    validations:
      required: true

Limitations

The id of the form must match the id of the extension.
The id of the inputs must be unique and cannot be extension.
The id of the inputs must be an alphanumeric string with a length of 3-32 characters and may contain dashes and underscores.

Fields

Accordion Field

The accordion field can be used to group any number of other fields.

  - type: accordion
    id: my-accordion
    attributes:
      label: My Accordion
    fields:
      - type: boolean
        id: random
        attributes:
          label: Random
          description: This is a description
          value: true
      - type: input
        id: text
        attributes:
          label: Text
          description: This is a description
          value: Hello World
          type: text
        validations:
          required: true
      - ...

The field does not store any values.

Boolean Field

The boolean field may be used to represent a boolean / "on/off" value. The resulting values will be represented as a boolean value.

  - type: boolean
    id: random
    attributes:
      label: Random
      description: This is a description
      value: true

Resulting values:

{
  "values": {
    "random": true
  }
}

Border Radius Field

The border-radius field provides a beautiful input that can be used to select a border radius value. The value is required and must be an object with the following properties: multiple, radius, top-left, top-right, bottom-left & bottom-right. The multiple will allow you to set the border radius for each corner individually. The radius value will be used when multiple is set to false.

  - type: border-radius
    id: border-radius
    attributes:
      label: Border Radius
      value:
        multiple: false
        radius: 0
        top-left: 0
        top-right: 0
        bottom-left: 0
        bottom-right: 0

Resulting values:

{
  "values": {
    "border-radius": {
      "multiple": false,
      "radius": 0,
      "top-left": 0,
      "top-right": 0,
      "bottom-left": 0,
      "bottom-right": 0
    }
  }
}

Button Field

WARNING

The button field is currently not supported in the scene editor.

The button field allows you to create a button that can be used to trigger an action. It will emit an event through the extension IPC module when the button is clicked. There is no value for this field.

  - type: button
    id: button
    attributes:
      label: Button
      value: Click Me

Emitted event:

OWN3D.ext.ipc.on('<ext-id>:inputs:<input-id>:click', (payload) => {
    console.log('Got click event', payload)
})

Checkbox Field

The checkbox field may be used to represent a boolean / "on/off" value. The resulting values will be represented as a array list of options which are checked using the value as their identifier.

  - type: checkbox
    id: checkbox
    attributes:
      label: Checkbox
      description: This is a description
    options:
      - label: Option 1
        value: option-1
        checked: true
        required: true
      - label: Option 2
        value: option-2
        checked: false
        required: false

Resulting values:

{
  "values": {
    "checkbox": [
      "option-1"
    ]
  }
}

Chips Field

The chips field provides a set of chips that can be selected. It behaves exactly like a dropdown field, but with a different UI.

  - type: chips
    id: battery
    attributes:
      label: Battery
      value: full
    options:
      - label: Full
        value: full
        icon: battery-full
      - label: Half
        value: half
        icon: battery-half
      - label: Empty
        value: empty
        icon: battery-empty

Resulting values:

{
  "values": {
    "battery": "full"
  }
}

Color Field

The color field provides a color picker that can be used to select a color. The hex code can be either 6 or 8 characters long. The 8 character hex code will be used for the alpha channel.

If allow-gradient is set, the user can choose between color, linear gradient and radial gradient.

  - type: color
    id: color
    attributes:
      label: Color
      allow-gradient: true
      value: "#ff0000"

Resulting values for hex-color:

{
  "values": {
    "color": "#ff0000"
  }
}

Resulting values for linear-gradient

{
  "values": {
    "color": "linear-gradient(90deg, #FF9602 0%, #ffffff 100%)"
  }
}

Resulting values for radial-gradient

{
  "values": {
    "color": "radial-gradient(circle, #c99144ff 0%, #ffffff 100%)"
  }
}

The dropdown field provides a dropdown menu. The select options may be defined in the options array.

  - type: dropdown
    id: dropdown
    attributes:
      label: Dropdown
      value: 2
    options:
      - label: Option 1
        value: 1
      - label: Option 2
        value: 2
      - label: Option 3
        value: 3

Resulting values:

{
  "values": {
    "dropdown": "2"
  }
}

File Field

The file field allows you to upload a file. The mimeTypes array is required and must contain a list of mime types which are allowed to be uploaded but limited to the following types: mp3, mp4, webm, wav, png, jpg, jpeg and gif. The max file size is 5MB by default.

Multiple files can be uploaded by setting the multiple attribute to true. When multiple is set to true, the value will be an array of file ids & types.

We offer multiple popups for selecting files. The popup attribute can be used to define which popup should be used. If you don't define a popup, the default popup files will be used. The following popups are available:

files - Allows you to select files from your OWN3D media library
gifs - Allows you to select GIFs from Tenor

  - type: file
    id: image
    attributes:
      label: Image
      multiple: false
      mimeTypes:
        - image/*

Resulting values:

{
  "values": {
    "image": {
      "id": "1337",
      "type": "file"
    }
  }
}

How Files Are Stored

When a file is uploaded using this field, OWN3D will store the file for you. The file will be stored in the OWN3D CDN and will be available until the file is deleted. The value of the field will be the file id which can be used to retrieve the file using the File Storage API.

Font Settings Field

The font-settings field provides a multi input field for font settings. It provides a list of fonts that are available in Bunny Fontsopen in new window (the font provider for OWN3D and equivalent to Google Fonts).

  - type: font-settings
    id: font-settings
    attributes:
      label: Font Settings
      value:
        font-color: "#ffffff"
        font-family: Inter
        font-weight: 400
        font-size: 14
        text-align: left
        font-style: normal
        letter-spacing: 0
        line-height: 1.2
        text-indent: 0

Resulting values:

{
  "values": {
    "font-settings": {
      "font-color": "#ffffff",
      "font-family": "Inter",
      "font-weight": 400,
      "font-size": 14,
      "text-align": "left",
      "font-style": "normal",
      "letter-spacing": "normal",
      "line-height": 1.2
    }
  }
}

Group Field

The group field can be used to visually combine other fields into a group.

  - type: group
    id: my-group
    attributes:
      label: My Group
    fields:
      - type: boolean
        id: random
        attributes:
          label: Random
          description: This is a description
          value: true
      - type: input
        id: text
        attributes:
          label: Text
          description: This is a description
          value: Hello World
          type: text
        validations:
          required: true
      - ...

The field does not store any values.

Input Field

The input field provides a simple text input. It can be used for text, numbers, and other types of data. The type attribute can be used to define the type of input. The type attribute is optional and defaults to text.

  - type: input
    id: text
    attributes:
      label: Text
      description: This is a description
      value: Hello World
      type: text
    validations:
      required: true

Resulting values:

{
  "values": {
    "text": "Hello World"
  }
}

Link Field

WARNING

The link field is currently not supported in the scene editor.

The link field allows you to create a link that can be used to navigate to a specific URL. It will open the link in a new tab. There is no value for this field.

  - type: link
    id: link
    attributes:
      label: Link
      value: https://example.com

Platforms Field

The platforms fields allows you to select a single or multiple streaming platform connection. It works like the checkbox field, but with a different UI, and it will automatically fetch the available platforms from the Connections API and pass them to the extension context. The value will be an array of selected platforms. options can be omitted. The selectable values will be the intersection of options (if given) and the platforms that are connected to the user account, including the "own3d" platform.

  - type: platforms
    id: connections
    options:
      - value: twitch
      - value: youtube
      - value: own3d
    attributes:
      label: Platforms
      multiple: false

Resulting values:

{
  "values": {
    "platforms": [
      "twitch",
      "youtube"
    ]
  },
  "context": {
    "connections": [
      {
        "platform": "twitch",
        "channel_id": "1337"
      },
      {
        "platform": "youtube",
        "channel_id": "1337"
      }
    ]
  }
}

Resource Field

Additional resource options may be defined in the options array, like in the dropdown field. When using the multiple option, the value will be an array of selected values.

  - type: resource
    id: alert-set
    attributes:
      label: Alert Set
      description: This is a description
      value: 1337
      multiple: false
      resource:
        resolver: fetch
        endpoint: /v1/alerts-sets
        map:
          label: $.data[*].name
          value: $.data[*].id
    validations:
      required: true

Resulting values:

{
  "values": {
    "alert-set": "1337"
  }
}

Search Field

The search field can be used to group any number of other fields and search through them and all of their ancestors. Searched ancestor fields: label, description, title, value

  - type: search
    id: my-search
    fields:
      - type: boolean
        id: random
        attributes:
          label: Random
          description: This is a description
          value: true
      - type: input
        id: text
        attributes:
          label: Text
          description: This is a description
          value: Hello World
          type: text
        validations:
          required: true
      - ...

The field does not store any values.

Select Field

The select field is intended to summarise all types of selection lists. These include dropdowns, chips and the grid select.

The select field currently only supports the grid style, others will follow.

  - type: select
    id: my-select
    attributes:
      type: grid
      multiple: false | true
      value: [option-1] # This is always an array
    options:
      - label: Option 1 with icon
        value: option-1
        icon: sparkles # Fontawesome Icon
      - label: Option 2 with image
        value: option-2
        image: images/option-2-thumbnail.png # Path to image in the extension

Resulting values:

{
  "values": {
    "my-select": ["option-1"]
  }
}

Slider Field

The slider field provides a beautiful slider that can be used to select a value. The min, max & step values are required.

  - type: slider
    id: age
    attributes:
      label: Age
      value: 18
      min: 13
      max: 99
      step: 1

Resulting values:

{
  "values": {
    "age": 18
  }
}

Tabs Field

The tabs field provides a tab bar with defined tabs to structure and group other fields. Recommended to be used as the top level field. the optional templates field in a tab specified the pre-selected tab when the user selects templates in the configuration menu.

  - type: tabs
    id: my-tabs
    tabs:
      - label: Tab1
        fields:
          - type: boolean
            id: random
            attributes:
              label: Random
              description: This is a description
              value: true
          - ...
      - label: Tab2
        templates: true
        fields:
          - type: input
            id: text
            attributes:
              label: Text
              description: This is a description
              value: Hello World
              type: text
            validations:
              required: true
          - ...

Tags Field

The tags field allow you to freely type in a list of words. This field is useful for adding a list of users, for which may be included or excluded from a feature, for example.

  - type: tags
    id: ignored-users
    attributes:
      label: Ignored Users
      description: The users that will be ignored
      value:
        - user1
        - user2

Resulting values:

{
  "values": {
    "ignored-users": [
      "user1",
      "user2"
    ]
  }
}

Conditional Fields

TIP

Conditional fields require additional review and may delay the review process. Please use them only when necessary and avoid using them for complex logic since they will decrease the performance of the form.

Conditional fields allow you to show or hide fields based on the value of another field. Conditional fields are defined using the if attribute. The if attribute must be a valid JavaScript expression that returns a boolean value, and it can be used either for the field itself or for values in the options array. As of now, only values are available in the context.

The following example shows how to use conditional fields in multiple ways:

  - id: theme
    type: dropdown
    options:
      - label: Default
        value: default
      - label: Legacy
        value: legacy
      - label: Bubbles
        value: bubbles
      - label: Zwietracht
        value: discord
    attributes:
      label: Theme
      value: default
  - id: options
    type: checkbox
    options:
      - label: Test Mode
        value: test-mode
      - if: "['default', 'legacy'].includes(values.theme)"
        label: Show Badges
        value: show-badges
        checked: true
      - if: "['default', 'legacy'].includes(values.theme)"
        label: Show Avatars
        value: show-avatars
      - label: Hide Old Messages
        value: hide-old-messages
      - label: Hide Commands
        value: hide-commands
    attributes:
      label: Options
  - id: message-timeout
    if: values.options['hide-old-messages']
    type: input
    attributes:
      type: number
      label: Message Cleanup
      value: 30
      description: The number of seconds to cleanup
    validations:
      required: true

Receiving Values

Using the API

The values are received using the TBDopen in new window endpoint. The following example shows how data is represented in the API:

{
  "values": {
    "resource": "1337",
    "text": "Hello World",
    "dropdown": 2,
    "checkbox": [
      "code-of-conduct"
    ],
    "font-settings": {
      "font-family": "Impact",
      "font-style": "bold",
      "font-size": 14
    },
    "ignored-users": [
      "user1",
      "user2"
    ],
    "image": {
      "id": "98f9fd85-0832-44fa-87d1-e24d9741f632",
      "type": "file"
    }
  }
}

Using the Extension Helper

The values are received using the Extension Helper method OWN3D.ext.onContext(...). The following example shows how to receive the values from the form:

OWN3D.ext.onContext((context, changed) => {
    // context['inputs'] contains the current inputs (TBC)
    // context['values'] contains the values from the form
});

Demo-Mode

Add has_demo_mode: true to the manifest.yaml. This will add a "Demo-Mode"-Box to the Settings in the Scene-Builder.

id: 98f9fab0-0714-46d8-ac77-d57130a1dc88
inputs:
  [...]
has_demo_mode: true

Changing the toggle, the Supervisor gets an update:

OWN3D.ext.onContext((context, changed) => {
  // changed => ['demo_mode']
  // context['demo_mode'] => true|false
});

# Syntax for Forms public beta

# About YAML Syntax

# Native Inputs

# Creating Forms For Extensions

# Limitations

# Fields

# Accordion Field

# Boolean Field

# Border Radius Field

# Button Field

# Checkbox Field

# Chips Field

# Color Field

# Dropdown Field

# File Field

# How Files Are Stored

# Font Settings Field

# Group Field

# Input Field

# Link Field

# Platforms Field

# Resource Field

# Search Field

# Select Field

# Slider Field

# Tabs Field

# Tags Field

# Conditional Fields

# Receiving Values

# Using the API

# Using the Extension Helper

# Demo-Mode

Syntax for Forms public beta

About YAML Syntax

Native Inputs

Creating Forms For Extensions

Limitations

Fields

Accordion Field

Boolean Field

Border Radius Field

Button Field

Checkbox Field

Chips Field

Color Field

Dropdown Field

File Field

How Files Are Stored

Font Settings Field

Group Field

Input Field

Link Field

Platforms Field

Resource Field

Search Field

Select Field

Slider Field

Tabs Field

Tags Field

Conditional Fields

Receiving Values

Using the API

Using the Extension Helper

Demo-Mode