Custom UI templates

Edit online

You can display your data in different ways in the UI when you create a card. Use custom templates to customize the appearance of cards by passing template-specific properties. The template specific properties are consumed by the custom view parser, which renders the correct template.

Include custom template with card definition

Various sections of a card can benefit from custom templates, such as the card header, footer, and table cell. Instead of using the label property to set plain text, you can use the customTemplate property to use any of the following templates. You need to pass a specific set of properties for each template.

An example of customTemplate usage:

"devConfigurations": [
  {
    "name": "item[8].customTemplate",
    "values": ["dateTpl"],
    "metaInformation": "gridOption"
  }
]

Include custom template with subscription overrides

If you want a tenant-level override for a card definition that requires the use of a custom template, then it's important to note that both the customTemplate and the original attribute value must be included. For example, to override the formatting of column 11, include the following properties in subscriptionConfig:


 {
            "name": "columns[11].cell.customTemplate",
            "value": "dateTpl"
        },
                {
            "name": "columns[11].cell.label",
            "value": "{{ updateReceived }}"
        }

Instead of the following properties:

        {
            "name": "columns[11].cell.customTemplate",
            "value": "dateTpl"
        }

The custom template formatter requires both the type of template and data to apply it to.

Available custom templates

textTpl
Usage
This template is used by default, if the customTemplate property isn't passed.
Expected properties
label: set plain text

letterCase:

  • UPPER: sets text to uppercase.
  • LOWER: sets text to lowercase.
"devConfigurations": [
  {
    "name": "item[8].label",
    "values": ["displaying text"],
    "metaInformation": "gridOption"
  },
  {
    "name": "item[8].letterCase",
    "values": ["UPPER"],
    "metaInformation": "gridOption"
  }
]
currencyTpl
Usage
Displays currency values.
"devConfigurations": [
  {
    "name": "item[8].customTemplate",
    "values": ["currencyTpl"],
    "metaInformation": "gridOption"
  }
]
Expected properties
label: set plain text

currencyCode: The ISO 4217 three-letter currency code, for example, USD orCAD. The default currencyCode is set to USD.

"devConfigurations": [
  {
    "name": "item[8].label",
    "values": ["123456.88"],
    "metaInformation": "gridOption"
  },
  {
    "name": "item[8].currencyCode",
    "values": ["CAD"],
    "metaInformation": "gridOption"
  }
]
dateTpl
Usage
Displays dates by using specific formats to display date and time.
"devConfigurations": [
  {
    "name": "item[8].customTemplate",
    "values": ["dateTpl"],
    "metaInformation": "gridOption"
  }
]
Expected properties
label: set plain text

dateFormat: string-formatted date object that includes both date and time. For more information, see date and time format > options. If not provided, the formatter uses the default value { year: 'numeric', month: 'numeric', day: 'numeric' }. For example, January 2nd, 2022 is en-US: "1/2/2022", en-GB: "02/01/2022", de-DE: "2.1.2022", ko: "2022. 1. 2.", and so on).

localizeTime: render the date in terms of the current user's time zone.

"devConfigurations": [
  {
    "name": "item[8].label",
    "values": ["2017-07-20T00:00:00.000+00:00"],
    "metaInformation": "gridOption"
  },
  {
    "name": "item[8].dateFormat",
    "values": [
      "{\"year\":\"numeric\",\"month\":\"long\",\"day\":\"numeric\",\"hour\":\"numeric\",\"minute\":\"numeric\"}"
    ],
    "metaInformation": "gridOption"
  },
  {as
    "name": "item[8].localizeTime",
    "values": ["true"],
    "metaInformation": "gridOption"
  }
]
numberTpl
Usage
Displays number values.
"devConfigurations": [
  {
    "name": "item[8].customTemplate",
    "values": ["numberTpl"],
    "metaInformation": "gridOption"
  }
]
Expected properties
label: set plain text

numberFormat: string-formatted number format object. For more information, see the relevant section of number format -> options. The following code shows the default format:

{
  minimumIntegerDigits: 1, // The minimum number of integer digits before the decimal point.
  minimumFractionDigits: 0, // The minimum number of digits after the decimal point.
  maximumFractionDigits: 2 // The maximum number of digits after the decimal point.
}

quantityUnit: set number of quantity units of a value. The value of this option must be the field in the GraphQL that gives the quantity a unit.

