Parameters

There are two main functions defined in pivot.coffee: pivot() and pivotUI() (see below). Please note that pivot() and pivotUI() do not accept the same parameters, and although certain sets of parameters will be parsed similarly by both, this is not generally true. See the FAQ. If you want to use pivotUI() without the UI, you may use the showUI parameter.

pivot(input [,options [,locale]])

pivot() will inject an HTML table into the object onto which it is called, which will summarize input according to options.

• input is an array of objects, an array of arrays, a function or a jQuery object referencing a table (see documentation and examples: array, function, table).
• options is an object as described below.
• locale is a string defaulting to en which controls the default locale for things like number formatting and error messages. Regardless of this setting, you can still override the default aggregators (which control number formatting) and error message strings. If this is set to something other than en you will have to load a locale-specific 'language pack' which creates this locale object before calling pivotUI(). See Localization for more info.

options object for pivot()

Key	Type	Default value	Description
rows	array of strings	[]	array of attribute names to use as rows
cols	array of strings	[]	array of attribute names for use as columns
aggregator	function	$.pivotUtilities .aggregators["Count"]()	constructor for an object which will aggregate results per cell (see documentation)
aggregatorName	string	"Count"	Name of the aggregator, used for display purposes in some renderers
renderer	function	table()	generates output from pivot data structure (see documentation)
rowOrder	string	"key_a_to_z"	the order in which row data is provided to the renderer, must be one of "key_a_to_z", "value_a_to_z", "value_z_to_a", ordering by value orders by row total
colOrder	string	"key_a_to_z"	the order in which column data is provided to the renderer, must be one of "key_a_to_z", "value_a_to_z", "value_z_to_a", ordering by value orders by column total
derivedAttributes	object of functions	{}	object to define derived attributes (see documentation)
dataClass	function	$.pivotUtilities.PivotData	Constructor for the data class to be built and passed to the Renderer (should be a subclass of the default)
filter	function	function(){return true;}	called on each record, returns false if the record is to be excluded from the input before rendering or true otherwise
sorters	object or function	{}	accessed or called with an attribute name and can return a function which can be used as an argument to array.sort for output purposes. If no function is returned, the default sorting mechanism is a built-in "natural sort" implementation. Useful for sorting attributes like month names, see example 1 and example 2.
rendererOptions	object	{}	object passed through to renderer as options. See Renderers and Optional Extra Renderers for details.
localeStrings	object	en strings	locale-specific strings for error messages (see locale parameter below)

pivotUI(input [,options [,overwrite [,locale]]])

pivotUI() will draw a UI and then call pivot(). It will call pivot() every time the UI is changed via a drag'n'drop or an aggregator selection. The options object lets you set up the UI itself in terms of what visualization aggregators and effects are offered, and it lets you prepopulate the various options as well.

• input is an array of objects, an array of arrays, a function or a jQuery object referencing a table (see documentation and examples: array, function, table).
• options is an object as described below.
• overwrite is a boolean defaulting to false which controls what happens if this function is called repeatedly on the same element. If set to true, the options object overwrites the current state of the UI. If set to false, only the input data set changes, and the state of the UI remains the same, unless this is the first call, at which point the UI will be set to the options.
• locale is a string defaulting to en which controls the default locale for things like number formatting and error messages. Regardless of this setting, you can still override the default aggregators (which control number formatting) and error message strings. If this is set to something other than en you will have to load a locale-specific 'language pack' which creates this locale object before calling pivotUI(). See Localization for more info.

options object for pivotUI()

Key	Type	Default value	Description
rows	array of strings	[]	attribute names to prepopulate in row area
cols	array of strings	[]	attribute names to prepopulate in cols area
vals	array of strings	[]	attribute names to prepopulate in vals area (gets passed to aggregator generating function)
aggregators	object of functions	$.pivotUtilities.aggregators	dictionary of generators for aggregation functions in dropdown (see documentation)
aggregatorName	string	first key in aggregators	aggregator to prepopulate in dropdown i.e. key to aggregators object
renderers	object of functions	$.pivotUtilities.renderers	dictionary of rendering functions (see documentation)
rendererName	string	first key in renderers	renderer to prepopulate in dropdown, i.e key to renderers object
rowOrder	string	"key_a_to_z"	the order in which row data is provided to the renderer, must be one of "key_a_to_z", "value_a_to_z", "value_z_to_a", ordering by value orders by row total
colOrder	string	"key_a_to_z"	the order in which column data is provided to the renderer, must be one of "key_a_to_z", "value_a_to_z", "value_z_to_a", ordering by value orders by column total
derivedAttributes	object of functions	{}	defines derived attributes (see documentation)
dataClass	function	$.pivotUtilities.PivotData	Constructor for the data class to be built and passed to the Renderer (should be a subclass of the default)
filter	function	function(){return true;}	called on each record, returns false if the record is to be excluded from the input before rendering or true otherwise
inclusions	object of arrays of strings	{}	object whose keys are attribute names and values are arrays of attribute values which denote records to include in rendering; used to prepopulate the filter menus that appear on double-click (overrides exclusions below)
exclusions	object of arrays of strings	{}	object whose keys are attribute names and values are arrays of attribute values which denote records to exclude from rendering; used to prepopulate the filter menus that appear on double-click
hiddenAttributes	array of strings	[]	contains attribute names to omit from the UI
hiddenFromAggregators	array of strings	[]	contains attribute names to omit from the aggregator arguments dropdowns
hiddenFromDragDrop	array of strings	[]	contains attribute names to omit from the drag'n'drop portion of the UI
sorters	object or function	{}	accessed or called with an attribute name and can return a function which can be used as an argument to array.sort for output purposes. If no function is returned, the default sorting mechanism is a built-in "natural sort" implementation. Useful for sorting attributes like month names, see example 1 and example 2.
onRefresh	function	function(){}	called upon renderer refresh with an object representing the current UI settings (see example)
menuLimit	integer	50	maximum number of values to list in the double-click menu
autoSortUnusedAttrs	boolean	false	controls whether or not unused attributes are kept sorted in the UI
unusedAttrsVertical	boolean or integer	85	controls whether or not unused attributes are shown vertically instead of the default which is horizontally. true means always vertical, false means always horizontal. If set to a number (as is the default) then if the attributes' names' combined length in characters exceeds the number then the attributes will be shown vertically
showUI	boolean	true	controls whether the drag'n'drop UI is shown. Set to false to emulate the behaviour of pivot() with the pivotUI() signature.
rendererOptions	object	{}	passed through to renderer as options. See Renderers and Optional Extra Renderers for details.
localeStrings	object	en strings	locale-specific strings for UI display (see locale parameter below)