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
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

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

Deprecation warning

This field is deprecated starting on 15.05.2024. Please use the select field with style chip.

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 value must be a valid hex color code. The hex code can be either 6 or 8 characters long. The 8 character hex code will be used for the alpha channel.

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

Resulting values:

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

Divider

The divider field displays a horizontal line and provides no other functionaliy.

  - type: divider
    id: divider

Deprecation warning

This field is deprecated starting on 15.05.2024. Please use the select field with style dropdown.

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
    }
  }
}

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"
  }
}

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
  }
}

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"
    ]
  }
}

Select Field

The select field allow you to create a select input. We offer three different styles: select, chips and dropdown. You can select multiple values by setting the multiple attribute to true. If you add group to the options and having style select, the options will be grouped by the group name. If you choose select as style, you can also define the number of columns to display the options in the select dropout.

  - type: select
    id: style
    attributes:
      label: Select a style
      description: Choose a style
      style: select # select, chips, dropdown
      columns: 1 # 1-2 (default 1)
      multiple: true
      value:
        - option-1
        - option-3
    options:
      - label: Option 1
        group: Modern styles
        value: option-1
        media: https://example.com/image.png
      - label: Option 1
        group: Modern styles
        value: option-1
        media: https://example.com/image.png
      - label: Option 3
        group: Flat styles
        value: option-3
        media: https://example.com/image.png

Resulting values:

{
  "values": {
    "style": [
      "option-1",
      "option-3"
    ]
  }
}

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
});

# Syntax for Forms public beta

# About YAML Syntax

# Native Inputs

# Creating Forms For Extensions

# Limitations

# Fields

# Boolean Field

# Border Radius Field

# Button Field

# Checkbox Field

# Chips Field

# Deprecation warning

# Color Field

# Divider

# Dropdown Field

# Deprecation warning

# File Field

# How Files Are Stored

# Font Settings Field

# Input Field

# Link Field

# Platforms Field

# Resource Field

# Slider Field

# Tags Field

# Select Field

# Conditional Fields

# Receiving Values

# Using the API

# Using the Extension Helper

Syntax for Forms public beta

About YAML Syntax

Native Inputs

Creating Forms For Extensions

Limitations

Fields

Boolean Field

Border Radius Field

Button Field

Checkbox Field

Chips Field

Deprecation warning

Color Field

Divider

Dropdown Field

Deprecation warning

File Field

How Files Are Stored

Font Settings Field

Input Field

Link Field

Platforms Field

Resource Field

Slider Field

Tags Field

Select Field

Conditional Fields

Receiving Values

Using the API

Using the Extension Helper