jQuery Common - Data Formatting

In the widgets provided by the DevExtreme Data Visualization library, you can easily customize the automatically generated text for the following widget elements.

Chart and PolarChart

• legend items
• point labels
• axis labels
• tooltips

PieChart

• legend items
• point labels
• tooltips

TreeMap

• tooltips

CircularGauge and LinearGauge

• subvalue indicators of the textCloud type
• value indicator of the rangeBar type
• tooltips

BarGuage

• bar labels
• tooltips

RangeSelector

• scale labels
• scale markers
• slider markers

Bullet and Sparkline

• tooltips

• tooltips

For this purpose, the widgets provide a uniform set of options. No matter where you need to customize text, you always have the format and customizeText (or customizeTooltip for tooltips) options.

Also, DevExtreme widgets provide a set of predefined formats that cover most cases of applying a format. These formats can be divided into three groups.

• Numeric Formats
• Date-Time Formats
• Currency Formats

Moreover, you can specify a custom format. See the following topics for detailed information on each case.

To set a numeric format, use the format.type option. Also, you can apply a precision to numeric values using the format.precision option. For example, the following configuration makes Chart's series point labels display values rounded up to the nearest hundredth.

var data = [
    { quarter: 'QI', quantity: 26.252 },
    { quarter: 'QII', quantity: 26.5 },
    { quarter: 'QIII', quantity: 26.375 },
    { quarter: 'QIV', quantity: 25.75 }
];

var chartOptions = {
    dataSource: data,
    series: {
        // ...
        label: {
            // ...
            format: {
                type: 'fixedPoint',
                precision: 2
            }
        }
    }
};

The format option also accepts strings. Use this capability as a shortcut for specifying a predefined format.

var widgetOptions = {
    // ...
    customizableElement: {
        format: 'fixedPoint'
    }
};

Alternatively, you can use a native formatter of the Globalize library. In this case, the format option accepts an object whose fields are the same as the options passed to the numberFormatter.

var widgetOptions = {
    // ...
    customizableElement: {
        format: {
            // ...
            minimumIntegerDigits: 1
        }
    }
};

Note that you must not set the type option if you use a Globalize formatter. Also, this approach might require additional CLDR modules not shipped with the DevExtreme package.

• 'longDate' - "Thursday, January 01, 1970"
• 'longTime' - "12:00:00 AM"
• 'longDateLongTime' - "Thursday, January 01, 1970, 12:00:00 AM"
• 'monthAndDay' - "January 01"
• 'monthAndYear' - "1970 January"
• 'quarterAndYear' - "QI 1970"
• 'shortDate' - "1/25/1970"
• 'shortTime' - "12:00 AM"
• 'shortDateShortTime' - "1/25/1970, 12:00 AM"
• 'millisecond' - "010"
• 'day' - "01"
• 'month' - "January"
• 'quarter' - "QI"
• 'year' - "1970"
• 'dayOfWeek' - "Thursday"
• 'hour' - "12"
• 'minute' - "00"

To set a date-time format, assign one of the values above to the format.type option. For example, the following code applies the 'monthAndDay' format to Chart's argument axis labels.

var data = [
    { date: new Date(1994,2,3), quantity: 26.25 },
    { date: new Date(1994,2,4), quantity: 26.50 },
    { date: new Date(1994,2,5), quantity: 26.375 },
    { date: new Date(1994,2,6), quantity: 25.75 }
];

var chartOptions = {
    // ...
    dataSource: data,
    argumentAxis: {
        label: {
            // ...
            format: {
                type: 'monthAndDay'
            }
        }
    }
};

The format option also accepts strings. Use this capability as a shortcut for specifying a predefined format.

var widgetOptions = {
    // ...
    customizableElement: {
        format: 'monthAndDay'
    }
};

Alternatively, you can use a native formatter of the Globalize library. In this case, the format option accepts an object whose fields are the same as the options passed to the dateFormatter.

var widgetOptions = {
    // ...
    customizableElement: {
        format: {
            skeleton: "GyMMMd"
        }
    }
};

Note that you must not set the type option if you use a Globalize formatter. Also, this approach might require additional CLDR modules not shipped with the DevExtreme package.

To set a currency format, assign 'currency' to the format.type option.

var widgetOptions = {
    // ...
    customizableElement: {
        format: {
            type: 'currency'
        }
    }
};

This setting applies the global default currency - 'USD'. It is specified by the defaultCurrency field of the object returned by the DevExpress.config() method. To change it, use the following code.

DevExpress.config({ defaultCurrency: 'EUR' });

To use any currency that differs from USD, follow these steps.

1. Get the currencies.json file that corresponds to your locale from one of the folders here.
2. Load the contents of this file in your app using one of the methods described here.

3. Assign the 3-letter code of the needed currency to the format.currency option.

   JavaScript

   var widgetOptions = {
       // ...
       customizableElement: {
           format: {
               type: 'currency',
               currency: 'EUR'
           }
       }
   };

Additionally, you can specify the precision of currency values using the format.precision option.

var widgetOptions = {
    // ...
    customizableElement: {
        format: {
            // ...
            type: 'currency',
            precision: 2
        }
    }
};

If you do not need to change neither the currency nor the precision field, assign 'currency' straight to the format option. This setting will apply the global default currency.

var widgetOptions = {
    // ...
    customizableElement: {
        format: 'currency'
    }
};

Alternatively, you can use a native formatter of the Globalize library. In this case, the format option accepts an object whose fields are the same as the options passed to the currencyFormatter.

var widgetOptions = {
    // ...
    customizableElement: {
        format: {
            currency: 'EUR',
            style: 'name'
        }
    }
};

Note that you must not set the type option if you use a Globalize formatter. Also, this approach might require additional CLDR modules not shipped with the DevExtreme package.

If none of the predefined formats meet your requirements, specify a custom format using the formatter function. This function accepts the original value as the parameter and returns a formatted string.

var widgetOptions = {
    // ...
    customizableElement: {
        format: {
            formatter: function (originalValue) {
                // ...
                return formattedString;
            }
        }
    }
};

In addition, you can implement the parser function to parse numbers or dates presented as strings into the correct format. This function may be called internally by the widget at different points of your application's lifetime.

var widgetOptions = {
    // ...
    customizableElement: {
        format: {
            // ...
            parser: function (stringToParse) {
                // ...
                return valueWithCorrectFormat;
            }
        }
    }
};

If formatter is the only field that you need to specify in the format object, assign the function straight to the format option as shown below.

var widgetOptions = {
    // ...
    customizableElement: {
        format: function (originalValue) {
            // ...
            return formattedString;
        }
    }
};

When you need to customize text after (or instead of) applying a format, use the customizeText function. This function returns the final text. Its parameter contains data about the element whose text is being customized. The actual contents of this parameter depend on the element. For example, the following code customizes the text of the Chart's value axis labels after applying a 'fixedPoint' format.

var data = [
    { quarter: 'QI', quantity: 26.252 },
    { quarter: 'QII', quantity: 26.5 },
    { quarter: 'QIII', quantity: 26.375 },
    { quarter: 'QIV', quantity: 25.75 }
];

var chartOptions = {
    dataSource: data,
    // ...
    valueAxis: {
        // ...
        label: {
            format: {
                type: 'fixedPoint',
                precision: 2
            },
            customizeText: function (data) {
                return data.valueText + 'ml' ;
            }
        }
    }
};

When providing a custom text for tooltips, use the customizeTooltip function instead of customizeText. This function must return an object wherein the required text is assigned to the 'text' field. In the following code, the customizeTooltip function combines the formatted value and argument of a point.

var chartOptions = {
    // ...
    tooltip: {
        enabled: true,
        format: { 
            type: 'fixedPoint',
            precision: 2
        },
        argumentFormat: {
            skeleton: 'Md'
        },
        customizeTooltip: function (data) {
            return { 
                text: data.valueText + ' on ' + data.argumentText
            };
        }
    }
};