$Formatter

The $Formatter reference contains a number of methods used to format information from Broadcast. This information can be generated by Broadcast or from user input. $Formatter methods are case-sensitive.

Some of the methods use a particular date format or number format.  Some of the date functions can also take a timezone as argument.  A description of these formats is at the end of this page.

$Formatter Methods

$Formatter methods take an argument and return a result that can used on your web page. $Formatter methods are case sensitive. All methods start in lower-case.

date(date)

Displays date as a string based on date-based input.

Example FML statement:

$Formatter.date($Today)

Example result:  (if today is March 23, 2005)

03-23-05

 date(date,format)

Displays date or time as a string based on date-based input and the date format.

Example 1 FML statement:

$Formatter.date($Today, "yyyy")

Example 1 result: (if the current year is 2005)

2005

Example 2 FML statement:

$Formatter.date($Today, "dd")

Example 2 result: (if today is the 23rd day of the month)

23

 date(date,format,timezone)

Displays date or time as a string based on date-based input, the date format, and the supplied timezone.

Example FML statement:

$Formatter.date($Run.Created, "H:mm z", "US/Eastern")

Example result: (if the time is 11:32 US Pacific time)

2:32 EST

escapeCssText(string)

Encodes a string so that it can be used a String in a cascading style sheet, by putting a backlash before '#' and '@'.  This is commonly used when specifying number formats while exporting data to Excel.

Example FML statement:

$Formatter.escapeCssText('##.00')

Example result:

\#\#.00

escapeJavascriptText(string)

Encodes a string so that it can be used in a Javascript string, by replacing ' with \'   and  "  with \".

Example FML statement:

