Component definition
The DX Component Builder generates a config.json file, or component definition file, when you create a component. This file drives the UI authoring experience when you configure the component for use in Pega Platform, meaning that the property pane of the component in Pega Platform is defined by this file.
UI view authoring relies on the information in the component definition to provide a streamlined experience when you edit the view metadata that is consumed at run time.
The component definition consists of header attributes and an array of property definitions. You can modify these attributes and add other attributes when you design your component.
The following example code shows the typical structure of the component definition file of an integer component:
{
"name": "MyCo_MyComponents_MyInteger",
"label": "My Integer",
"description": "My Integer",
"organization": "MyCo",
"version": "01.01.01",
"library": "MyComponents",
"allowedApplications": [],
"componentKey": "MyCo_MyComponents_MyInteger",
"type": "Field",
"subtype": "Integer",
"properties": [
{
"name": "label",
"label": "Field label",
"format": "TEXT",
"required": true
},
{
"name": "readOnly",
"label": "Edit mode",
"format": "READONLY"
},
{
"name": "showGroupSeparators",
"label": "Show thousands separator",
"format": "BOOLEAN",
"visibility": "(!displayAs = slider)"
},
{
"label": "Column settings",
"format": "GROUP",
"visibility": "@VIEWTYPE == 'MultiRecordDisplayAsTable'",
"properties": [
{
"name": "columnWidth",
"label": "Column width",
"format": "SELECT",
"source": [
{
"key": "auto",
"value": "Auto"
},
{
"key": "custom",
"value": "Custom"
}
]
},
{
"name": "width",
"label": "Width (px)",
"format": "NUMBER",
"visibility": "$this.columnWidth == 'custom'"
}
]
},
{
"label": "Input settings",
"format": "GROUP",
"visibility": "(!readOnly = true)",
"properties": [
{
"name": "displayAs",
"label": "Display as",
"format": "SELECT",
"defaultValue": "input",
"source": [
{
"key": "input",
"value": "Input"
},
{
"key": "stepper",
"value": "Stepper"
},
{
"key": "slider",
"value": "Slider"
}
]
},
{
"name": "min",
"label": "Min value",
"format": "NUMBER",
"defaultValue": "0",
"required": true,
"visibility": "(displayAs = slider)"
},
{
"name": "max",
"label": "Max value",
"format": "NUMBER",
"defaultValue": "100",
"required": true,
"visibility": "(displayAs = slider)"
},
{
"name": "defaultValue",
"label": "Default value",
"format": "NUMBER",
"visibility": "(displayAs = slider)"
},
{
"name": "step",
"label": "Increment",
"format": "NUMBER",
"defaultValue": "1",
"min": 1,
"visibility": "(displayAs = slider)"
},
{
"name": "placeholder",
"label": "Placeholder",
"format": "TEXT",
"visibility": "(!displayAs = slider && !displayAs = stepper)"
},
{
"name": "helperText",
"label": "Helper text",
"format": "TEXT"
},
{
"name": "showInput",
"label": "Show numeric input",
"format": "BOOLEAN",
"defaultValue": true,
"visibility": "(displayAs = slider)"
},
{
"name": "showTicks",
"label": "Show ticks",
"format": "BOOLEAN",
"defaultValue": true,
"visibility": "(displayAs = slider)"
}
]
},
{
"label": "Read-only settings",
"format": "GROUP",
"properties": [
{
"format": "SELECT",
"name": "formatter",
"label": "Format",
"defaultValue": "defaultInteger",
"source": [
{
"key": "defaultInteger",
"value": "Default"
},
{
"key": "Decimal",
"value": "Decimal"
},
{
"key": "Currency",
"value": "Currency"
},
{
"key": "Percentage",
"value": "Percentage"
}
]
}
]
},
{
"format": "CASCADE",
"visibility": "(formatter = Currency)",
"source": {
"format": "SELECT",
"label": "ISO Code Selection",
"name": "isoCodeSelection",
"defaultValue": "constant",
"source": [
{
"key": "constant",
"value": "Constant"
},
{
"key": "propertyRef",
"value": "Property Reference"
}
]
},
"cascadeElements": [
{
"key": "currencyISOCode",
"format": "TEXT",
"name": "currencyISOCode",
"label": "Currency ISO Code",
"defaultValue": "USD",
"match": "constant"
},
{
"key": "currencyISOCode",
"format": "PROPERTY",
"name": "currencyISOCode",
"label": "Currency ISO Code",
"match": "propertyRef"
}
]
},
{
"format": "SELECT",
"name": "currencyDisplay",
"label": "Currency display",
"visibility": "(formatter = Currency)",
"defaultValue": "symbol",
"source": [
{
"key": "symbol",
"value": "Auto"
},
{
"key": "code",
"value": "Code"
},
{
"key": "name",
"value": "Name"
}
]
},
{
"format": "SELECT",
"name": "negative",
"label": "Negative number display",
"visibility": "(formatter = Currency)",
"defaultValue": "minus-sign",
"source": [
{
"key": "minus-sign",
"value": "Standard"
},
{
"key": "parentheses",
"value": "Accounting"
}
]
},
{
"format": "SELECT",
"name": "notation",
"label": "Notation",
"visibility": "(!negative = parentheses)&&(!formatter = Percentage)",
"defaultValue": "standard",
"source": [
{
"key": "standard",
"value": "Standard"
},
{
"key": "compact",
"value": "Compact"
}
]
},
{
"name": "decimalPrecision",
"label": "Decimal places",
"format": "NUMBER",
"visibility": "(formatter = Decimal)||(formatter = Percentage)",
"min": 0,
"max": 20
},
{
"format": "SELECT",
"name": "currencyDecimalPrecision",
"label": "Decimal places shown",
"visibility": "(formatter = Currency)",
"defaultValue": "auto",
"source": [
{
"key": "auto",
"value": "Auto"
},
{
"key": "0",
"value": "None"
},
{
"key": "1",
"value": "1"
},
{
"key": "2",
"value": "2"
},
{
"key": "3",
"value": "3"
},
{
"key": "4",
"value": "4"
}
]
},
{
"label": "Conditions",
"format": "GROUP",
"properties": [
{
"name": "required",
"label": "Required",
"format": "REQUIRED",
"visibility": "(!readOnly = true)"
},
{
"name": "disabled",
"label": "Disabled",
"format": "DISABLED",
"visibility": "(!readOnly = true)"
},
{
"name": "visibility",
"label": "Visibility",
"format": "VISIBILITY"
}
]
},
{
"label": "Advanced",
"format": "GROUP",
"collapsible": true,
"properties": [
{
"name": "testId",
"label": "Test ID",
"format": "TEXT",
"ignorePattern": "[^-_\\p{N}\\p{L}]",
"includeAnnotations": false
}
]
}
],
"defaultConfig": {
"label": "@L $this.label"
}
}name- The name of the component. For the field and widget component types, this is for the
metadata child
type. For templates, this is forviewMetada.config.template. label- The name of the component in the UI.
description- A description of the component's intended function and use.
allowedApplications- The applications which can use the components. Leave blank to use in allow all applications to use the component.
componentKey- The identifier associated with the component. By default, this is the same as
name. type- The category of the component, such as Field, Template, or Widget.
subtype- The subcategory of the selected component type. For example, Form, Page, and Details are the available subtypes of the Template component. Subtypes are also used in UI view authoring to control the templates that are displayed in the template picker. Matching subtypes are grouped together as list items.
- In Field components, subtypes are checked against the custom components' subtype, which is created with the DX Component Builder. UI view authoring includes the optional Display as property pane option, which you use to override the run-time display with that of the custom component.
properties- An array of property definitions (objects) that represent the properties that can be
configured for the component. You define the characteristics of a custom component in
this array, such as
name,label,format, andvisibility. - For more information, see Properties.
defaultConfig- An array of objects representing the default state of the component.
Recommended reading
See the following articles to learn more about the component definition file's attributes:
- Properties
The properties attribute in the component definition is an array of objects, each representing a property definition. The property definitions represent the component's configuration through a variety of formats. When authoring UI views, you use these formats to display the configurable options, while also storing the values in the view metadata.
- Formats
Configuration formats determine the type of element defined in the component definition file, and how a field is displayed visually.
- Annotations
You use annotations in component metadata to perform specific operations, such as retrieving case information, running When rules, and retrieving environment information.
- Expressions
You use expressions in the component definition file to control field visibility based on the configuration of another field in the same component. Depending upon the complexity of the expression, you can also build an expression with multiple operators and comparators.
Previous topic Deleting Cosmos DX components Next topic Properties