Customizing the grid

Besides appearance customization of the component in general, Flexmonster also provides functionality for extended grid customization. The customizeCell API call allows styling up entire columns, rows, or specific cells according to a certain requirement.

About the customizeCell API call

The customizeCell method is triggered for each table cell during rendering, and it has two parameters:

The cell builder, which contains the cell's current HTML representation and through which the representation can be customized.
The CellDataObject, which contains information about the cell, e.g., its position on the grid and the semantics of data this cell represents.

Check out a full description of the customizeCell parameters.

This guide contains several examples illustrating how customizeCell helps in achieving visualization goals. To see more examples of customizeCell usage, visit the Examples page.

Example 1. Alternating row colors

This sample explains how to alternate row colors on the grid.

Here’s how the customizeCellFunction can be defined:

function customizeCellFunction(cell, data) {
  if (data.type == "value") {
    if (data.rowIndex % 2 == 0) {
      cell.addClass("alter");
    } else {
      return;
    }
  }
}

Here is the CSS code sample:

#fm-pivot-view .fm-grid-view div.alter {
  background-color: #e1e1e1;
}

In this sample, the CSS class is applied only to cells where data.type is "value", which means that the cell contains data.

Live example

The same approach can be used for alternating column colors.

Example 2. Styling subtotals and grand totals

Totals in rows and columns can be styled independently. The CellDataObject has properties specifying if the cell is subtotal in the compact pivot table, subtotal in the classic (tabular) form, or grand total. Based on the values of these properties in each cell, a CSS class can be added to it. Here is an example:

function customizeCellFunction(cell, data) {
  if (data.isClassicTotalRow) {
    cell.addClass("fm-total-classic-r");
  }
}

The CSS code sample:

#fm-pivot-view .fm-grid-view .fm-total-classic-r {
  background-color: #B2DBBF;
}

Live example

Example 3. Highlighting cells based on their data

The CellDataObject has measure, rows, and columns properties that contain info about the cell's semantics. Take a closer look at several samples demonstrating the usage of these properties.

3.a. Highlighting a certain member on the grid

This example describes how to highlight cells containing info about a certain member regardless of their position:

const highlightedMembers = {
  "Country": ["Canada", "Germany"],
  "Business Type": ["Warehouse"]
}

function customizeCellFunction(cell, data) {
  if (data.rows) {
    data.rows.forEach(row => {
      if (highlightedMembers[row.hierarchyName] &&
      highlightedMembers[row.hierarchyName].includes(row.caption)) {
        cell.addClass("highlight");
      }
    });
  }
  if (data.columns) {
    data.columns.forEach(column => {
      if (highlightedMembers[column.hierarchyName] &&
      highlightedMembers[column.hierarchyName].includes(column.caption)) {
        cell.addClass("highlight");
      }
    });
  }
}

Then, after the attributes were added, the following CSS selector can be written:

.highlight {
  background-color: #FFB74D !important;
}

Live example

3.b. Highlighting a certain measure on the grid

This sample is similar to the previous sample, but information about the measure is added to cells as follows:

function customizeCellFunction(cell, data) {
  if (data.measure) {
    cell.attr["measure"] = data.measure.name;
  }
}

Each HTML cell will have a measure attribute, and the following CSS selector will highlight the rows with Price:

#fm-pivot-view .fm-grid-view div[measure="Price"] {
  background-color: #B2DBBF;
}

Live example

3.c. Adding all the semantic info to cell builder attributes

This JSFiddle example demonstrates another way of adding all the semantic info to cell builder attributes Live example.

This sample takes into account the position of the hierarchies in rows and columns.

Example 4. Customizing cells based on conditional formatting

It is also possible to apply customization to a cell if the condition of the conditional formatting is true for that cell.

The CellDataObject has the conditions property containing a list of the conditional formatting ids that are true for this cell.

Check the JSFiddle example that shows how to style the entire row if the condition is true for at least one cell in this row Live example.

Example 5. Representing numbers by icons

This example demonstrates how to replace cell values with the images depending on which interval the value belongs to: high, middle, and so forth Live example.

Example 6. Adding hyperlinks

This case describes adding links to all the countries in the report. It can be done through the text property of the cell builder Live example.

The possibilities of customizeCell are not limited by the above cases. This API call covers many variants of visualization. To learn more about the customizeCell function and the CellDataObject, see the API documentation:

What’s next?

You may be interested in the following articles: