Number and Date formatting in Ctools dashboards

[Pedro Alves]

Repost from http://pedroalves-bi.blogspot.pt/2015/06/number-and-date-formatting-in-ctools.html


------------------

Number and date format is a very important part of any dashboard development. Happens all the time. 

Historically, CDF has used a helper function very similar to the good ol' sprintf function. However, really falls short to the needs we have.

The same goes for date parsing and format

So we improved the support for it by introducing two utility functions:

• numberFormat
• dateFormat 

The following documentation is actually available from within the

Format Number And Date

CDF has a default library to format numbers i.e. cdo.NumberFormat and other to format dates i.e. moment

Q: How can I format numbers in CDF?

A:

In CDF we provide the function Dashboards.numberFormat to format numbers with a given mask using the dashboard default language or optionally with a specific language.
The mask syntax is mostly compatible with VB's format function mask syntax, only the number related subset is relevant.
Other elements of this mask syntax are 'C' or 'Currency' and 'A' or 'Abbreviation' to insert the currency symbol and abbreviate the number.

Examples:

1. Format a number using the dashboard language, e.g. 'en-us':

    Dashboards.numberFormat(1200, '0,#.0')                -> "1,200.0"
    Dashboards.numberFormat(1200, '0,0.#')                -> "1,200"
    Dashboards.numberFormat(1200.46, '0,0.#')             -> "1,200.5"

    Dashboards.numberFormat(5480, '0.00 Abbreviation')    -> "5,49 k"
    Dashboards.numberFormat(5480000, '0.00A')             -> "5,49m"
    Dashboards.numberFormat(5480000000, '0.00A')          -> "5,49b"
    Dashboards.numberFormat(5480000000000, '0.00A')       -> "5,49t"

    Dashboards.numberFormat(4500.64, '0,0.0\u00a4')       -> "4,500.6$"
    Dashboards.numberFormat(4500000.64, '0,0.0 Currency') -> "4,500,000.6 $"
    Dashboards.numberFormat(4500.64, 'C 0,0.0')           -> "$ 4,500.6"

    Dashboards.numberFormat(0.2, '0.00%')                 -> "20.00%"
    Dashboards.numberFormat(1200, '0.0e00')               -> "1.2e03"
    Dashboards.numberFormat(4500000, '0.0AC')             -> "4.5m$"
            

2. Format a number using a specific language, will use fallback logic if the specified language isn't found:

    Dashboards.numberFormat(4500.64, '0,0.0 C', 'pt-pt') -> "4,500.6 €"
    Dashboards.numberFormat(4500.64, 'C 0,0.0', 'en-gb') -> "£ 4,500.6"
    Dashboards.numberFormat(4500.64, 'C 0,0.0', 'xx-zz') -> "$ 4,500.6" *Fallback to the default 'en-us'*
            

Q: How can I format dates in CDF?

A:

Similar to number format, here we provide the function Dashboards.dateFormat to format a date with a given mask.
For a detailed list of examples on how to use moment click here.
The mask syntax is explained in detail here.
To add more languages to moment you can do two things:

• Manually configure a new language using the function Dashboards.configLanguage described in the next section with a configuration object as described here.
• Import a locale configuration file from 'moment/locale/' to a folder in the repository, e.g. '/public/cdf/locale' and load it in the dashboard using the 'Add Resource - external javascript file' operation

Examples:

    Dashboards.dateFormat(moment(),'DD/MM/YY')                                        -> "19/06/15"
    Dashboards.dateFormat(moment(), 'dddd Do MMMM YYYY')                               -> "Friday 19th June 2015"
    Dashboards.dateFormat( moment('13-08-1983', 'DD-MM-YYYY'), 'D MMM, YYYY') -> "13 Aug, 1983"
            

Q: How can I configure new or existing languages?

A:

To configure a new or existing language you can use the function Dashboards.configLanguage by specifying the language code and a configuration object with the keywords:

• number - to configure number's format language
• dateLocale - to configure date's format language

Examples:

1. Configure the number's format language:

    Dashboards.configLanguage('foo-bar', {
        number: {
            mask:              '#,0.##',
            style: {
                integerPad:    '0',
                fractionPad:   '0',
                decimal:       ',',
                group:         ' ',
                groupSizes:    [3],
                abbreviations: ['k','m', 'b', 't'],
                negativeSign:  '-',
                currency:      'F'
            }
        }
    })
            

2. Configure the date's format language:

    Dashboards.configLanguage('foo-bar', {
        dateLocale: {
            months: [
                "January", "February", "March", "April", "May", "June",
                "July", "August", "September", "October", "November", "December"
            ],
            monthsShort: [
                "Jan", "Feb", "Mar", "Apr", "May", "Jun",
                "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"
            ]
        }
    })
            

3. Configure both format language:

    Dashboards.configLanguage('foo-bar', {
        number: {
            mask:              '#,0.##',
            style: {
                integerPad:    '0',
                fractionPad:   '0',
                decimal:       ',',
                group:         ' ',
                groupSizes:    [3],
                abbreviations: ['k','m', 'b', 't'],
                negativeSign:  '-',
                currency:      'F'
            }
        },
        dateLocale: {
            months: [
                "January", "February", "March", "April", "May", "June",
                "July", "August", "September", "October", "November", "December"
            ],
            monthsShort: [
                "Jan", "Feb", "Mar", "Apr", "May", "Jun",
                "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"
            ]
        }
    })