back to Overview


Formats a single value as a string, using the given format template.
Util module only.


_.formatValue(format, value)


the format that describes the output
the value to format. Either a Date, a number, a string or a value that can be converted to a string.
(return value)
the string-formatted value


Formats a single value as a string, using the given format template. It has support for numbers, dates, booleans and strings.

Choice Formatting
With a choice format, you can map input values into output values. In the format string the choices are separated by pipes ('|') and each choice has the format <cmp><value>:<result>:

  • <cmp> is a comparison operator ('=', '>', '<', '>=', '<='), but can be omitted to check for equality.
  • <value> is the value as string.
  • <result> is the result, either a string or a number format
You can have a default choice at the end without <cmp> or <value>.


_.formatValue('true:is True|is False', value);
_.formatValue('<5:under 5|>=15:at least 15|=7:is seven|some other number', value);
_.formatValue('1:one item|2:two items|>3:many items', value);
_.formatValue('ERR:error|WARN:warning|INFO:info|debug', value);

Number Formatting
Number formatting allows you to specify the number of digits before and optionally after the decimal separator, the decimal separator itself as well as how to group and decorate the digits. The following characters are used in the format:

#Optional digit before decimal separator.
0Required digit before decimal separator (0 if number is smaller).
.Decimal separator (if it occurs exactly once in the string)
:Required for choice formats. You can not use this in a number format.
|Required for choice formats. You can not use this in a number format.

All other characters will stay unmodified in the format string. For negative numbers, a sign (-) is placed in front of the first digit.

If you don't provide sufficient pre-decimal placeholders for the number, the remaining digits will be put in front of the rest of the number, so the rendered number is always complete. However, there will be no grouping if there are no placeholders.

If you only define a group separator, but not a decimal separator, and you use a comma (,) or period (.) as separator, the group separator must appear at least twice in the format. Otherwise it will be considered a decimal separator.


var v1  = _.formatValue('#', 15);           // '15'
var v2  = _.formatValue('####', 15);        // '15'
var v3  = _.formatValue('0000', 15);        // '0015'
var v4  = _.formatValue('#.###', 15.14274); // '15.143'
var v5  = _.formatValue('#.000', 15.14274); // '15.143'
var v6  = _.formatValue('#.###', 15.1);     // '15.1'
var v7  = _.formatValue('#.000', 15.1);     // '15.100'
var v8  = _.formatValue('000,000', 15.1);   // '015,100'
var v9  = _.formatValue('#.###', 15);       // '15'
var v10 = _.formatValue('#.000', 15);       // '15.000'
var v11 = _.formatValue('#,###', 15.1);     // '15,1' (comma as decimal separator)
var v10 = _.formatValue('Total= $#.00 (VAT included)', 71);  // 'Total= $71.00 (VAT included)' (decoration)
var v12 = _.formatValue('###,###,###', 92548);    // '92,548' (grouped digits)
var v14 = _.formatValue('###.###.###,###', 92548.42); // '92.548,42' (comma as decimal separator)
var v14 = _.formatValue('### ### ###.###', 92548.42); // '92 548,42' (space as decimal separator)
var v15 = _.formatValue('<10:#.00|<100:#.0|#', 7.356); // '7.36' (choice format)
var v16 = _.formatValue('<10:#.00|<100:#.0|#', 25.04); // '25.0'
var v17 = _.formatValue('<10:#.00|<100:#.0|#', 71.51); // '72'

Choice Number Formatting
It is possible to combine number formatting with choices. You can also use additional characters in a number format.


_.formatValue('$#.00', 17);  // '$17.00'
_.formatValue('0:no eggs|1:1 egg|>1:# eggs', 12);  // '12 eggs'

Date Formatting
In a date format, there are a number of reserved characters that represent parts of the date. If you repeat the same character, you specify the minimum number of digits. Some elements allow a comma-separated list of translations in angular brackets, see below.

yYear (4 digits)
YYear (2 digits)
MMonth (1-12)
nMonth as short name ('Jan', 'Feb'...). Supports translations.
NMonth as long name ('January', 'February'...). Supports translations.
dDay of month (1-31)
mMinutes (0-59)
HHours in 24h format (0-23)
hHours in 12h format (1-12)
KHours in 0-based 12h format (0-11)
kHours in 1-based 24h format (1-24)
sSeconds (0-59)
SMilliseconds (0-999)
aEither 'am' or 'pm'. Supports translations.
wDay of week as short name ('Sun', 'Mon'...). Supports translations.
WDay of week as long name ('Sunday', 'Monday'...). Supports translations.
zTimezone offset, e.g. '+0700'
formatValue also supports formatting a date in a different timezone. You only need to put the timezone in brackets at the front of the format, e.g. '[+0100]'.


var now = new Date();
var v1  = _.formatValue('y-M-d', now);       // e.g. '2013-7-9'
var v2  = _.formatValue('yyyy-MM-dd', now);  // e.g. '2013-07-09'
var v3  = _.formatValue('yyyy-MM-ddTHH:mm:ss.SS z', now); // e.g. '2013-07-09T23:07:38.472 +0700'
var v4  = _.formatValue('MM/dd/YY h:mm:ss a', now);       // e.g. '07/09/13 11:07:38 pm'
var v5  = _.formatValue('dd.MM.yyyy HH:mm:ss', now);      // e.g. '09.07.2013 23:07:38'
var v6  = _.formatValue('H:mm', now);                // e.g. '23:07'
var v7  = _.formatValue('W, N d y', now);            // e.g. 'Tuesday, July 9 2013'
var v8  = _.formatValue('Nd', now);                  // e.g. 'July9'
var v9  = _.formatValue('d.N[Januar,Februar,März,April,Mai,Juni,Juli,'+
            'August,September,Oktober,November,Dezember]', now); // German translation: '9. Juli'
var v10 = _.formatValue('[+0100]yyyy-MM-dd h:mm a', now);  // different timezone: '2013-07-09 5:07 pm'

See also..


comments powered by Disqus

back to Overview