Creating Custom Formatters in CDL

CDL provides various formatters to customize widget properties like color, date, number, text and more. Each formatter has unique settings for customization.

You can create and specify a formatter using CDL manually. To do this, create it in the report configuration block, then you can refer to it later in the report when you want to designate specific properties, appearances, or actions for specific parts of a widget. It's likely that you will need multiple versions of a specific type of formatter, such as to set different number layouts in various columns in a widget or to set different colors on different parts of a widget. Therefore, each formatter of a specific type must have a unique name in the report.

To learn more, visit: About Formatters

Color Formatter

This formatter sets the threshold values that determine when the colors used in dials and graphs in the widgets will change, and it also defines the color to be used for each range of values.

 formatter color #fmtKPIColor {
    thresholds: #82D854 >= 100%, #FFBD5B >= 70%, #FA5263 < 70%
  }
  formatter color #colorFormatter {
    thresholds: #5ba35d >= 75, #ffa156 >= 60, #dd3435  >= 0
  }

To establish the thresholds, you begin with the highest threshold and designate the color to be used when values are greater than or equal to that threshold. Then, you proceed to the second-highest threshold and specify the color to be used when values are greater than or equal to that threshold but less than the highest threshold. Repeat this process for each threshold, listing all the required thresholds and corresponding colors, with each threshold separated by a comma.

In the first example shown above, in a widget where "scorecolor1" is applied, data values greater than 4 will be colored with code #7ED251, values less than 4 but greater than 2 will be colored with code #F0AD4E, and values between 2 and 1 will be colored with code #FA5263.

For details of the properties and settings, refer to formatter in the CDL Reference Guide.

Date Formatter

The Date formatter converts an ISO_8601 date into a readable form. If the date string is invalid, either because it is not in ISO_8601 format or is empty, and the "emptyValue" property is not defined, it will display "Invalid date." To customize the output when the value is empty, specify a value for the "emptyValue" property.

 formatter date #weekFormat {
    inputFormat: "WW"
    formatString: "DD MMM YYYY"
  }
  formatter date #monthFormat {
    inputFormat: "M"
    formatString: "MMM YYYY"
  }
  formatter date #quarterFormat {
    inputFormat: "YYYYQQ"
    formatString: "\QQ"
  }

Note

The formatString property overrides the shortForm property.

For information on properties and settings, refer to the "formatter" section in the CDL Reference Guide.

Number Formatter

Use the Number formatter to determine how numeric values are displayed.

formatter number #percentNumber {
    numberDecimals: 1
    decimalSeparator: "."
    postfix: "%"
    prefix: ""
  }
  formatter number #numberFormat {
    numberDecimals: 0
    decimalSeparator: "."
    integerSeparator: ","
    prefix: ""
    shortForm: true
  }
  formatter number #nodecimal {
    numberDecimals: 0
    integerSeparator: ","
  }

The Number formatter will not encounter errors with text strings. If the value is an empty string, the formatter will default to the value specified in "emptyValue" (if present) or a formatted zero integer. If the value is not an empty string, the formatter will display the string as is. This behavior occurs when expressions with "IIF" are used in table queries and return strings.

Note

Note To display an empty cell, use the string: emptyValue: ' '

For details of the properties and settings, refer to formatter in the CDL Reference Guide.

Text Formatter

The Text formatter determines how texts are displayed. You can, for example, set it to truncate text after a specified number of characters with the "length" property, and include the ellipses character "..." after the truncation point if "useDots" is set to true. If the text is an empty string, you can specify what to display in the field by providing a value for the "emptyValue" property.

formatter text myTextFormat{
   emptyValue: "-"
   length: 25
   useDots: true
 }

In the code example, if a text string exceeds 25 characters, it will be truncated and the excess replaced with the ellipses character "...". If the field is blank, a "-" character will be displayed.

For details of the properties and settings, refer to formatter in the CDL Reference Guide.

Value Formatter

This is a default value formatter that performs no transformation to the value. When the value is null or undefined ("", null, undefined, or 0 in the case of the number formatter), it will return the string specified in the emptyValue property.

formatter value emptyvalue {
  emptyValue: " "
  }

For details of the properties and settings, refer to formatter in the CDL Reference Guide.