Text Options

TextOptions are part of the style system. They allow for complete control over how text is rendered in a report. For any component in a report, TextOptions can be defined as a single object or as an array of objects. If provided as an array, the first object in the array with a condition that resolves to true (or without a condition) will be applied to the text. Any other object in the array is ignored.

TextOptions Schema

key	type	required	description
fontName	string	optional	The font to use for the text. Default value is arial.
weight	string	optional	The weight of the font. Valid values are thin, extraLight, light, normal, medium, semiBold, bold, extraBold, black, extraBlack, italic, underline, subscript, superscript, and strikeThrough. If a font does not support the requested weight, the closest available weight will be used. Some options can be combined, e.g. 'bold underline'. Default is normal.
fontColor	string	optional	The color to use when rendering the text. Default value is black. Colors can be well-defined color names, or RGB values (e.g. "#1E3D7A").
backgroundColor	string	optional	The color to use for the text background. Default value is #00000000 or transparent. Colors can be well-defined color names, or RGB values (e.g. "#1E3D7A").
fontSize	float	optional	The size of the text to display, in pixels.
lineHeight	float	optional	Specifies the spacing between lines of text.
letterSpacing	float	optional	Allows for control over the spacing between characters. The default value, 0, is the normal spacing defined by the font. Specify a negative number to decrease spacing, and a positive number to increase spacing. The amount of spacing added/removed is relative to the fontSize.
alignment	string	optional	The text alignment to use within the component. Valid values are left, right and center. Default is left.
vAlignment	string	optional	The vertical text alignment to use within the component. Valid values are top, bottom and middle. Default is middle.
format	TextFormat	optional	String formatting to apply to the text.
mask	TextMask	optional	String masking to apply to the text.
fallbackFont	TextOptions	optional	The font family to use if the primary font is unable to render a glyph.
condition	Conditional	optional	If present, the textOptions specified will be applied only if the condition evaluates to true.

Text Formatting

Text formatting can be applied to text in a report. For example, the number 123456.78 can be formatted as currency and rendered in the report as $123,456.78. String formatting can be applied to integers, floating-point values, dates, and times. If a value that is to be formatted is defined in a report as a string, it will first be converted to the type specified. If the type conversion fails, a warning will be generated and report rendering will continue by displaying an unformatted string. The reporting engine is hard-coded to use the 'EN-US' culture when formatting strings. If a different culture is required, a custom engine will need to be built.

TextFormat Schema

key	type	required	description
type	string	required	The type of value the text represents. Can be one of: float, double, int, long, date, or time.
formatString	string	required	A formatting string to apply to the text. A wide variety of formatting options are available. See numeric formatting and date/time formatting for detailed information.

Examples

Notice that in some cases, formatting a value can result in rounding. Be careful when using this feature if number precision is important for your report.

Float Formatting

Description	Format String	Result
Original Value	none	1234.567890
3 decimal places	'N3'	1,234.568
As currency	'C2'	$1,234.57
As percentage	'p2'	123,456.79%

Integer Formatting

Description	Format String	Result
Original Value	none	12345
Comma separators	'N0'	12,345
Commas and 2 decimals	'N2'	12,345.00
As Thousands	'#,##0,K'	12K

Date Formatting

Description	Format String	Result
Original Value	none	11/21/1982
Long format	'D'	Sunday, November 21, 1982
Month/Day format	'M'	November 21
Year/Month format	'Y'	November 1982

Text Masking

Text masking can be applied to text in a report. Masking is useful when PII or other sensitive data is included in a data file, but should not be output in a report. For example, a customers' account number or social security number can be masked to show only the last 4 digits.

TextMask Schema

key	type	required	description
pattern	string	required	A RegEx pattern that will be used to mask the string. Any match will be replaced by the string defined in replacement.
replacement	string	required	The replacement string to use for the mask.

Examples

The following mask can be used to hide the first 12 characters of a 16 digit account number.

"textOptions": {
    "mask": {
        "pattern": "^.{12}",
        "replacement": "XXXXXXXXXXXX"
    }
}

Input:

1234567890123456

Output:

XXXXXXXXXXXX3456