Mojo.Format

Namespace Detail

Mojo.Format has functions related to formatting dates, times and numbers.

Most of the API methods accept an optional options parameter which can be used to specify extended options for each method. Currently, five properties are recognized:

    countryCode: The two letter IETF/ISO 639 code for a country or region
    fractionDigits: The number of digits to use after the decimal place when representing fractional values
    format: A date/time format string
    date: A date format string
    time: A time format string

Not all APIs use all properties; see each API's documentation for details.

All APIs default to using the device's current locale, so supplying the countryCode is only necessary in the specific case of desiring formatting other than that of the device's current locale, and can be omitted otherwise.

Method Summary
Method Name and Description
Mojo.Format.formatChoice(value, choiceString, model)
Mojo.Format.formatCurrency(amount, options)
Mojo.Format.formatDate(date, options)
Mojo.Format.formatNumber(number, options)
Mojo.Format.formatPercent(percent, options)
Mojo.Format.formatRelativeDate(date, options)
Mojo.Format.getCurrentTimeZone()
Mojo.Format.getFirstDayOfWeek(options)
Mojo.Format.isAmPmDefault(options)
Mojo.Format.runTextIndexer(text)
Mojo.Format.using12HrTime()

Method Detail

Mojo.Format.formatChoice(value, choiceString, model)

Format a choice string according to the given value and model. The choice string is a sequence of choices separated by a vertical bar character. Each choice has a value to match, a hash character, followed by the string to use if the value matches. The string cannot contain a vertical bar. The strings may contain references to objects in the given model that are use to format that string using the Template object. The syntax for the value of "2>" means "greater than 2". Similarly, the syntax "2<" means "less than 2". If the value of the choice is empty, that means to use that choice as the default string.

Example choice string:

    0#There are no files|1#There is one file|2<#There are #{num} files.|#There are some files.

In the above example, if the value passed in with the first parameter is 0, then use the first string "There are no files". If the value passed in with the first parameter is 1, then use the second string "There is one file". If the value is 2 or more, use the last string, "There are #{num} files." If no other choices match, then the default string of "There are some files." is used instead.

