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=true^category=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!
