Component and Data Resource Properties in UI Builder

You are viewing content included in the Next Experience Center of Excellence

In UI Builder you can drag and drop components and data resources onto a page, but then how do you configure them? Since components and data resources are encapsulated, the mechanism for passing data to them is to use their properties, which are basically their inputs. You can read more about the theory around properties and how they're used in the framework in the Component Properties page.

For this article, I'm going to focus on listing all of the property types and their schema in case you need to add properties to your custom components or data resources. Since they do share the same property definitions going to look at existing data resources' properties is a good idea if you want to find some examples.

Good practices when creating properties:

Use sentence-casing for all property labels
Sentence case capitalizes only the first letter of the first word in a phrase, except for proper nouns.
Use positive verbs for Boolean properties
Check if the labels use positive verbs such as "show", "set", "use" and "turn on", instead of "disable", "hide", etc. Use "turn on" or "activate" in place of "enable."
When possible, avoid using a JSON property
Although a JSON property is flexible, breaking up the JSON property into multiple properties can increase usability.
Use tooltips to provide further information
Rather than simply repeating the label text, explain why and how to configure the property.

Property types

UI Builder currently supports 14 configuration property types.

Boolean

type : "boolean"
value: true | false

Choice

type: "choice"
value: The value from one of the available choices contained in the typeMeta object
typeMetadata:
- variant: Enum of dropdown (Default), radio-group or button-group <-- Determines the selection UX in UIB
- choices: Array
  - label: Human-readable label to be shown in the choice list option
  - value: Raw value which should be used to update a choice property

Condition

type: "condition_string"
value: Encoded query string. Example: "active=truecategory=1"
typeMetadata:
- table: Table for which a condition field should be constructed, such as "incident"
- emptyStateBehavior: the value to default to when the field is empty, which must be one of these explicit values "NULL|UNDEFINED|EMPTY_STRING|EMPTY_OBJ|EMPTY_ARRAY". The default empty state value is ''.

Reference

type: "reference"
value: sys ID of record in the table defined in typeMeta | ""
typeMetadata
- reference: Table name (e.g. incident)
- emptyStateBehavior: the value to default to when the field is empty, which must be one of these explicit values "NULL|UNDEFINED|EMPTY_STRING|EMPTY_OBJ|EMPTY_ARRAY". The default empty state value is ''.

Field

type: "field"
value: name of a field (like active or short_description)
typeMetadata
- table: Table from which a field should be picked. Can be a static table name (like "incident"), or a reference to another property on this component (like "@tableProperty")
- emptyStateBehavior: the value to default to when the field is empty, which must be one of these explicit values "NULL|UNDEFINED|EMPTY_STRING|EMPTY_OBJ|EMPTY_ARRAY". The default empty state value is ''.

Field List

type: "field_list"
value: comma-separated list of field names ("active,short_description")
typeMetadata
- table: Table from which a field should be picked. Can be a static table name (like "incident"), or a reference to another property on this component (like "@tableProperty")
- emptyStateBehavior: the value to default to when the field is empty, which must be one of these explicit values "NULL|UNDEFINED|EMPTY_STRING|EMPTY_OBJ|EMPTY_ARRAY". The default empty state value is ''.

HTML

type: "html"
value: String HTML content
typeMetadata
- emptyStateBehavior: the value to default to when the field is empty, which must be one of these explicit values "NULL|UNDEFINED|EMPTY_STRING|EMPTY_OBJ|EMPTY_ARRAY". The default empty state value is ''.

String

type: "string"
value: Any String value, or an empty string
typeMetadata
- emptyStateBehavior: the value to default to when the field is empty, which must be one of these explicit values "NULL|UNDEFINED|EMPTY_STRING|EMPTY_OBJ|EMPTY_ARRAY". The default empty state value is ''.

Table