maxNumberBeforeNull: any number greater than the label renders as --. For example, if maxNumberBeforeNull === 999, then a value of 100 renders as it is, but a value of 1000 or greater renders as --.

"devConfigurations": [
  {
    "name": "item[8].label",
    "values": ["15234.8799"],
    "metaInformation": "gridOption"
  },
  {
    "name": "item[8].numberFormat",
    "values": [
      "{\"minimumIntegerDigits\":1,\"minimumFractionDigits\":0,\"maximumFractionDigits\":3}"
    ],
    "metaInformation": "gridOption"
  },
  {
    "name": "item[8].quantityUnit",
    "values": ["itemUnit"],
    "metaInformation": "gridOption"
  }
]
percentTpl
Usage
Display percent values.
"devConfigurations": [
  {
    "name": "item[0].customTemplate",
    "values": ["percentTpl"],
    "metaInformation": "gridOption"
  }
]
Expected properties
label: set plain text

numberFormat: string-formatted number object. For more information, see the relevant section of number format>options. The following code shows the default format:

{
  minimumIntegerDigits: 1, // The minimum number of integer digits before the decimal point.
  minimumFractionDigits: 0, // The minimum number of digits after the decimal point.
  maximumFractionDigits: 0 // The maximum number of digits after the decimal point.
}
"devConfigurations": [
  {
    "name": "item[0].customTemplate",
    "values": ["percentTpl"],
    "metaInformation": "gridOption"
  },
  {
    "name": "item[0].label",
    "values": [“0.25”],
    "metaInformation": "gridOption"
  },
  {
    "name": "item[0].numberFormat",
    "values": [
      "{\"minimumIntegerDigits\":1,\"minimumFractionDigits\":0,\"maximumFractionDigits\":1}"
    ],
    "metaInformation": "gridOption"
  }
]
linkTpl
Usage
Create a clickable field or link.
"devConfigurations": [
  {
    "name": "item[8].customTemplate",
    "values": ["linkTpl"],
    "metaInformation": "gridOption"
  }
]
Expected properties
label: set plain text
href.type: specifies where to take the user on click. The following values are accepted for this property:
  • LAYOUT
  • LAYOUT_TEMPLATE.
  • CUI_SHELL
  • NEW_WINDOW

href.id: ID of the layout or layout template that is loaded on click.

href.params: any parameters that must be passed from the current view to the next one. You might pass multiple parameters that are separated by a comma. If param value is undefined, null, or empty, then by default the type of label is textTpl.

href.labelType: by default the type of label is textTpl, but you might choose to change it to any of the following supported types:

  • textTpl
  • currencyTpl
  • dateTpl
  • numberTpl

href.labelOptions: based on href.labelType property, you can pass extra properties to format the data. The following values are supported:

  • letterCase : can be used when href.labelType = textTpl
  • currencyCode: can be used when href.labelType = currencyTpl
  • dateFormat: can be used when href.labelType = dateTpl
  • numberFormat: can be used when href.labelType = numberTpl
  • quantityUnit: can be used when href.labelType = numberTpl

href.path:

  • Can be used when href.type == CUI_SHELL. This property configures the path to any other app under the CUI Shell navigation. For example, if the user clicks a SKU ID link within ICT, clicking takes the user to IV, then href.path is set to /inventory-hub/inventory/sku
  • Can be used when href.type == NEW_WINDOW . This property configures the path to an external URL outside of the CUI shell. The path must be specified with http://` as part of the URL in order for the external URL to open in a new window correctly. 
