Parameters

Nicolas Kruchten edited this page Jun 18, 2018 · 47 revisions

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)
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.