PivotTable
Runtime representation of a pivot table. Wraps the JSF PivotTable definition and provides methods for computing layout, writing to sheet cells, and looking up values for GETPIVOTDATA.
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new PivotTable(): PivotTable;Returns
Section titled “Returns”PivotTable
Properties
Section titled “Properties”cacheIndex
Section titled “cacheIndex”readonly cacheIndex: number;Position in the owning manager’s _caches array, or -1 when unbound. Used only for
serialization correlation; runtime lookups go through the attached cache directly. Readonly
because the invariant “matches manager._caches.indexOf(_cache)” must be updated atomically
with the cache attachment.
Accessors
Section titled “Accessors”Get Signature
Section titled “Get Signature”get cache(): PivotCache | null;The live cache this pivot table computes from (possibly shared), or null before it is bound.
Returns
Section titled “Returns”PivotCache | null
colFieldIndices
Section titled “colFieldIndices”Get Signature
Section titled “Get Signature”get colFieldIndices(): readonly number[];Column field indices with negative placeholders (e.g. -2 for “Values”) filtered out.
Returns
Section titled “Returns”readonly number[]
colFields
Section titled “colFields”Get Signature
Section titled “Get Signature”get colFields(): readonly PivotField[];Returns
Section titled “Returns”readonly PivotField[]
colGrandTotals
Section titled “colGrandTotals”Get Signature
Section titled “Get Signature”get colGrandTotals(): boolean;Returns
Section titled “Returns”boolean
colRoles
Section titled “colRoles”Get Signature
Section titled “Get Signature”get colRoles(): PivotColRole[];Column-axis style roles — the rowRoles mirror for the column axis, as 0-based column
offsets from the left of the output area. The renderer positions a declared table style’s
firstSubtotalColumn region on these.
The column axis has no outline/separator placement modes (column subtotals always sit
right-of-group), so every entry is a subtotal; there is no column subheading. A column
subtotal materializes once per displayed data field — the data fields multiply the columns,
except in the hideValuesRow collapse where they show as a single block, and in the row-axis
Values (onRows) layout where they multiply rows instead — so this emits one role per
(subtotal, displayed data-field column), at the same columns the cell emitter writes them to:
the positions come from the emitter’s own subtotalCol closure (see _refRelativeEmitter).
Verified against excel-test/pivot-valuesouter-colsubtotal-verify and
excel-test/pivot-values-inner-position.
Returns
Section titled “Returns”colStride
Section titled “colStride”Get Signature
Section titled “Get Signature”get colStride(): number;Columns each column-header group occupies in the computed output: normally
one per data field, but collapses to 1 when the location lacks slack for
the synthetic Values row (Excel’s hideValuesRow="1" signature: multi-data
- col-axis + no slack between
firstHeaderRowandfirstDataRow). Used by the cell emitter for column position arithmetic — except the row-axis Values layout, which overrides the column stride to 1 and expands rows by the data-field count instead (see resolveRowAxisStrides). Degenerate case (no data fields) yields 1.
Returns
Section titled “Returns”number
dataFields
Section titled “dataFields”Get Signature
Section titled “Get Signature”get dataFields(): readonly PivotDataField[];The data fields (a fresh deep copy on every read — elements too, since the readonly
array typing would not stop element mutation), defaulting to empty when absent. Mutations
belong on jsf.dataFields (followed by clearLayout), never here.
Returns
Section titled “Returns”readonly PivotDataField[]
fields
Section titled “fields”Get Signature
Section titled “Get Signature”get fields(): readonly PivotField[];Returns
Section titled “Returns”readonly PivotField[]
layoutForm
Section titled “layoutForm”Get Signature
Section titled “Get Signature”get layoutForm(): "outline" | "compact" | "tabular";The report layout form, read from the fields on the row and column axes: the form is recorded
per field and the layout renders from those flags, while the root compact and outline are
the defaults for a field placed later. Fields that disagree report the least tabular form among
them, compact before outline. A definition with no axis field reports the root’s form.
Returns
Section titled “Returns”"outline" | "compact" | "tabular"
location
Section titled “location”Get Signature
Section titled “Get Signature”get location(): PivotTableLocation;Returns
Section titled “Returns”PivotTableLocation
measures
Section titled “measures”Get Signature
Section titled “Get Signature”get measures(): readonly PivotMeasure[];Returns
Section titled “Returns”readonly PivotMeasure[]
missingCaption
Section titled “missingCaption”Get Signature
Section titled “Get Signature”get missingCaption(): string | undefined;Returns
Section titled “Returns”string | undefined
Get Signature
Section titled “Get Signature”get name(): string;Returns
Section titled “Returns”string
pageArea
Section titled “pageArea”Get Signature
Section titled “Get Signature”get pageArea(): | PivotPageArea | null;Geometry of the page-field (report filter) area, or null when the pivot has no page fields.
The renderer (mondrian) reads this to find the filter cells — they sit above and outside
ref, so its per-cell pivot index built from ref never reaches them — e.g. to position a
declared table style’s pageFieldLabels / pageFieldValues regions.
The geometry is purely positional: when the anchor sits too high for all the rows to fit
(a hand-built JSF; Excel reserves the rows on creation), the reported region can extend above
the top of the sheet, and getCellWrites omits the cells that fall there. Callers clip to
the sheet.
Returns
Section titled “Returns”| PivotPageArea
| null
pageFields
Section titled “pageFields”Get Signature
Section titled “Get Signature”get pageFields(): readonly PivotField[];Returns
Section titled “Returns”readonly PivotField[]
Get Signature
Section titled “Get Signature”get ref(): string;The A1-style range covering the pivot’s output area.
Returns
Section titled “Returns”string
rowFieldIndices
Section titled “rowFieldIndices”Get Signature
Section titled “Get Signature”get rowFieldIndices(): readonly number[];Row field indices with negative placeholders (e.g. -2 for “Values”) filtered out.
Returns
Section titled “Returns”readonly number[]
rowFields
Section titled “rowFields”Get Signature
Section titled “Get Signature”get rowFields(): readonly PivotField[];Returns
Section titled “Returns”readonly PivotField[]
rowGrandTotals
Section titled “rowGrandTotals”Get Signature
Section titled “Get Signature”get rowGrandTotals(): boolean;Returns
Section titled “Returns”boolean
rowRoles
Section titled “rowRoles”Get Signature
Section titled “Get Signature”get rowRoles(): PivotRowRole[];Style roles of the output rows that are not plain data rows: the row axis’s subheading
(group label) and subtotal rows, as 0-based row offsets from the top of the output area.
The renderer (mondrian) reads this to position a declared table style’s
firstRowSubheading / firstSubtotalRow regions. Blank separator rows
(insertBlankRow="1") carry no role; the renderer styles them as plain body rows.
In the row-axis Values (dataOnRows) layout each aggregate subtotal spans one sheet row per
data field, so it contributes that many entries — regardless of its role, since an
outline-above aggregate (Values nested at a non-innermost row position) classifies as a
subheading yet still expands (see below). Only the separator and blank rows stay single-row
(the positioner collapses their data-field offset).
A row is a subheading when it is the group’s label row, and a subtotal only when it is a
dedicated subtotal row below its group. Excel styles the above-group row (outline/compact
“subtotal at top”, where the group label and its subtotal share one row) as a subheading, not a
subtotal — verified in Excel on PivotStyleLight16 (an above-group row shows no top border
and no fill, the firstRowSubheading look, where firstSubtotalRow would add a top border).
So outlineAbove rows classify as subheading alongside the bare separator rows; only
below-group rows (outlineAbove === false) are subtotal.
Returns
Section titled “Returns”Get Signature
Section titled “Get Signature”get sheet(): string;Returns
Section titled “Returns”string
showMissing
Section titled “showMissing”Get Signature
Section titled “Get Signature”get showMissing(): boolean;Returns
Section titled “Returns”boolean
Get Signature
Section titled “Get Signature”get style(): PivotTableStyle | undefined;Returns
Section titled “Returns”PivotTableStyle | undefined
Methods
Section titled “Methods”addMeasure()
Section titled “addMeasure()”addMeasure(field, options?): PivotMeasure;Parameters
Section titled “Parameters”options?
Section titled “options?”aggregation?
Section titled “aggregation?”string
Returns
Section titled “Returns”Throws
Section titled “Throws”field belongs to another pivot table, or a cache refresh removed it
containsOutput()
Section titled “containsOutput()”containsOutput(row, col): boolean;Check whether (row, col) falls within this pivot table’s output area.
Parameters
Section titled “Parameters”number
number
Returns
Section titled “Returns”boolean
getDataValue()
Section titled “getDataValue()”getDataValue( dataFieldName, criteria, options?): | CellValue | PivotLookupError;Look up an aggregated value by data field name and field/item criteria (GETPIVOTDATA). A null name takes the pivot table’s first data field, as GETPIVOTDATA’s Excel-97 text form does when it names no data field.
Parameters
Section titled “Parameters”dataFieldName
Section titled “dataFieldName”string | null
criteria
Section titled “criteria”[string, CellValue][]
options?
Section titled “options?”caseSensitiveFieldNames?
Section titled “caseSensitiveFieldNames?”boolean
Returns
Section titled “Returns”| CellValue
| PivotLookupError
getOutputBounds()
Section titled “getOutputBounds()”getOutputBounds(): | Readonly<OutputBounds> | null;Compute and cache the output bounds from the materialized cell writes. Unlike ref, which is
only rewritten when a refresh/repaint runs and so can lag a source-data change, these bounds
always reflect the current data. Returns null for malformed refs. Every call returns a fresh
copy: the bounds behind containsOutput, PivotManager.findAt, and the pivot write guards
must not be reachable through the return value.
Returns
Section titled “Returns”| Readonly<OutputBounds>
| null
getProtectedBounds()
Section titled “getProtectedBounds()”getProtectedBounds(): | Readonly<OutputBounds> | null;The pivot’s full protected footprint: its output area (getOutputBounds) extended to
cover the page-field (report-filter) area, which materializes ABOVE the anchor (and, when the
page fields wrap into multiple column-groups, to the RIGHT of the body) and outside ref (see
PivotPageArea). Identical to getOutputBounds when the pivot has no page fields.
The range/structural write guards (clearCells, moveCells, insert/delete cells, insert/delete
rows or columns) use this rather than getOutputBounds so they agree with the single-cell write
guard, which blocks writes anywhere in the per-sheet R-tree footprint (fed from
boundsOfWrites, which already covers the page-field caption cells). Without it, a range or
structural edit overlapping only the page area would slip past while a direct write to the same
cell is blocked.
Body-bounds consumers keep using getOutputBounds: syncLayoutToJSF’s ref excludes the page
area by Excel convention, and the adopted-output export scrub deliberately reads only the body.
Returns
Section titled “Returns”| Readonly<OutputBounds>
| null
matchLookupName()
Section titled “matchLookupName()”matchLookupName(name): PivotLookupName | null;What a name names in this pivot table (see matchLookupName), or null when it names nothing in it. A pivot table with no cache names nothing.
Parameters
Section titled “Parameters”string | number
Returns
Section titled “Returns”PivotLookupName | null
rename()
Section titled “rename()”rename(newName): void;Parameters
Section titled “Parameters”newName
Section titled “newName”string
Returns
Section titled “Returns”void
Throws
Section titled “Throws”the new name is taken on the same sheet (at update commit)
Throws
Section titled “Throws”the new name is empty
setGrandTotals()
Section titled “setGrandTotals()”setGrandTotals(axis, enabled): void;Parameters
Section titled “Parameters”"col" | "row"
enabled
Section titled “enabled”boolean
Returns
Section titled “Returns”void
setLayoutForm()
Section titled “setLayoutForm()”setLayoutForm(form): void;Parameters
Section titled “Parameters”"outline" | "compact" | "tabular"
Returns
Section titled “Returns”void
setMissingCaption()
Section titled “setMissingCaption()”setMissingCaption(caption): void;Parameters
Section titled “Parameters”caption
Section titled “caption”string | undefined
Returns
Section titled “Returns”void
setShowMissing()
Section titled “setShowMissing()”setShowMissing(show): void;Parameters
Section titled “Parameters”boolean
Returns
Section titled “Returns”void