sendAlert('$Formatter.escapeJavascriptText("Joe's Sales are Superb!")')

Example result:

sendAlert('Joe\'s Sales are Superb!')

escapeUrlText(string)

Encodes a string so that it can be used in a URL, by replacing spaces with + and punctuation.

Example FML statement:

$Formatter.escapeUrlText('Clint Eastwood at work and at play')

Example result:

Clint+Eastwood+at+work+and+at+play

fullDate(date)

Displays the complete date as a string based on date-based input.

Example FML statement:

$Formatter.fullDate($Today)

Example result:

Mar 23, 2005

fullDate(date,timezone)

Displays the complete date as a string based on date-based input, adjusted to the appropriate timezone.  Typically this will return the same as without the timezone, but if the time is shifted forward or back across midnight the day will shift.

Example FML statement:

$Formatter.fullDate($Run.Created,"Japan")

Example result:  (if the date is Mar 22, 2005 and the time is 6:00 PM Pacific Standard Time)

Mar 23, 2005

fullTime(date)

Displays the time, including seconds, as a string based on date-based input.

Example FML statement:

$Formatter.fullTime($Today)

Example result: (if it is currently 11:57:23 AM)

11:57:23 AM

fullTime(date,timezone)

Displays the time, including seconds, as a string based on date-based input, adjusted to the appropriate timezone.

Example FML statement:

$Formatter.fullTime($Today,"US/Eastern")

Example result: (if it is currently 11:57:23 AM Pacific Standard Time)

2:57:23 PM

html(string)

Removes any HTML that a user may have entered into a text box so that the output from the user can be safely presented in HTML. All carriage returns that the user enters are ignored.

Example input HTML code for user input:

Example user text box with text that the user has entered:

Example FML code for displaying user text:

Example output to user's browser:

htmlFiltered(String)

Allows basic HTML formatting statements but removes all other HTML statements.  Use this to allow a user to enter formatted text while preventing Javascript and other "dangerous" user-entered code from being included in the page.  Specifically, HTML tags <b>, <i>, <u>, <a> (without Javascript), <img>, <ol>, <ul>, <li>, <pre>, <div>, <br>, and <p> are allowed.  Also causes a blank line to be treated as the start of a new paragraph by automatically inserting a <p> tag.

Example FML code:

Results:

Example output to user's browser:

htmlMultiLine(String)

Removes any HTML that a user may have entered into a text box and changes any carriage returns into <BR> so that the output from the user can be safely presented in HTML.

Example input HTML code for user input:

Example user text box with text that the user has entered:

Example FML code for displaying user text:

$Formatter.htmlMultiLine($Web.getParameter('SAMPLE'))

Example output to user's browser:

memory(number of bytes)

Correctly displays numbers in terms of KB or MB, depending on size

Example 1 FML statement:

$Formatter.memory(4096)

Example 1 result:

4 KB

Example 2 FML statement:

$Formatter.memory(5000000)

Example 2 result:

4.7 MB

na(number, format)

Displays a number according to the number format specified, and "n/a" if the value is 0 or invalid.

Example FML statement:

#set ($result = 5 / 0)
$Formatter.na(result, '$#,##0')

Example result:

n/a

number(number, format)

Displays a number according to the number format specified.

Example FML statement:

$Formatter.number(123456789, '$#,##0')

Example result:

$123,456,789

shortNumber(number)

Displays a number in abbreviated form adding a "K" for thousands, "M" for millions "B" for billions, or "T" for trillions.  Has zero decimal points.

Example 1 FML statement:

$Formatter.shortNumber(4110)

Example 1 result:

4K

Example 2 FML statement:

$Formatter.shortNumber(5176111)

Example 2 result:

5M

shortNumber(number, format)

Displays a number in abbreviated form adding a "K" for thousands, "M" for millions "B" for billions, or "T" for trillions.  Applies the specified number format after dividing by 1 thousand, 1 million, 1 billion, or 1 trillion.

Example 1 FML statement:

$Formatter.shortNumber(4110,"0.0")

Example 1 result:

4.1K

Example 2 FML statement:

$Formatter.shortNumber(5176111,"$###")

Example 2 result:

$5M

time(date)

Displays the time as a string based on date-based input.

Example FML statement:

$Formatter.time($Today)

Example result: (if it is currently 11:57 AM)

11:57 AM

time(date,timezone)

Displays the time as a string based on date-based input, adjusted to the appropriate timezone.  

Example FML statement:

$Formatter.time($Today,"US/Eastern")

Example result: (if it is currently 11:57 AM Pacific Standard Time)

2:57 PM

Time Formats

The $Formatter.date method uses a time pattern string to specify the format of the date and time.   In this pattern, all ASCII letters are reserved as pattern letters, which are defined as the following:

The count of pattern letters determine the format.

Examples:

Time Zones

By default, all date and times displayed on Forio Broadcast Professional are based on US Pacific Time.  Similarly, all date and times displayed in simulations served by Forio Broadcast Enterprise follow the time zone setting of the physical server.

Any displayed time can be adjusted to a specific time zone by using a date formatting method with the optional time zone argument.  This will adjust the time by the correct number of hours taking into account daylight savings time in the new time zone.  Note that the start and end date for daylight savings time will vary depending on the location and country.

The names for time zones are based on the standard tz database.  More information can be found on the tz web site.  Additionally, the Time Zone Converter provides a detailed list of time zone settings per country.

Below are the options for the US time zones.  Note that there are a number of different choices due to differences in daylight savings time.  (For example, Arizona does not follow standard US daylight savings time).    

Finally, the time zone may also be specified as an offset of GMT (Greenwich Mean Time).  In such cases the displayed time will not include any adjustments for daylight savings time.  For example, the first two time zones below will be 8 hours before GMT.  (e.g. Pacific Standard Time), while the third time zone will be one hour after GMT (e.g. Central European Standard Time).

Number Formats

The $Formatter.number method uses a number pattern string to specify the format of a number.  This format is similar (but not identical) to that used by Microsoft Excel.  The format is

pattern   or
positive pattern; negative pattern

Symbols used in a pattern include the following:

Other letters or symbols in the pattern are displayed verbatim.

To round to a specified number of decimals, Forio Broadcast uses "half-even" rounding.  This means that rounding is done to the nearest neighbor, unless both neighbors are equidistant.   In this case, it round up when the digit to the left of the discarded fraction is odd and round down if it's even.   This form of rounding minimizes cumulative error when applied repeatedly over a sequence of calculations.

Examples: