Customize Fields in PivotEngine

Fields contain information that allow the PivotEngine to summarize raw data. They are represented by the PivotField class and have properties that allow you to customize where the data comes from as well as how it is summarized and presented.

The main properties of the PivotField class are:

• binding: Determines which property of the raw data objects is represented by the field.
• header: Determines the title used to show the summary results for the field.
• format: Determines how the summary results for the field are formatted or used to break up the data.
• aggregate: Determines how the raw data is aggregated in the output summary. Possible values include sum, count, average, max, min, etc.

Format

The PivotField.format property determines how raw values are formatted for display (measure fields) and also for breaking values into groups (dimension fields).

This example shows how changing the format property of a dimension fields affects data grouping. If the field format shows the quarter, the data is grouped by quarter. If it shows the month, the data is grouped by month.

// customize the "Period" field
let fld = ng.fields.getField('Period');
fld.format = 'yyyy';

ShowAs

The PivotField.showAs property allows you to specify common calculations to be performed on the field value before it is displayed.

Options for this property are defined by the ShowAs enumeration and include differences between the value and the one in the previous row or column, percentages over the row, column, or grand total, and running totals.

// customize the "Period" field
let fld = ng.fields.getField('Period');
fld.showAs = wjOlap.ShowAs.PctCol;

ShowAs enums are outlined here in the API

Sort

The PivotEngine automatically sorts dimension (row and column) fields when it generates data summaries. It does not sort measure (value) fields by default.

Refer to the Sorting Fields topic for more information about sorting.

HTML Content

Use the PivotField's isContentHtml property to render fields that contain HTML instead of plain text.

ng.fields.getField('Buyer').isContentHtml = true;
ng.fields.getField('Type').isContentHtml = true;


// single data object
...
    {
        date: new Date(yr, 0, 1),
        buyer: '<span class="initial">M</span>om',
        type: '<span class="initial">F</span>uel',
        amount: 74
    },
...

The Buyer and type fields are strings, but they contain HTML tags, so the thery are capable of being rendered as HTML in the PivotGrid.

Calculated Fields

In some cases, you may want to summarize calculated values instead of raw values.

You can do this by adding a calculated value to the raw data items, or by adding a custom field with the getValue property set to a function that calculates the value for the raw item.

This example demonstrates the second approach. It adds two calculated fields to a PivotEngine:

1. Range: This is a calculated dimension field that contains the value "High", "Low", or "Medium" based on the value of the "sales" property.
2. Conversion: This is a calculated measure field that contains the ratio between sales and downloads.