Communication without complication

Introduction

The most flexible way to create text-based pages for use in CODA, or to mix text and images, is by writing a description of them in CML - the CODA Markup Language. CML resembles a very simple HTML, and is easy to write by hand or to generate as the output of some other system. You can create a CML file with any text editor, save it on your web server and add it into CODA as a new CML page simply by specifying the URL.

If you're making modifications to a CML page, it's useful to have its page on the CODA website handy - you can use the 'Assign to display' link on the right hand side as a quick way to check those updates on your display. Another way to learn about CML is to experiment with CMLedit.

This page documents the CML tags and gives some notes on their usage. It's also worth keeping an eye on the CML Hints and tips page.

NOTE: CML is quite strict XML. All attributes must be in quotes. All text must use xml escape characters for symbols such as & both in plain text and in attributes (that includes image URLs). Numbers should be integers unless indicated otherwise.

CML Tags

coda

description:

This top-level tag contains the entire document. The version attribute specifies which version of CML is being used. The current version is '0.1'.

attributes:

• version - Version number. Should be '0.1'

example:

<coda version="0.1">
  <p>Hello, world!</p>
</coda>

div

description:

A div is a box containing rendering elements. There is an initial div created for the entire document for free, which fills the screen and has a foreground colour of white, and no background colour. Divs will generally follow after each other down the screen, but divs placed with a specific x position and/or y position are outside that flow.

The textual content of a div will be constrained to within the width allowing for the specified margins.

attributes:

• xpos - Horizontal position from left of screen (or right if negative). Either in pixels or as a percentage of the outer div size. The default is 0.
• ypos - Vertical position from top of screen (or bottom if negative). Either in pixels or as a percentage of the outer div size. The default is 0.
• width - Width of the div box, either in pixels or as a percentage of the outer div size. The default is 100%.
• height - Height of the div box, either in pixels or as a percentage of the outer div size. The default is 100%
• margin - Offset of div content from the edge of the div, specified in pixels. The default value is 20.
• background - Background colour of the div box, either as a colour name (e.g., red, yellow, blue) or as web colour (e.g., #ff0000, #00ff00, #0000ff). If not specified the div has a transparent background.
• foreground - Foreground colour of the div box, either as a colour name (e.g., red, yellow, blue) or as web colour (e.g., #ff0000, #00ff00, #0000ff). The default is white.
• backgroundOpacity - A number between 0 and 1 inclusive indicating how opaque the background colour of the div should be. The default is 1.0.
• cornerRadius - A value in pixels allowing you to create rectangles with rounded corners. The default is 0.
• backgroundGradientColors - (experimental) A pair of colours which will be used to form a background gradient from top to bottom. They should be comma-separated values in square brackets. (e.g. [#11DD11, #116611]). This feature may change over time - we recommend also specifying a background colour as a fallback - but it can be used to produce more visually-interesting displays.

examples:

<div xpos='50%' width='50%' background='#800080' foreground='white'>
  <p>Hello, world!</p>
</div>

<div margin="0" xpos="10" ypos="10" width="80" height="80" 
     background="green"  backgroundGradientColors="[#30ff30, #308030]"
     backgroundOpacity="0.9" cornerRadius="10" >
</div>

p

description:

All textual content to be displayed for the reader must be contained in a paragraph tag. The contents of the paragraph may only contain Pango style text formatting tags (such as span, i, b, etc.) or a line break tag (br). Nothing else is valid - this is not HTML!

White space is ignored. If you want to insert any meaningful white space then use the br tag.

attributes:

• align - Sets the text alignment of the paragraph. Valid options are left, right, center, or centre, with the default being left.

example:

<p align='center'>Hello</p>

hr

description:

Draws a horizontal rule across the current div.

attributes:

example:

<hr />

img

description:

The image tag will place an image within a div at the current flow point. Supported image formats include PNG, JPEG, BMP, GIF, and SVG. Note that if you set only one of width or height for an image then the other axis will be scaled automatically to preserve the proportions. This also means the scaling attribute is useless unless you specify both width and height.

attributes:

• src - a URL specifying the source of the image.
• width - Width of the image box, either in pixels or as a percentage of the outer div size. The default is the natural image width.
• height - Height of the image box, either in pixels or as a percentage of the outer div size. The default is the natural image height.
• scaling - How to scale the image in the width/height box if it's not a natural ratio of the normal image size. Can be one of FIT, STRETCH, CROP, or NONE. The default is STRETCH.

example:

<img src="http://coda.camvine.com/codasmall.png" width="20%" height="20%" scaling="FIT"/>

Note that default widths and heights are those of the image referenced, and are not necessarily those of any enclosing div. An image may overflow its enclosure, and width="100%" may therefore reduce an image's size.

span

description:

To change the formatting of a span of text, use this tag. The span tag is rendered by the Pango library. Full documentation of it can be found here. Both the span tag and the convenience functions will work.

attributes:

See pango reference

example:

<p>This is some <span size='large'>Big</span> and <span size='small'>small</span> test.</p>

br

description:

This tag inserts a line break into a paragraph. It should only ever occur within a paragraph.

attributes:

example:

<p>This is on one line...<br />This is on another!</p>

date

description:

This tag inserts a formatted date string into a paragraph. It should only ever occur within a paragraph. The time and date is generated by the CODAbox controlling the screen, and will take into account its timezone. You can therefore use the same CML to display the time in multiple locations, even if they are in different timezones.

attributes:

• format - This is required. It specifies a time format string similar to C formatting strings. See the example for more details. The following table describes the valid entries in the format string:

example:

<p>The time is <date format="%H:%M %p" /> and the date is <date format="%A %d %B %Y" /></p>