Data Formatters

Often it is desirable to format the data before rendering. Examples are formatting currency and percentage values.

The interface provided to create custom formatters is

interface DataFormatter {
	format(v: unknown): string
	readonly reference?: unknown; // a reference value to use to format and decide default width
	readonly chars?: number; // to decide default width of these many characters
}

The above interface is designed conviniently to make use of existing JavaScript's Intl.NumberFormat and Intl.DateTimeFormat formatting objects.

Loading...

tip

To apply cutsom formatter for pivoted columns, the formatters have to be specified on the gdf instead of on the vdf.

Default Column Widths

SQL Frames has logic to automatically decide the optimal column width when displaying the DataFrames. This logic is based on the values of the field associated with that column. However, the values and their formatting can completely be different and hence there are options to adjust the default column width.

When the formatter provides the reference value, then this reference value is formatted and the resulting string is used to decide the default width.

When the formatter provides the chars value, then a string of these many characters is used to decide the default column width.

See the following example for both these use cases.

Loading...

note

Notice how the column width of x is smaller than that of x0 even though both have the same value. The width difference is not much because this documentation applies a site level default formatting of two decimals.

getData() formatting

The df.getData() API allows getting data out of a DataFrame as both formatted and unformatted (native values). In addition, when it is formatted, it can be iso format or the same format as shown in the DataFrame (user format). For the later, the formatters defined using the DataFormatter API are used. These options are available for both data and the column headers. For normal DataFrames, the column headers return just the name of the columns. For pivot tables, the column headers themselves contain values of the pivoted columns and hence they can be obtained as formatted or unformatted and in iso or user formats.

Refer to the type definitions provided in api.d.ts for how to specify these options.