Formatter Types

Formatters control how cell values are rendered in a grid column. They receive a FormatterContext and return a string, a DOM node, or a fragment.

The FormatterContext

A formatter is a function (or an object with a format method) that receives a FormatterContext:

interface FormatterContext<TItem = any> {
    value?: any;                 // the cell value
    row?: number;                // the row index
    cell?: number;               // the column index
    column?: Column<TItem>;      // the column definition
    item?: TItem;                // the row item
    grid?: ISleekGrid;           // the grid instance
    enableHtmlRendering: boolean; // whether HTML strings are allowed
    escape(value?: any): string; // HTML-escapes a value
    sanitizer: (dirtyHtml: string) => string; // sanitizes HTML
    purpose?: "auto-width" | "excel-export" | "pdf-export" | "print" | ...;
    addClass?: string;           // extra classes for the cell
    addAttrs?: { [key: string]: string }; // extra attributes for the cell
    tooltip?: string;            // title attribute for the cell
}

HTML Rendering and XSS Safety

By default enableHtmlRendering is false, which means a formatter should return plain text — the result is set via textContent, and escape() is a no-op. When enableHtmlRendering is true, a formatter may return HTML strings, but should use ctx.escape() to avoid script injection:

format(ctx) {
    return `<a href="${ctx.escape(ctx.value)}">${ctx.escape(ctx.value)}</a>`;
}

When writing formatters with JSX, values are escaped automatically, so you don't need ctx.escape():

format(ctx) {
    return <a href={ctx.value}>{ctx.value}</a>;
}

Built-in Formatters (corelib)

These formatters are registered in @serenity-is/corelib and are typically applied via formatter attributes on columns:

Formatter	Description
UrlFormatter	Renders a value as a hyperlink.
DateFormatter	Formats a date value.
DateTimeFormatter	Formats a date-time value.
EnumFormatter	Renders an enum value as its localized text.
NumberFormatter	Formats a number with a display format.
BooleanFormatter	Renders a boolean as localized true/false text.
CheckboxFormatter	Renders a boolean as a checkbox.
FileDownloadFormatter	Renders a file download link.
MinuteFormatter	Formats a minute value as hours:minutes.

Built-in Formatters (SleekGrid)

SleekGrid also ships function formatters that take a FormatterContext directly:

Formatter	Description
PercentCompleteFormatter	Renders a percent value as bold colored text.
PercentCompleteBarFormatter	Renders a percent value as a colored bar.
YesNoFormatter	Renders a boolean as "Yes"/"No".
CheckBoxFormatter	Renders a boolean as a checkbox icon.
CheckmarkFormatter	Renders a boolean as a checkmark icon.

URLFormatter

This formatter lets you put a link with a URL to a grid column.

It takes optional arguments below:

Option Name	Description
UrlFormat	This is the format of URL. A sample would be "http://www.site.com/{0}" where {0} is the UrlProperty value. If no format is specified, link will be the value of UrlProperty as is. If your URL format starts with "~/", it will be resolved to application root. For example, if format is "~/upload/{0}" and your application runs at "localhost:3045/mysite", resulting URL will be "/mysite/upload/xyz.png".
UrlProperty	This is name of the property that will be used to determine link URL. If not specified, it is the name of the column that this formatter is placed on. If UrlProperty value starts with "~/" it will be resolved like UrlFormat.
DisplayFormat	This is the display text format of link. A sample would be "click to open {0}" where {0} is the DisplayProperty value. If no format is specified, link will be the value of DisplayProperty as is.
DisplayProperty	This is name of the property that will be used to determine link text. If not specified, it is the name of the column that this formatter is placed on.
Target	This is the target of the link. Use "_blank" to open links in a new tab.

Custom Formatters

A custom formatter is a class that implements Formatter (a format(ctx) method) and registers with formatterTypeInfo:

import { FormatterContext, FormatterResult } from "@serenity-is/sleekgrid";
import { formatterTypeInfo, registerType } from "@serenity-is/corelib";

export class MyFormatter implements Formatter {
    static [Symbol.typeInfo] = formatterTypeInfo("MyApp.MyFormatter");
    static { registerType(this); }

    format(ctx: FormatterContext): FormatterResult {
        return ctx.value ? "Yes" : "No";
    }
}

See Type Registration for details.

You can also assign a formatter directly to a column in createColumns():

protected override createColumns() {
    let columns = new UserColumns(super.createColumns());
    columns.ImpersonationToken && (columns.ImpersonationToken.format = ctx => !ctx.value ? "" :
        <a target="_blank" href={resolveUrl(`~/Account/ImpersonateAs?token=${encodeURIComponent(ctx.value)}`)}>
            <i class={faIcon("user-secret", "primary")}></i>
        </a>);
    return columns.valueOf();
}