|
<< Click to display table of contents >> Template syntax | Format Strings |
Format strings can be used in:
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, RTF, DocX, HTML, Markdown)
•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.
Note 3: empty (NULL) values are not inserted in text, regardless format strings
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 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> | greek
<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 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 date and time values are the same as for FormatDateTime() function from SysUtils unit.
Example:
•"d/m/y"
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
This type of format strings is used when displaying RVF, RTF, DocX, HTML, Markdown 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.
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"
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"