type: "table_name"
value: Table name (e.g. "incident") | ""
typeMetadata
- emptyStateBehavior: the value to default to when the field is empty, which must be one of these explicit values "NULL|UNDEFINED|EMPTY_STRING|EMPTY_OBJ|EMPTY_ARRAY". The default empty state value is ''.

JSON

type: "json"
value: String JSON content
typeMetadata
- emptyStateBehavior: the value to default to when the field is empty, which must be one of these explicit values "NULL|UNDEFINED|EMPTY_STRING|EMPTY_OBJ|EMPTY_ARRAY". The default empty state value is null.

Number

type: "number"
value: Any number value, or null
typeMetadata
- emptyStateBehavior: the value to default to when the field is empty, which must be one of these explicit values "NULL|UNDEFINED|EMPTY_STRING|EMPTY_OBJ|EMPTY_ARRAY". The default empty state value is null.

CSS

type: "css"
value: A string of CSS
typeMetadata
- emptyStateBehavior: the value to default to when the field is empty, which must be one of these explicit values "NULL|UNDEFINED|EMPTY_STRING|EMPTY_OBJ|EMPTY_ARRAY". The default empty state value is ''.

URL

type: "url"
value: string (should be valid URL)
typeMetadata
- emptyStateBehavior: the value to default to when the field is empty, which must be one of these explicit values "NULL|UNDEFINED|EMPTY_STRING|EMPTY_OBJ|EMPTY_ARRAY". The default empty state value is ''.

Icon

type: "icon"
value: A string representing the name of the desired now-icon

Example

As a quick example, here are some of the properties from the GlideRecord Collection Query GrapQL data resource available by default. You'll notice in addition to showing how many of the above properties work in practice, most of the property types have a typeMetadata that allows for extra configuration.

One of the interesting parts is the use of the @ symbol to reference another property value. You can see that the Conditions property is referencing the value of the Table property right above it.

[
    {
        "name": "table",
        "label": "Table",
        "description": "Table to look up",
        "readOnly": false,
        "fieldType": "table_name",
        "mandatory": true,
        "defaultValue": ""
    },
    {
        "name": "encodedQuery",
        "label": "Conditions",
        "description": "Look up search conditions",
        "readOnly": false,
        "fieldType": "condition_string",
        "mandatory": false,
        "defaultValue": "",
        "typeMetadata": {
            "table": "@table"
        }
    },
    {
        "name": "returnFields",
        "label": "Return fields",
        "description": "Returned field values",
        "readOnly": false,
        "fieldType": "field_list",
        "mandatory": false,
        "typeMetadata": {
            "table": "@table"
        }
    },
    {
        "name": "orderBy",
        "label": "Order by",
        "description": "Field to sort rows by",
        "readOnly": false,
        "fieldType": "field",
        "mandatory": false,
        "typeMetadata": {
            "table": "@table"
        }
    },
    {
        "name": "sortType",
        "label": "Sort type (asc/desc)",
        "description": "Sort type",
        "readOnly": false,
        "fieldType": "string",
        "mandatory": false,
        "defaultValue": "asc",
        "typeMetadata": {
            "choices": [
                {
                    "label": "a to z",
                    "value": "asc"
                },
                {
                    "label": "z to a",
                    "value": "desc"
                }
            ]
        }
    },
    {
        "name": "limit",
        "label": "Max results",
        "description": "Maximum results returned",
        "readOnly": false,
        "fieldType": "string",
        "mandatory": false,
        "defaultValue": "1000"
    },
    {
        "name": "offset",
        "label": "Pagination offset",
        "description": "Pagination offset",
        "readOnly": false,
        "fieldType": "string",
        "mandatory": false
    },
    {
        "name": "returnFieldMetadata",
        "label": "Return field metadata",
        "description": "Return field metadata",
        "readOnly": false,
        "fieldType": "boolean",
        "mandatory": false,
        "defaultValue": false
    }
]

Want to see more enablement and examples for another part of UI Builder? Let me know in the comments!

Labels: