CycleServer formats and formatters are two parts of a single feature for displaying values based on attribute metadata. For example, using a built-in format/formatter, tagging an attribute “MemoryFree” with ‘Format=”Byte”‘ will cause CycleServer to interpret numeric values of that attribute as bytes and display values like “2GB” instead of 2147483648. Formatted values may also be non-textual values such as images, charts, links, etc.
What is a Format?
A format is an ad of type “Application.Format” which represents a particular data format, such as “Seconds since Epoch”, “Miles per Hour” or even enumerations such as “HTTP Request Method”. Below is an example of a format ad for “Seconds since Epoch”.
AdType="Application.Format" Name="EpochSeconds" Label="Seconds since Epoch"
That’s all there is to most format ads. However, there are a few other attributes which are defined below. Note that format ads do not contain much information about how to display values. They simply represent a known data format.
Application.Format Ad Definition
|Name||String||Required||A unique name for this format|
|Label||String||Required||The display name for this format.|
|Values||List||Optional||If this format is an enumeration, this is a list of nested ads that
each define metadata about formatting specific values of the
Each nested ad in the Label attribute has the following attributes:
Value (any): the value Label (string): a display name for this value Color (string): an RGB hex string for the color to use for this value (e.g. "6A357D")
What is a Formatter?
AdType="Application.Formatter" Format="EpochSeconds" Name="MiddleEndianDate" Label="Date: MM/DD/YYYY" Plugin="my.DateFormatter" DateFormatString="MM/DD/yy"
Application.Formatter Ad Definition
|Name||String||Required||A unique name for this formatter|
|Label||String||Required||The display name for this formatter|
|Format||String||Required||A reference to the “Name” attribute of an Application.Format.Ad|
|Order||Integer||Optional||For each format, the formatter with the lowest order is used by
default. If no order is specified, 1000 is used as the default.
Used when a formatter will display simple text only. No HTML formatting may be used.
Used when a formatter will produce HTML, or a mix of plain-text and HTML.
How does CycleServer decide which formatter to use?
When choosing a formatter to use for an attribute, 3 factors are considered, in order of importance:
- User preferences (Note that this is not yet implemented as of CycleServer 4.2)
- Additional attributes on the Formatter ad. For example, if we’re looking for a Formatter which
displays values in a verbose manner (particularly useful for tooltips), we might look for an
attribute “Detail” with a value of true.
- The “DefaultFormatter” attribute on the attribute ad.
- The “Order” attribute (lower = higher priority)
To display an attribute of an ad in an HTML context, simply call the “pico/format.apply” method on the ad in the following manner:
The example above could result in the following effective HTML, assuming we have two formats/formatter plugins registered: one for the “Date” attribute, which displays a human readable date, and another for the “Body” attribute, which converts forum-style tags into HTML markup. Note that the “Title” attribute is formatted as a string inside of a <span> tag. This is because the default string formatter plugin is being used. Any attribute without a format registered will be formatted by the default formatter registered to its type.
<div id="newsContainer"> <h1 id="title"><span>Hello World!</span></h1> <span id="date"><span>Friday August 20th, 2010</span></span> <span id="bodyText"><span>In this example, we will use a formatter to support <a href='http://www.cyclecomputing.com'>forum-style tags</a></span></span> </div>