Renderers

The renderer parameter to the pivot() function defines what the user will actually see. It takes as parameters a PivotData object and an options object and returns a jQuery object which pivot() will inject into the DOM at the right place.

The renderers parameter to the pivotUI() function is a dictionary of such functions.

The renderer mechanism is fairly generic, so it should be possible to write some fairly interesting renderers in a variety of frameworks. PivotTable.js ships with a Table renderer that has some neat extensions for visualization such as Heatmaps and Table Barcharts, as well as Optional Extra Renderers which can produce C3/D3 charts and/or export data to TSV format.

rendererOptions

The rendererOptions parameter of pivot() and pivotUI() is passed to all renderers, and different renderers read different keys in this object. See below for the built-in renderers, and the relevant sections for the Plotly, C3 and other renderers.

Built-in renderers

Some built-in renderers (Table, Table Barchart, Table Heatmaps) are available under $.pivotUtilities.renderers

Table rendererOptions

The Table renderers accept a table key in the rendererOptions object.

This object can take boolean rowTotals and colTotals keys which both default to true and control the rendering of row- and column-totals. Grand totals are only shown when both are true. Note that even when set to false, totals will be shown if doing otherwise would cause the rendering of an empty table.

Additionally, a clickCallback key is read from this object, and it should be a function that is to be called when cells are clicked on, with signature (e, value, filters, pivotData). e is the underlying click event, value is the cell value, and filters are meant to be passed to pivotData.forEachMatchingRecord(filters, callback) to iterate over each record that contributed to that cell's value, firing callback for each one. There is an example here: https://pivottable.js.org/examples/mps_prepop.html

Table Heatmap rendererOptions

The Table Heatmap renderers accept a heatmap key in the rendererOptions object in addition to the table one listed above. A single key colorScaleGenerator is read from this object, and it should be a function that accepts an array of values and returns a function which returns a CSS colour for any value passed in. Basically a D3-style color-map. There is an example here: https://pivottable.js.org/examples/montreal_2014.html

The PivotData object

The PivotData object, which is passed into the renderer function, is the data model for PivotTable.js. It essentially wraps a tree of aggregator objects and provides some accessors to list all the rowKey and colKey values in the tree, and some other information useful to generate views of data:

• getAggregator(rowKey, colKey): returns the aggregator object at that point in the tree. Passing in the empty arrary [] for either or both parameter will return a total aggregator: row totals by passing in [] for colKey, column totals by passing in [] for rowKey and an overall total by passing in [] for both parameters.
• getColKeys(), getRowKeys(): return arrays of values that can be passed into getAggregator() above. These values are arrays of attribute-values from the underlying data set, so these functions return arrays of arrays of strings.
• colVars, rowVars: these are arrays of attribute-names from the underlying data set which define the PivotData structure, i.e. the values that were passed into pivot() as options.cols and options.rows
• forEachMatchingRecord(criteria, callback): calls callback(record) once for each record of the filtered original input which matches the criteria, which is an object of the form {<attribute>: <value>, <attribute>: <value>...}

Once a renderer has queried out an aggregator object, it can get the value by calling value(). See the definition of Aggregators for more information.