Skip to main content

DHTMLX Pivot. Adding text templates for table and header cells example

Demo of text templates for customizing cell values and header labels in DHTMLX Pivot. Append state abbreviations to row values and transform header text to lowercase using tableShape.templates and headerShape.template.

Live example​

const url = "https://snippet.dhtmlx.com/codebase/data/pivot/04/dataset.json";

fetch(url).then(res => res.json()).then(dataset => {
    const { data, fields } = prepareData(dataset);

    new pivot.Pivot("#pivot", {
        data,
        tableShape: {
            templates: {
                // set a template to customize values of "state" cells
                state: v => v+ ` (${states[v]})`,
            }
        },
        headerShape: {
            // a custom template for header text 
            template: (label, id, subLabel) => (label + (subLabel ? ` (${subLabel})` : "")).toLowerCase(),
         },
        config: {
            rows: ["state", "product_type"],
            columns: [],
            values: [
                {
                    field: "profit",
                    method: "sum"
                },
                {
                    field: "sales",
                    method: "sum"
                },
                {
                    field: "marketing",
                    method: "sum"
                },
                {
                    field: "date",
                    method: "min"
                },
                {
                    field: "cogs",
                    method: "sum"
                },
            ],
        },
        fields,
    });
})
<!-- component container -->
<div style="width: 100%; height: 100%" id="pivot"></div>

<script>
const states = {
  "California": "CA",
  "Colorado": "CO",
  "Connecticut": "CT",
  "Florida": "FL",
  "Illinois": "IL",
  "Iowa": "IA",
  "Louisiana": "LA",
  "Massachusetts": "MA",
  "Missouri": "MO",
  "Nevada": "NV",
  "New Hampshire": "NH",
  "New Mexico": "NM",
  "New York": "NY",
  "Ohio": "OH",
  "Oklahoma": "OK",
  "Oregon": "OR",
  "Texas": "TX",
  "Utah": "UT",
  "Washington": "WA",
  "Wisconsin": "WI"
};

function prepareData(dataset) {
    const {data, fields} = dataset;
    const dateFields = fields.filter(f => f.type == "date");
    data.forEach(item => {
        dateFields.forEach(f => {
            const v = item[f.id];
            if (typeof v == "string") item[f.id] = new Date(v);
        })
    });
    return {data, fields}
}
</script>

Raw field values in pivot tables often need contextual formatting to be useful. State names like "California" or "Colorado" take up horizontal space and may need abbreviations for compact views. Similarly, auto-generated header labels from field names and aggregation methods may not match your application's typography standards.

DHTMLX Pivot provides two template mechanisms for text-level customization: tableShape.templates for modifying cell display values, and headerShape.template for transforming header labels. Unlike HTML templates that inject markup, text templates work with plain string transformations - appending suffixes, reformatting labels, or applying text case changes.

This example demonstrates both template types working together. The tableShape.templates.state function appends a two-letter state abbreviation in parentheses (e.g., "California (CA)"), while headerShape.template converts all header labels to lowercase and appends sub-labels in parentheses. Use this approach when you need to enrich cell text without injecting HTML elements.

Solution overview​

To customize cell text values, define a templates object inside tableShape where each key matches a field name. The template function receives the cell value and returns the modified string. In this example, state: v => v + ` (${states[v]})` looks up the state abbreviation from a mapping object and appends it.

For header labels, the headerShape.template function receives three arguments: label (the display name), id (the field identifier), and subLabel (the aggregation method label). The example transforms the combined text to lowercase: (label, id, subLabel) => (label + (subLabel ? ` (${subLabel})` : "")).toLowerCase(). This affects all column headers uniformly.

Key points​

  • Field-specific cell templates: The tableShape.templates object maps field names to template functions, so you can customize individual fields (like "state") without affecting other columns
  • Uniform header transformation: The headerShape.template function applies to all column headers, making it ideal for consistent typography changes like case normalization
  • Pure text output: Unlike the HTML render-table intercept approach, these templates return plain strings - they are simpler to implement but cannot insert icons or markup
  • Data fetched asynchronously: The example loads data from a remote JSON endpoint and processes date fields with a prepareData() helper, demonstrating a real-world data loading pattern

API reference​

Additional resources​