"devConfigurations": [
  {
    "name": "widget.footer.label",
    "values": ["View details"],
    "metaInformation": "widgetOption"
  },
  {
    "name": "widget.footer.href.type",
    "values": ["LAYOUT_TEMPLATE"],
    "metaInformation": "widgetOption"
  },
  {
    "name": "widget.footer.href.id",
    "values": ["DRILLDOWN_TEMPLATE"],
    "metaInformation": "widgetOption"
  },
  {
    "name": "widget.footer.href.params",
    "values": ["product={{ productId }}, order={{ orderId }}"],
    "metaInformation": "widgetOption"
  },
  {
    "name": "widget.footer.href.labelType",
    "values": ["textTpl"],
    "metaInformation": "widgetOption"
  },
  {
    "name": "widget.footer.href.letterCase",
    "values": ["UPPER"],
    "metaInformation": "widgetOption"
  },
  {
    "name": "columns[0].dataMapping",
    "values": [
      "product.partNumber"
    ],
    "metaInformation": "tableColumn"
  },
  {
    "name": "columns[0].label",
    "values": [
      "SKU ID"
    ],
    "metaInformation": "tableColumn"
  },
  {
    "name": "columns[0].customTemplate",
    "values": [
      "linkTpl"
    ],
    "metaInformation": "tableColumn"
  },
  {
    "name": "columns[0].href.type",
    "values": [
      "CUI_SHELL"
    ],
    "metaInformation": "tableColumn"
  },
  {
    "name": "columns[0].href.path",
    "values": [
      "/inventory-hub/inventory/sku"
    ],
    "metaInformation": "tableColumn"
  },
  {
    "name": "columns[0].href.params",
    "values": [
      "productId={{ product.partNumber }},UOM={{ quantityUnits }},productClass={{ class }},nodes={{ location.locationIdentifier }}"
    ],
    "metaInformation": "tableColumn"
  }
]
multilinkTpl
Usage
To create multiple clickable fields or links.
"devConfigurations": [
  {
    "name": "item[8].customTemplate",
    "values": ["multiLinkTpl"],
    "metaInformation": "tableColumn"
  }
]
Expected properties
multiLink: All link properties must be passed into this array. The following values are accepted for this array:
href.type: specifies where to take the user on click. The following values are accepted for this property:
  • LAYOUT
  • LAYOUT_TEMPLATE.
  • CUI_SHELL
  • NEW_WINDOW

href.id: ID of the layout or layout template that is loaded on click.

href.params: any parameters that must be passed from the current view to the next one. You might pass multiple parameters that are separated by a comma. If param value is undefined, null, or empty, then by default the type of label is textTpl.

"devConfigurations": [
  {
    "name": "columns[0].dataMapping",
    "values": [
      "partNumber"
    ],
    "metaInformation": "tableColumn",
    "sensitive": false,
    "readonly": false,
    "required": false
  },
  {
    "name": "columns[0].label",
    "values": [
      "Part number"
    ],
    "metaInformation": "tableColumn",
    "sensitive": false,
    "readonly": false,
    "required": false
  },
  {
    "name": "columns[0].sortable",
    "values": [
      "true"
    ],
    "metaInformation": "tableColumn",
    "sensitive": false,
    "readonly": false,
    "required": false
  },
  {
    "name": "columns[0].customTemplate",
    "values": [
      "multiLinkTpl"
    ],
    "metaInformation": "tableColumn",
    "sensitive": false,
    "readonly": false,
    "required": false
  },
  {
    "name": "columns[0].multiLink[0].href.type",
    "values": [
      "LAYOUT_TEMPLATE"
    ],
    "metaInformation": "tableColumn"
  },
  {
    "name": "columns[0].multiLink[0].href.id",
    "values": [
      "BTO_DEFAULT_PARTS_SHORT_DETAIL_LAYOUT_TEMPLATE"
    ],
    "metaInformation": "tableColumn"
  },
  {
    "name": "columns[0].multiLink[0].href.params",
    "values": [
      "selectedPartNumber={{partNumber}},selectedProductId={{id}}"
    ],
    "metaInformation": "tableColumn"
  },
  {
    "name": "columns[0].multiLink[1].href.type",
    "values": [
      "LAYOUT_TEMPLATE"
    ],
    "metaInformation": "tableColumn"
  },
  {
    "name": "columns[0].multiLink[1].href.id",
    "values": [
      "BTO_DEFAULT_PARTS_SHORT_DETAIL_LAYOUT_TEMPLATE"
    ],
    "metaInformation": "tableColumn"
  },
  {
    "name": "columns[0].multiLink[1].href.params",
    "values": [
      "selectedPartNumber={{partNumber}},selectedProductId={{id}}"
    ],
    "metaInformation": "tableColumn"
  },
  {
    "name": "columns[0].hidden",
    "values": [
      "false"
    ],
    "metaInformation": "tableColumn",
    "sensitive": false,
    "readonly": false,
    "required": false
  },
  {
    "name": "columns[0].sequence",
    "values": [
      "0"
    ],
    "metaInformation": "tableColumn",
    "sensitive": false,
    "readonly": false,
    "required": false
  }
]
iconTpl
Usage
To display icons.
"devConfigurations": [
  {
    "name": "item[8].customTemplate",
    "values": ["iconTpl"],
    "metaInformation": "gridOption"
  }
]
Expected properties
label: set plain text

