CDML Reference

In general, all tags in CDML are enclosed by <* and *>. Attributes within these tags then determine the styles of the text following the tags, within the same block. If you want to include <* in text without being interpreted as CDML tags, use <<* as an escape sequence.

Font Styles

You can change the style of the label text by using CDML tags. For example, the line:

<*font=timesi.ttf,size=16,color=FF0000*>Hello <*font=arial.ttf,size=12,color=8000*>world! in an chart's Label Title attribute will result in the following text being rendered:

The following table describes the supported font style attributes in CDML:

CDML Attribute	Description
font	Specifies the start of a new style section, and sets the font name. You may use this attribute without a value (that is, use "font" instead of "font=arial.ttf") to create a new style section without modifying the font name. Use </font> to terminate a style section, which will restore the original font styles.
size	Specifies the font size.
width	Specifies the font width. This attribute is used to set the font width to different values. If the width and height are the same, use the size attribute.
height	Specifies the font height. This attribute is used to set the font height to different values. If the width and height are the same, use the size attribute.
color	Specifies the font color, in hex format, e.g. 000000.
bgColor	Specifies the font background color, in hex format, e.g. 000000.
underline	Specifies the line width of the line used to underline the following characters. Set to 0 to disable underline.
sub	Specifies the following text as subscript.
super	Specifies the following text as superscript.
xoffset	Specifies a horizontal offset, in pixels, for the following text to be drawn from the original position.
yoffset	Specifies a vertical offset, in pixels, for the following text to be drawn from the original position.

Unlike HTML tags, no double or single quotes are used within CDML tags. This is because CDML tags are often embedded as string literals in the parent page code and quotes, if used, may conflict with other string literal quotes. Therefore, quotes must not be used within CDML tags. Also, unlike HTML tags, CDML tags use the comma character (,) as a delimiter between multiple tag attributes. This is because certain attributes, such as a font file name, may contain embedded spaces.

Blocks and Lines

In CDML, a text string may contain multiple blocks. A block may contain multiple lines of text by separating them with the <*br*> tag. For example, the line:

<*size=15*><*block*><*color=FF*>BLOCK<*br*>ONE<*/*> and <*block*><*color=FF00*>BLOCK<*br*>TWO<*/*> in a chart's Label Title attribute will result in the following text being rendered:

The example above uses a line of text that contains two blocks separated by the word and. Each block in turn contains two lines. The blocks are defined using <*block*> as the starting tag and <*/*> as the ending tag.

When a block ends, font styles will be restored to the state they were in before entering the block.

Block Attributes

CDML supports nested blocks; that is, a block can contain other sub-blocks. Attributes are supported within the <*block*> tag to control the alignment and orientation of the sub-blocks. The following table describes the supported attributes inside a <*block*> tag:

Block Attribute	Description
angle	Specifies the angle of rotation for the block, in degrees of counter-clockwise rotation.
bgColor	Specifies the block background color, in hex format, e.g. 000000.
halign	Specifies the horizontal alignment of lines. This is for blocks that contain multiple lines. Supported values are left, center and right. The default value left means the left border of each line should align with the left border of the block. The value center means the horizontal center of each line should align with the horizontal center of the block. The value right means the right border of each line should align with the right border of the block.
height	Specifies the height of the block, in pixels. By default, the height is automatically determined to be the height necessary for the contents of the block. If the height attribute is specified, it will be used as the height of the block.
linespacing	Specifies the spacing between lines as a multiple of the default line spacing. For example, a line spacing of 2 means the line spacing is two times the default line spacing. The default line spacing is the line spacing as specified by the font used.
maxwidth	Specifies the maximum width of the block in pixels. If the content is wider than maximum width, it will be wrapped into multiple lines.
truncate	Specifies the maximum number of lines of the block. If the content requires more than the maximum number of lines, it will be truncated. In particular, if truncate is 1, the content will be truncated if it exceeds the maximum width (as specified by maxwidth or width) without wrapping. The last few characters at the truncation point will be replaced with "...".
valign	Specifies the vertical alignment of sub-blocks. This is for blocks that contain sub-blocks. Supported values are baseline, top, middle, absmiddle, and bottom The value baseline means the baseline of sub-blocks should align with the baseline of the block. The baseline is the underline position of text. This is normal method of aligning text, and is the default in CDML. For blocks that are rotated, the baseline is the same as the bottom. The value top means the top line of sub-blocks should align with the top line of the block. The value bottom means the bottom line of sub-blocks should align with the bottom line of the block. The value middle means the middle line of sub-blocks should align with the middle line of the block. The middle line is the middle position between the top line and the baseline. The value absmiddle means the absolute middle line of sub-blocks should align with the absolute middle line of the block. The absolute middle line is the middle position between the top line and the bottom line.
width	Specifies the width of the block in pixels. By default, the width is automatically determined to be the width necessary for the contents of the block. If the width attribute is specified, it will be used as the width of the block. If the width is insufficient for the contents, the contents will be wrapped into multiple lines.