The strings may contain references (such as #{num}) to objects in the given model that are used to format the final string.

When this function is called this way:

    var files = 2185;
    var model = { num: files };
    print(Mojo.Format.formatChoice(files, "0#There are no files|1#There is one file|2<#There are #{num} files.", model);

The output is:

    There are 2185 files.

Parameters:
value: a value used to choose the right choice in the choice string
choiceString: a concatenation of string choices
model: object from which values in the string choices are formatted

Returns:: a formatted string corresponding to the given value and formatted with the given model

{String} Mojo.Format.formatCurrency(amount, options)

Converts a number representing an amount of currency into a string, using the proper locale-based format for currency.

Parameters:

{Number} amount

Currency amount to convert

{Number|Object} options

(optional) If a Number, then the number of places after the decimal place.
If an Object, then an object containing various extended options. Currently supports two properties:

'fractionDigits'	the number of places after the decimal place.
'countryCode'	a two letter IETF/ISO 639 code for a country/region. If present, this property specifies what country's/ region's formatting should be used for the operation. If absent, defaults to the device's current locale (which is usually what is desired).

Returns:: Formatted string

Mojo.Format.formatDate(date, options)

Formats the date object based on the options.

Parameters:
{Date} date: object to be formatted
{String|Object} options: Options for the formatter. Let LENGTH represent an element of the set {'short', 'medium', 'long', 'full', 'default'}
options accepts a LENGTH directly as a format or {date: LENGTH (optional), time: LENGTH (optional)} with either date, time, or both specified as a property in the object, or {format: LENGTH}.
If options is solely a LENGTH, formatDate outputs both the date and time formatted according to this string.
If only date or time is specified as a property in an object hash, only the date or time will be returned as formatted in the LENGTH string.
If both date and time are specified as properties in an object hash, both the date or time will be returned and formatted appropriately for the locale and according to their LENGTHs.
If format is specified as a property in an object hash, both the date and time will be returned as formatted in the LENGTH string. The format property is equivalent to specifying both date and time with the same LENGTH string, and takes precedence over the date and time properties.
If countryCode is specified as a property in an object hash, the date and/or time will be returned and formatted as appropriate for the specified country. The countryCode property is a two letter IETF/ISO 639 code for a country/region. If absent, formatting defaults to the device's current locale (which is usually what is desired).

Returns:: the date formatted as a string.

{String} Mojo.Format.formatNumber(number, options)

Converts a number into a string, using the proper locale-based format for numbers.

Parameters:

{Number} number

Number to convert

{Number|Object} options

(optional) If a Number, then the number of places after the decimal place. If an Object, then an object containing various extended options Currently supports two properties:

'fractionDigits'	the number of places after the decimal place.
'countryCode'	a two letter IETF/ISO 639 code for a country/region. If present, this property specifies what country's/ region's formatting should be used for the operation. If absent, defaults to the device's current locale (which is usually what is desired).

Returns:: Formatted string

{String} Mojo.Format.formatPercent(percent, options)

Converts a number into a percent string, using the locale-based format for percentages. The number is expected to already be a percentage, and will not be multiplied by 100.

Parameters:
{Number} percent: Percent to format as a string
{Object} options: (optional) An object containing various extended options Currently only supports a 'countryCode' property, which is a two letter IETF/ISO 639 code for a country/region. If present, this property specifies what country's/ region's formatting should be used for the operation. If absent, defaults to the device's current locale (which is usually what is desired).

Returns:: Formatted string

Mojo.Format.formatRelativeDate(date, options)

Formats the date object based on the options.

Parameters:
{Date} date: Object to be formatted
{String|Object} options: Options for the formatter. If options is a string, it is one of 'short', 'medium', 'long', 'full', or 'default' and outputs the date formatted according to this string if the date is later than tomorrow or earlier than last week. If the date is in the last week, it returns the localized day. If yesterday/today/tomorrow, it provides the property localized strings for those words.
If options is an object, it can contain both or either of the properties 'format', which is a format string as specified above, and 'countryCode', which is a two letter IETF/ISO 639 code for a country/region. If present, this property specifies what country's/region's formatting should be used for the operation. If absent, defaults to the device's current locale (which is usually what is desired).

Returns:: The date formatted as a string.

Mojo.Format.getCurrentTimeZone()

Returns the current timezone of the device.

Returns:: String

Mojo.Format.getFirstDayOfWeek(options)

Returns a zero-based index into the week indicating what day is the first day of the country's or region's calendar week: Sunday: 0 Monday: 1 Tuesday: 2 etc. By default, returns the index appropriate for the device's current region setting.

Parameters:
{Object} options: (optional) An object containing various extended options Currently only supports a 'countryCode' property, which is a two letter IETF/ISO 639 code for a country/region. If present, this property specifies what country's/ region's formatting should be used for the operation. If absent, defaults to the device's current locale (which is usually what is desired).

Returns:: Number

Mojo.Format.isAmPmDefault(options)

Returns whether the current locale "normally" uses AM/PM as opposed to 24 hour time.

Parameters:
{Object} options: (optional) An object containing various extended options Currently only supports a 'countryCode' property, which is a two letter IETF/ISO 639 code for a country/region. If present, this property specifies what country's/ region's formatting should be used for the operation. If absent, defaults to the device's current locale (which is usually what is desired).

Returns:: Boolean

{string} Mojo.Format.runTextIndexer(text)

Searches the parameter text for URLs (web and mailto) and emoticons (if support is enabled) and returns a new string with those entities replaced by HTML links and images (respectively).

Parameters:
{string} text: is the text to transform into HTML

Returns:: {string} HTML-ized version of input string

Mojo.Format.using12HrTime()

Returns whether the current app should use AM/PM as opposed to 24 hour time.

Returns:: Boolean