# UiSchema

The PANDIUM.yaml's UISchema is a list of elements that determine how the configurations defined in the schema properties are displayed on the connection settings page e.g. the order of controls, their visibility, labels, and layout.

All UISchema elements must contain the type prop. Depending on that type other props may be available/required. Pandium currently supports the following types of UISchema elements:

### Control

A UISchema element with `type: Control` displays one of the configurations defined in the schema properties.

In addition to type, it takes these properties:

| prop        | values                                                                                                              | note                                                                                                                                                                  |
| ----------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **scope**   | [JSON schema reference value](https://spacetelescope.github.io/understanding-json-schema/structuring.html#reuse%22) | <p>Required.</p><p>Determines which schema property this UISchema element displays. </p><p>Has the following format <code>‘#/properties/\[property\_name]’</code></p> |
| **label**   | string                                                                                                              | <p>Not Required.</p><p>Used to customize the text seen for the control on the connections settings page.</p><p><br></p>                                               |
| **admin**   | boolean                                                                                                             | <p>Not Required.</p><p>When true, the element will only render for Integration Hub users.</p><p><br></p>                                                              |
| **options** | object                                                                                                              | <p>Not required. For full-width inputs, use  <br><code>options:</code><br>    <code>trim: false</code></p>                                                            |
|             |                                                                                                                     |                                                                                                                                                                       |

If the schema properties look like this:

```yaml
schema:
  type: object
  properties:
    bool_input:
      type: boolean
      default: true
```

Then, the UISchema element for the bool\_input property could look like this:

```yaml
type: Control
label: A Boolean Input
scope: "#/properties/bool_input"
```

It would then be displayed in the connection settings page like this:

!["A Boolean Input" is defined by the label property in the UISchema](https://4017407078-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MfJn-9R_dn6dvcGNcdk%2F-Mi2w3UK1Udgnshdd442%2F-Mi8QVRjXOjtg1WheaTQ%2FScreen%20Shot%202021-08-27%20at%204.53.05%20PM.png?alt=media\&token=4cdce604-df78-4e65-b447-dd536a6f6763)

### MultiSelectControl

A UISchema element with `type: MultiSelectControl` displays one of the configurations defined in the schema properties. This type will only render correctly if the Schema property referenced in its scope is formatted as a multi select enum.

In addition to type, it takes these properties:

| prop      | values                                                                                                              | note                                                                                                                                                                                                                                                                                     |
| --------- | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **scope** | [JSON schema reference value](https://spacetelescope.github.io/understanding-json-schema/structuring.html#reuse%22) | <p>Required for Control.</p><p>Determines which schema property this uischema element displays. </p><p>Has the following format <code>‘#/properties/\[property\_name]’</code></p><p>The schema property referenced in its scope must be formatted as a multi select enum.</p><p><br></p> |
| **admin** | boolean                                                                                                             | Not Required. When true, the element will only render for Integration Hub users.                                                                                                                                                                                                         |
|           |                                                                                                                     |                                                                                                                                                                                                                                                                                          |

If the schema property looks like this:

```yaml
string_enum_multi_input:
  items:
    options:
      - label: Option 1 label
        value: option1
      - label: Option 2 label
        value: option2
      - label: Option 2 label
        value: option2
```

Then, the UISchema element for the string\_enum\_multi\_input property coudl look like this:

```yaml
- type: MultiSelectControl
  scope: "#/properties/string_enum_multi_input"
```

Which would then be displayed like this on the connections page:

<figure><img src="https://4017407078-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfJn-9R_dn6dvcGNcdk%2Fuploads%2FEG1o9PL7hAiFVU0oXmEI%2FOption%201%20label.png?alt=media&#x26;token=8ec596f5-bda9-4ce3-8e9e-170f00ee84cb" alt=""><figcaption><p>MultiSelectControl UISchema Element</p></figcaption></figure>

### Label

A UISchema element with type: Label displays a label.  This can be helpful when combined with UISchema elements that do not take the label prop (e.g. the MultiSelectControl)

In addition to type, it takes these properties:

| prop         | value   | note                                                                             |
| ------------ | ------- | -------------------------------------------------------------------------------- |
| **title**    | string  | Not Required.                                                                    |
| **subtitle** | string  | Not Required.                                                                    |
| **hintText** | string  | Not Required.                                                                    |
| **admin**    | boolean | Not Required. When true, the element will only render for Integration Hub users. |

Here is an example of a UISchema element with type: label

```yaml
- type: Label
  subtitle: Select Appropriate Options
  hintText: This is the hintText for the label element
  title: Multi Select Control
```

Which would be displayed like this on the connection settings page:

<figure><img src="https://4017407078-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfJn-9R_dn6dvcGNcdk%2Fuploads%2FtDoxisatyQEOHUBg6iS1%2FMulti%20Select%20Control%20%C2%AE.png?alt=media&#x26;token=1e9351df-3dc7-4c47-97e6-5713945f0abc" alt=""><figcaption><p>Label UISchema element</p></figcaption></figure>

### Divider

A UISchema element with type: Divider displays a horizontal line.  This can help visually organize and separate different sections of the connections setting page.  This type of UISchema element does not take any additional properties.

Here is an example of UISchema element with type: Label

```yaml
- type: Divider
```

It would be displayed as a simple dividing line in the connection settings page.

### Vertical Layout

A UISchema element with type: VerticalLayout is used to list other UISchema elements vertically. Layout elements (i.e. VerticalLayout, HorizontalLayout, Section) can be combined and nested within one another.

In addition to type, it takes these properties:

| prop        | value                     | note      |
| ----------- | ------------------------- | --------- |
| **element** | List of UISchema elements | Required. |

Here is an example of UISchema element with type: Vertical Layout:

```yaml
type: VerticalLayout
elements:
- type: Control
  label: Name
  scope: "#/properties/name"
- type: Control
  label: Birth Date
  scope: "#/properties/birthDate"
```

Which would be displayed like so:

![Elements displayed vertically in the UI](https://4017407078-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MfJn-9R_dn6dvcGNcdk%2F-Mi8Rd-tt-t1r9QDXOkr%2F-MiMMqUunrRNKtiAPDAi%2FScreen%20Shot%202021-08-30%20at%2010.03.22%20AM.png?alt=media\&token=e129e0b8-6d8f-4ad2-81a5-4aab47fc6ff3)

### Horizontal Layout

A UISchema element with type: HorizontalLayout is used to list other UISchema elements side by side. Layout elements (i.e. VerticalLayout, HorizontalLayout, Section) can be combined and nested within one another.

In addition to type, it takes these properties:

| prop        | value                     | note      |
| ----------- | ------------------------- | --------- |
| **element** | List of UISchema elements | Required. |

Here is an example of UISchema element with type: HorizontalLayout:

```yaml
type: HorizontalLayout
elements:
- type: Control
  label: Name
  scope: "#/properties/name"
- type: Control
  label: Birth Date
  scope: "#/properties/birthDate"
```

In addition to type, it takes these properties:

![Elements displayed horizontally in the UI](https://4017407078-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MfJn-9R_dn6dvcGNcdk%2F-Mi8Rd-tt-t1r9QDXOkr%2F-MiMNDIXp7b76Eemlb0v%2FScreen%20Shot%202021-08-30%20at%2010.04.58%20AM.png?alt=media\&token=21c49f4d-9389-4411-8a6b-91403579c702)

### Section

A UISchema element with type: Section is used to list other UISchema elements vertically. It differs from the VerticalLayout because it can take more props (e.g. label, subtitle, hintText). Layout elements (i.e. VerticalLayout, HorizontalLayout, Section) can be combined and nested within one another.

In addition to type, it takes these properties:

| prop         | value                     | note          |
| ------------ | ------------------------- | ------------- |
| **element**  | List of UISchema elements | Required.     |
| **label**    | string                    | Not required. |
| **subtitle** | string                    | Not required. |
| **hintText** | string                    | Not required. |

Here is an example of UISchema element with type: Section:

```yaml
type: Section
label: My Group
type: Section
  label: First Section
  elements:
  - type: Control
    label: Name
    scope: "#/properties/name"
    options:
      trim: true
  - type: Control
    label: Birth Date
    scope: "#/properties/birthDate"
    options:
      trim: true
  hintText: This is the hint text of the first section.
  subtitle: This is the subtitle of the first section.
```

It would be displayed like this on the connections settings page:

<figure><img src="https://4017407078-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MfJn-9R_dn6dvcGNcdk%2Fuploads%2FbjOg8oGAUz09tWUCBrQU%2FC53xaM-li4lFryQvAq6IHd4PVmP9gXNfqmbisKr3NRzUs1bN2vgHgti-LPAQu_73Lq-QaGK4Jgmsw4AVHW2CtnCsou160gJzwlMbL9OSIwV1NuRE17GQmNxqvzJE.png?alt=media&#x26;token=d98295a2-fa65-4bbc-ab3f-9c44fb7c21a2" alt=""><figcaption><p>Elements displayed in a Section UISchema Element</p></figcaption></figure>

### File Input

A UISchema element with type: File Input is used to provide users (both Admins and customer end-users) with the ability to import a CSV file.

Here is an example of UISchema element with type: File Upload:

```yaml
type: FileInput
label: File Upload
scope: "#/properties/file_upload"
```

### Combining Layout Elements

UISchema elements of the type VerticalLayout, HorizontalLayout, and Section can be combined and nested within one another as in this example:

```yaml
---
type: VerticalLayout
elements:
- type: Section
  label: First Section
  elements:
  - type: Control
    label: Name
    scope: "#/properties/name"
    options:
      trim: true
  - type: Control
    label: Birth Date
    scope: "#/properties/birthDate"
    options:
      trim: true
  hintText: This is the hint text of the first section.
  subtitle: This is the subtitle of the first section.
- type: Divider
- type: Section
  label: Second Section
  elements:
  - type: Control
    label: Option One
    scope: "#/properties/option1"
  - type: Control
    label: Option Two
    scope: "#/properties/option2"
  hintText: Note the horizontal line between the two section. You can add this to your
    own coniguration form by including a 'Divider' element.
  subtitle: The second section contains two boolean fields.
```

![Two sections in a vertical layout, seperated by a divider](https://user-images.githubusercontent.com/49411879/137545293-00ef9312-2268-4297-9d38-9296d96f0d31.png)