Building a UI

You can build a custom annotation/evaluation interface in two ways:

  1. Drag-and-Drop UI Form Builder – An interactive canvas for placing components.
  2. UI Form JSON File – A scriptable approach where you upload a JSON file of the form layout and properties.

Either method yields the same result: a structured layout of components that can be dynamically updated and extended with custom code.

Properties

This is the builder that you'll use to create your Multimodal form. The builder is separated into two sections that will help you build and edit your form based on your project's requirements. After creating the project, you may build a custom form from scratch or select from a number of available templates. Building the form involves the use of various UI components and their customized functionality, which can be defined through the Code Editor.

Outline of the UI builder

The UI Builder is divided into three main areas:

  1. Components Panel
    • A library of available UI elements grouped by category (Layout, Button, Input, Select, Media and Custom).
    • You drag these components onto the canvas to add them to your interface.
  2. Canvas
    • The visual workspace where you assemble the user interface.
    • Divided into two main sections:
      • Header: Often used for project titles, instructions, or important project-wide elements.
      • Body: The main area where annotators or reviewers will interact with form components.
  3. Properties Panel
    • Displays the configurable properties for the currently selected component.
    • Here, you set attributes such as component ID, default value, permissions, styling, etc.

General properties

​​There are multiple components available in the UI Builder. Each component on the UI should have its own unique ID that is auto-generated, but can be changed to a more defining value. You should keep in mind that there are a few reserved IDs that can’t be used for any component, and these are: _item_name, _item_category, and _folder.

The rest of the component’s properties are divided into sections: Content, Settings, Permissions, and Format.

Content

You can manage and control the component’s main properties here. This includes its values and composition.

Settings

You can manage and fine-tune a component’s settings to make sure it looks and behaves the way you want. These settings include things like component positioning, sizing, value ranges or limitations, whether or not to exclude it from the export JSON, and whether or not the component is required to be fulfilled before an item is completed.

Permissions

Component permissions



















You can modify the permissions on each individual component (except Grid) so that they can either be Hidden or Read only. You can select one or multiple roles and statuses that this setting is applicable to, including any custom ones available in your project. This can be done when defining the properties of the component.

If there are multiple components that you want to have the same Permissions for, you can copy the settings of one component and paste it onto another. You can do this by clicking the respective buttons to Copy (or Alt + Ctrl + C) the permissions, and Paste (or Alt + Ctrl + V) them.

📘

Component-specific permission settings

  • When setting the permission conditions for the Tab component, you can apply different conditions per tab.
  • You can also define additional permissions for Web components as described here.

Format

Some components will give you the option to format their appearance. This includes background styles, title styles, text direction and button styles.

You can also copy and paste format settings from one component to another:

  1. Hover over the format settings.

  2. Click Copy/Paste formatting and click Copy formatting, or use Ctrl + Shift + C

  3. Click on the component you want to copy these settings to.

  4. Click Copy/Paste formatting and click Paste formatting, or use Ctrl + Shift + V

Version history

Project Admins, Team Admins, and Team Owners can use version history to review changes to a form's JSON and code, edit a draft, and restore an earlier version.

The following labels distinguish the form's states:

  • Published version - The form currently in use.
  • Current version - The working form when it differs from the published version, or from the latest saved version if the form hasn't been published.
  • Draft - Edits made to the JSON or Python code within version history that haven't been applied to the current form.

View and compare versions

  1. In the Form Builder, click Version History in the top bar.
  2. Select the version you want to compare. Use its date and time, version ID, and available author details to identify it.
  3. Click Split to compare versions side by side, or Unified to view the same changes in a single column.
  4. Expand Python Code to review changes by file. Web component code is included in the form JSON.
  5. Use the navigation arrows to move between changes in the form JSON and Python code.

The selected version is compared against your Draft, when one exists; otherwise, it's compared against the version at the top of the list. Renamed Python files appear as a deleted file and an added file.

Version history doesn't refresh automatically if another admin publishes changes while you have it open.

Edit and apply changes

Only the version at the top of the list is editable. Other versions are read-only.

  1. Edit the form JSON or Python code to create a Draft.
  2. Click Apply Changes to load the draft into the Current version. The form JSON must be valid and meet the form's validation requirements.

If the changes can't be applied, the draft remains available to correct or discard.

To discard the draft, click Discard Changes, then Discard. This removes only your draft edits and preserves your existing Form Builder changes. Closing version history and choosing Leave also discards unapplied draft edits.

Undo and redo aren't available for edits made in version history. Discarding a draft or restoring a version can't be undone.Restore a version

You can restore an earlier stored version. You can also restore the Published version when a Current version contains unpublished Form Builder changes. Save any Form Builder changes you want to keep before restoring.

  1. In Version History, hover over the version you want to restore and click Restore.
  2. In the pop-up, click Restore.

The restored form opens in the Form Builder as the Current version.

Save or publish changes

Applying a draft or restoring a version changes only the working form. To store those changes in version history, return to the Form Builder and click Save. To store a new version and make it live, click Publish, or Update for an already-published form.

Import and Export

You can Import or Export in a few ways at any time by clicking their respective buttons in the top-right corner of the form builder.

  • Import: You can import a form JSON file that you've created or exported from a project. You may also import a form Template to start with.
  • Export: You can export a form in JSON format, or as a CSV file for annotations. Saving a form's JSON allows you to reuse the layout and all its components and functionality across other Multimodal projects.
📘

Reusable components

By exporting a form JSON, you may also save frequently used components and their respective python logic to append them to any form without having to recreate them from scratch.

In this case, be sure to select the Add to existing form option when importing.

Status controls

This setting controls whether or not contributors may manually transition an item’s status while working on it in the editor. When disabled, contributors must handle transitions programmatically based on:

  • The transition type and configuration of each status, including validation requirements
  • The configuration of the form’s code.

This feature is Enabled by default, but you can Disable it at any time from the editor’s Settings, accessible via the button in the top-right corner.

Comments panel

This setting controls whether users can leave comments on items or read any that were placed. This is enabled by default. Disabling it will hide all comment panels and prevent users from commenting on items in the editor.

If you disable this feature and there are some items that contain comments, those comments will no longer be visible in the editor or in Explore. Disabling the feature will not delete any of the existing comments, it’ll only hide them. Reenabling the feature later will bring them back.

README

You can create a README file for your project’s form while in the UI builder. This README file will be visible any time this project’s form is opened in the builder and can be accessed from the top-right corner. You can use it to include any important or key bits of information about your project and form.

To create a README file:

  1. Enter the project’s form builder either during project creation or from the project’s settings.
  2. In the top right, click the README button.
  3. Type in all the information you want to include.
  4. When you’re done, click Apply.
  5. Click Next in the top-right corner.
  6. Click Publish (if done during project creation) or Update (if this is an existing project).

To edit a README file:

  1. Enter the project’s form builder from the settings.
  2. In the top right, click the README button.
  3. Click the Edit button.
  4. Make your changes accordingly.
  5. When you’re done, click Apply.
  6. Click Next in the top-right corner.
  7. Click Update.

Did this page help you?