Template syntax | Format Strings

<< Click to display table of contents >>

Template syntax | Format Strings

Format strings can be used in:

data fields

variables

cross-tab header fields

functions

expressions

They are optional.

Format strings are different for different types of data. The following types of data have their own formats of format strings:

floating point values

integer values

boolean values

date and time

text strings

documents (RVF and RTF)

images

Note 1: a report generator treats '}' as a termination of the field code. To insert '}' in a format string, use '}}'.

Note 2: a format string is enclosed in double quotes; however, a format string can include double quote characters itself; you do not need to escape them.

Format strings for floating point values

Format strings for floating point values are the same as for FormatFloat() function from SysUtils unit, extended by optional colors and optional parameters section.

To allow different formats for positive, negative, and zero values, the format string can contain between one and three sections separated by semicolons.

One section: The format string applies to all values.

Two sections: The first section applies to positive values and zeros, and the second section applies to negative values.

Three sections: The first section applies to positive values, the second applies to negative values, and the third applies to zeros.  

If the section for negative values or the section for zero values is empty, that is if there is nothing between the semicolons that delimit the section, the section for positive values is used instead. For formatting purposes, sections contained only colors are treated as empty.

Each section may start from a color definition inside []. See the "color definition" chapter below. This means that the format string in this section cannot start from [ (you can include it in single or double quotes, though).

A format string may start from a parameters section. It has format [fmt<decimal separator>[<thousands separator>]].

<decimal separator> and <thousands separator> are characters used as decimal and thousands separators. If a parameters section is omitted, locale default characters are used. You should specify decimal separator explicitly if this field is used in expressions; for example, SQL requires the dot character as a decimal separator.

Example:

"0.00;[red]-0.00" – displays two digits after the decimal point, negative values are displayed red

"select price * {discount "[fmt.]"} from mytable" – the result uses dot as a decimal separator

Format strings for integer values

Format strings for integer values consist of up to three sections.

The first section represents positive values and defines the number format.

The second section represents negative values

The third section represents zero values.

Format strings for integer values have the following format:

<Int format string> ::= [[<color+>]][<number format>][;[<color->][;[<color0>]]]

<number format> ::= decimal<min length> | roman | ROMAN | alpha | ALPHA | hex<min length> | HEX<min length>

<number format> is case sensitive.

number format

example

decimal

roman

ROMAN

alpha

ALPHA

hex

HEX

greek

1, 2, 3, ..., 10, 11, 12

i, ii, iii

I, II, III

a, b, c, ..., aa, ab, ac

A, B, C, ..., AA, AB, AC

1, 2, 3, ..., a, b, c

1, 2, 3, ..., A, B, C

α, β, γ, ..., αα, αβ, αγ

<min length> is a positive integer number, it specifies the minimal number of digits in the output string; if necessary, '0's are added to the resulting text.

<color+> (if specified) defines the color for positive values.

<color-> (if specified) defines the color for negative values (otherwise, <color+> is used)

<color0> (if specified) defines the color for zero (otherwise, <color+> is used)

Example:

decimal[blue][red][black]
sample output: -10, 0, 5

hex4
sample output: 0000, 001a, -00ff

alpha
sample output: a, w, 0, -8

Format strings for boolean values

Format strings for boolean values consist of two sections separated by a semicolon. The first section specifies how to represent True, the second section specifies how to represent False. Each section may contain a color and a text.

Format strings for boolean values have the following format:

<Bool format string> ::= [[<colorT>]]<textT>[;[[<colorF>]]<textF>]

<colorT> (if specified) defines the color for True, see the "color definition" below.

<colorF> (if specified) defines the color for False; if not specified, <colorT> is used for False.

<textT> (if specified) is a text for True; if empty, Texts.TrueText is used.

<textF> (if specified) is a text for False; if empty, Texts.FalseText is used.

Examples:

"yes;no"
sample output: no yes

"[green]on;[red]off"
sample output: off on

Format strings for dates and times

Format strings for date and time values are the same as for FormatDateTime() function from SysUtils unit.

Example:

"d/m/y"

Format strings for strings

Format strings for string values are the same as for FormatMaskText() function from MaskUtils unit.

However, FormatMaskText() always uses space characters for missing characters and ignores a blank character specified in the format string.

Report Workshop uses the blank characters specified in the mask, or DefaultBlank global variable (from MaskUtils unit) if omitted. By default, DefaultBlank = '_'.

Example:

"(000)000-0000;0; " – displays a phone number
sample output: (123)456-7890

Format strings for documents

This type of format strings is used when displaying RVF, RTF, and DocX fields.

The format string is a combination of the following values, separated by spaces: fontname, fontsize, color, backcolor.

The corresponding properties of text of the inserted document are ignored, i.e. properties of the font of the field code are used instead.

Item in the format string

Related property of TFontInfo

Comments

fontname

FontName

This option is not applied to text items having Charset=SYMBOL_CHARSET

fontsize

SizeDouble

This option is also applied to Font.Size of list markers

color

Color

This option is not applied to hyperlinks

backcolor

BackColor

 

Example:

"fontsize fontname" – ignores font size and name in inserted documents, uses these properties from a report template instead.

Format strings for images

This type of format strings is used when displaying images.

The format string is a combination of properties, separated by spaces. Each property has the form:

<property name>=<property value>

<property name> is one of:  padding, borderwidth, vspace, hspace, bordercolor, align, width, height, minwidth, minheight, maxwidth, maxheight.

Property name

Related item property

(TRVExtraItemProperty)

Meaning

Value type

padding

rvepSpacing

Spacing around the picture, inside its border. If a background color is defined, this area is colored

integer (in pixels)

vspace

rvepOuterVSpacing

Spacing above and below the border

integer (in pixels)

hspace

rvepOuterHSpacing

Spacing to the left and to the right of the border

integer (in pixels)

bordercolor

rvepBorderColor

Border color

color (see the "color definition" chapter)

borderwidth

rvepBorderWidth

Border width

integer (in pixels)

width

rvepImageWidth

The image is stretched to the specified width

integer (in pixels)

height

rvepImageHeight

The image is stretched to the specified height

integer (in pixels)

align

rvepVAlign

Vertical image alignment in a line, or alignment to the left/right side

one of: baseline, middle, abstop, absbottom, absmiddle, left, right

Note: a background color is not available as a property. It is taken from the background color of text of the field code.

The following properties allow stretching the image: width, height, minwidth, minheight, maxwidth, maxheight. If the properties contradict to each other, width and height have the highest priority, minwidth and minheight have a middle priority, maxwidth and maxheight have the lowest priority.

If both width and height are defined, min* and max* properties are ignored.

If one of width/height is defined, the other side is stretched proportionally, constrained to the corresponding min* and max* properties.

If none of width/height is defined, the image is stretched proportionally, according to min* and max* properties.

Example:

"borderwidth=2 bordercolor=orange maxwidth=500"

Color definition

In certain places of format strings, users can specify colors.

Color codes are similar to HTML: you can define either a color name, or #RRGGBB code.

Color name is one of:

aliceblue, antiquewhite, aqua, aquamarine, azure, beige, bisque, black, blanchedalmond, blue, blueviolet, brown, burlywood, cadetblue, chartreuse, chocolate, coral, cornflowerblue, cornsilk, crimson, cyan, darkblue, darkcyan, darkgoldenrod, darkgray, darkgreen, darkkhaki, darkmagenta, darkolivegreen, darkorange, darkorchid, darkred, darksalmon, darkseagreen, darkslateblue, darkslategray, darkturquoise, darkviolet, deeppink, deepskyblue, dimgray, dodgerblue, firebrick, floralwhite, forestgreen, fuchsia, gainsboro, ghostwhite, gold, goldenrod, gray, green, greenyellow, honeydew, hotpink, indianred, indigo, ivory, khaki, lavender, lavenderblush, lawngreen, lemonchiffon, lightblue, lightcoral, lightcyan, lightgoldenrodyellow, lightgreen, lightgrey, lightpink, lightsalmon, lightseagreen, lightskyblue, lightslategray, lightsteelblue, lightyellow, lime, limegreen, linen, magenta, maroon, mediumaquamarine, mediumblue, mediumorchid, mediumpurple, mediumseagreen, mediumpurple, mediumslateblue, mediumspringgreen, mediumturquoise, mediumvioletred, midnightblue, mintcream, mistyrose, moccasin, navajowhite, navy, oldlace, olive, olivedrab, orange, orangered, orchid, palegoldenrod, palegreen, paleturquoise, palevioletred, papayawhip, peachpuff, peru, pink, plum, powderblue, purple, red, rosybrown, royalblue, saddlebrown, salmon, sandybrown, seagreen, seashell, sienna, silver, skyblue, slateblue, slategray, snow, springgreen, steelblue, tan, teal, thistle, tomato, turquoise, violet, wheat, white, whitesmoke, yellow, yellowgreen.

Color codes are case-insensitive.

Examples:

floating point value format string: "0.00;[red]-0.00"

image format string: "borderwidth=2 bordercolor=#ff0000"