size: set icon size. Possible values are sm (16px), md (20px), lg (24px), xlg (32px)

icon: set icon type, for example, arrow--right

ID: Optional. When using an icon in a data table, for example, it might be necessary to set a unique ID in order to distinguish which icon events are sent from.

"devConfigurations": [
  {
    "name": "item[8].label",
    "values": ["Next page"],
    "metaInformation": "gridOption"
  },
  {
    "name": "item[8].icon",
    "values": ["arrow--right"],
    "metaInformation": "gridOption"
  },
  {
    "name": "item[8].size",
    "values": ["sm"],
    "metaInformation": "gridOption"
  },
  {
    "name": "item[8].id",
    "values": ["abc-123"],
    "metaInformation": "gridOption"
  }
]

For a full list of Carbon icons, see Carbon Design System.

priorityTpl
Usage
Display a colored priority dot mark followed by the priority number.
Expected properties
label: priority level 
"devConfigurations": [
  {
    "name": "item[8].label",
    "values": ["100"],
    "metaInformation": "gridOption"
  }
]
assigneeTpl
Usage
The assigneeTpl template takes as input an IUI value and returns a string value that depends on whether the input IUI matches the current logged-in user's IUI. If they match, the template outputs {{firstName}} {{lastName}} of the current logged-in user. If they do not match, the output is Member. If the input IUI to the template is not present, the default value is Unassigned.
Expected properties
label: set plain text. An IUI string value.

userToken: The current logged-in user's token. You do not need to know this value. In the widget definition, you can specify {{token}}, and the string interpolation feeds in the correct value, because the token is part of the exposed state.

See the following template example:

"devConfigurations": [
  {
    "name": "columns[5].cell.label",
    "values": ["samsmith@ibm.com"],
    "metaInformation": "tableColumn"
  },
  {
    "name": "columns[5].cell.userToken",
    "values": ["{{token}}"],
    "metaInformation": "tableColumn"
  }
]
customTemplateKey and customTemplateOptions
Usage
  • Select a template and its set of properties.
  • The set of properties that are used is based on the value of customTemplateKey.
  • You can use any of the preceding templates.
  • You can use different templates only if each set has the correct properties.
Expected properties
"devConfigurations": [
  {
    "name": "item[8].customTemplateKey",
    "values": ["{{ Key 1 or Key 2 or Key 3 }}"],
    "metaInformation": "gridOption"
  },
  {
    "name": "item[8].customTemplateOptions[0].key",
    "values": ["Key 1"],
    "metaInformation": "gridOption"
  },
  {
    "name": "item[8].customTemplateOptions[0].customTemplate",
    "values": ["priorityTpl"],
    "metaInformation": "gridOption"
  },
  {
    "name": "item[8].label",
    "values": ["100"],
    "metaInformation": "gridOption"
  },
  {
    "name": "item[8].customTemplateOptions[0].key",
    "values": ["Key 2"],
    "metaInformation": "gridOption"
  },
  {
    "name": "item[8].customTemplateOptions[0].customTemplate",
    "values": ["priorityTpl"],
    "metaInformation": "gridOption"
  },
  {
    "name": "item[8].label",
    "values": ["200"],
    "metaInformation": "gridOption"
  },
  {
    "name": "item[8].customTemplateOptions[0].key",
    "values": ["Key 3"],
    "metaInformation": "gridOption"
  },
  {
    "name": "item[8].customTemplateOptions[0].customTemplate",
    "values": ["iconTpl"],
    "metaInformation": "gridOption"
  },
  {
    "name": "item[8].label",
    "values": ["Next page"],
    "metaInformation": "gridOption"
  },
  {
    "name": "item[8].icon",
    "values": ["arrow--right"],
    "metaInformation": "gridOption"
  },
  {
    "name": "item[8].size",
    "values": ["sm"],
    "metaInformation": "gridOption"
  },
  {
    "name": "item[8].id",
    "values": ["abc-123"],
    "metaInformation": "gridOption"
  }
]