Property description
The widget property marks a component as a widget usable on the home screen. A component with this property is listed in the widget catalog, where users pick it and place it on their home screen.
Available for the following component types: api-chart, chart, summaries, api-table, wordcloud, panel, section-title, static-text.
Minimal JSON
{
"titleKey": "",
"category": ""
}{
"titleKey": "widget.title.objects_by_state",
"descriptionKey": "widget.desc.objects_by_state",
"category": "overview",
"defaultWidth": 12,
"defaultHeight": 4,
"minWidth": 6,
"minHeight": 3,
"editableFilters": [
{
"key": "workflowStateKey",
"editor": "workflow-state",
"valueKind": "enumKey"
}
]
}For the surrounding component, see the widget example in components.
Nested properties
| Property | Description | Values | Mandatory |
|---|---|---|---|
titleKey | Translation key of the title. Define the key in translations to specify how the text is displayed in the UI. Unlike the name property, if you use a specific string of text for the title, this text will appear with the package key. For example, Comment Section will be displayed as package_key_comment section. | string | Yes |
category | Section of the widget catalog that lists the widget. Supported values are my_work, overview, assets, adoption, scope. | string | Yes |
defaultHeight | Height in grid rows the widget gets when a user places it. Supported values are 1 and above, and the value can’t be smaller than minHeight. | integer | No |
defaultWidth | Width in grid columns the widget gets when a user places it. Supported values are 1 to 24, and the value can’t be smaller than minWidth. | integer | No |
descriptionKey | Translation key of the widget description shown in the catalog. Define the key in translations. | string | No |
editableFilters | Array of filters a user can change on a placed widget. Each entry connects a filter key in the component’s template to the editor the user picks the value in. For configuration, see Editable filters. | array | No |
iconKey | Key of the icon used to visually represent the asset. Use predefined icons from Settings > Configuration > Icons, or define custom ones in the icons asset. | string | No |
minHeight | Smallest height in grid rows a user can resize the widget to. Supported values are 1 and above. | integer | No |
minWidth | Smallest width in grid columns a user can resize the widget to. Supported values are 1 to 24. | integer | No |
For default and minimum size behavior, inheritance, and grid dimensions, see Widget size on the home screen grid.
Editable filters
The editableFilters array lets a user change part of a placed widget’s data selection without editing the package.
| Property | Description | Values | Mandatory |
|---|---|---|---|
key | Filter key inside the component’s template that this editor drives. | string | Yes |
editor | Editor the user picks the value in. See the table below. | string* | Yes |
valueKind | Format of the value written into the filter. Supported values are id for numeric identifiers and enumKey for enum keys. Default is id. | string | No |
*Supported editor values
| Value | The user picks |
|---|---|
application | An application. |
object-type | An object type. |
relation-type | A relation type. |
space | A space. |
table-columns | Table columns. |
time-range | A time range. |
user-relation-type | A user relation type. |
workflow-state | A workflow state. |
Widget size on the home screen grid
The home screen grid is 24 columns wide, which is why defaultWidth and minWidth accept values from 1 to 24. Height is measured in grid rows and has no upper limit.
Omit a size property to inherit the value of the component type:
| Component type | Default width × height | Minimum width × height |
|---|---|---|
panel, section-title, static-text | 6 × 3 | 4 × 3 |
summaries | 8 × 4 | 6 × 3 |
api-chart, chart, wordcloud | 8 × 5 | 6 × 4 |
api-table | 12 × 6 | 8 × 6 |
Component types that are not in the table inherit the panel values.
A minimum you set yourself also raises the inherited default. For example, minWidth: 10 on a summaries widget with no defaultWidth produces a default width of 10 instead of 8.