Skip to content
RevoGrid [Pro]

Plugin Lifecycle

PivotPlugin is the runtime layer that turns the direct grid.pivot config into rendered rows, generated columns, and grouped state. Understanding its lifecycle helps you persist user choices, avoid conflicting updates, and reason about when Pivot owns the grid payload.

Activation

Section titled “Activation”
Interactive example

Plugin lifecycle

Capture source/columns/grouping/pinned totals, apply config, clear and restore

The example loads when visible.

Pivot activates when:

  • PivotPlugin is present in grid.plugins
  • grid.pivot contains a config

The plugin observes the direct pivot property and reapplies Pivot whenever the config changes. additionalData.pivot updates are still supported for compatibility.

What Happens On Apply

Section titled “What Happens On Apply”

When applyPivot runs:

  1. the plugin captures the original source, columns, grouping, and pinned-bottom rows on first activation
  2. it decides whether to use the client or server execution path
  3. it generates or loads Pivot rows and columns
  4. it writes those generated structures back to the grid

This means Pivot is temporarily the owner of the rendered grid payload.

Client Path

Section titled “Client Path”

In client mode:

  • raw grid source is read from the captured original data
  • createPivotData materializes Pivot rows
  • pivotColumns generates the column tree
  • grand total rows are moved to pinnedBottomSource

Server Path

Section titled “Server Path”

In server mode:

  • the plugin resolves a PivotEngineAdapter
  • it builds a PivotLoadRequest
  • it aborts any stale in-flight remote request
  • only the latest response is allowed to update the grid

This is the last-write-wins behavior that protects the UI when filters or layouts change quickly.

Configurator Integration

Section titled “Configurator Integration”

If hasConfigurator is enabled, the plugin renders the configurator and wires its updates back into the Pivot state. Each configurator update:

  • emits pivot-config-update
  • applies the updated config unless the event was prevented

pivot-config-update

Section titled “pivot-config-update”

This is a synchronous, cancelable proposal before execution. Call event.preventDefault() to veto it. A proposal can later fail or be superseded; persisting its payload as an accepted report saves uncommitted intent.

Subscribe to the attached authoring facade for status/history and persist newly ready revisions:

const authoring = pivotPlugin.getAuthoringController();
let savedRevision = -1;
const veto = (event: Event) => {
  if (!applicationAllowsChanges()) event.preventDefault();
};
grid.addEventListener('pivot-config-update', veto);
const unsubscribe = authoring.subscribe(() => {
  const snapshot = authoring.getSnapshot();
  if (snapshot.status === 'ready' && snapshot.revision !== savedRevision) {
    savedRevision = snapshot.revision;
    persistAccepted(snapshot.report); // Session descriptors may require runtime bindings for portable export.
  }
});
// On shell cleanup:
unsubscribe();
grid.removeEventListener('pivot-config-update', veto);

The existing pivot-model-changed event and getRuntimeSnapshot() describe committed analytical output. The authoring facade also describes pending/error state, retained reports and Undo/Redo. Loading/error never claims pending pixels are committed. Rapid remote commands compose on pending intent; superseded requests cannot overwrite the latest result. Synchronous framework echoes of accepted configs need not create a second owner or a persistence feedback loop.

Reapplication Triggers

Section titled “Reapplication Triggers”

Pivot recalculates when:

  • grid.pivot changes
  • additionalData.pivot changes
  • the underlying non-Pivot source changes
  • the underlying non-Pivot columns change
  • row drill-down or column collapse state changes through plugin-managed interactions

The plugin intentionally avoids treating already-generated Pivot rows or columns as new base inputs.

Clearing Pivot

Section titled “Clearing Pivot”

clearPivot():

  • aborts any remote load
  • removes managed Pivot state
  • restores the original source, columns, grouping, and pinned-bottom rows

Removing grid.pivot has the same practical effect. Removing additionalData.pivot also clears Pivot when that path is the active source.

The stable attached authoring facade reports inactive before activation and after clear. Re-enable reuses it with a newer global revision. Destroy reports terminal destroyed, cancels pending work and clears subscriptions. Its restricted commands cannot replace source/runtime or dispose the plugin; those remain host/report-import authority.

See Custom Integrations for the exact checked constructor, toolbar and cleanup modules.

Best Practices

Section titled “Best Practices”
  • Treat direct grid.pivot / framework pivot binding as the durable state you own.
  • Use pivot-config-update for synchronous admission and ready authoring snapshots for committed persistence.
  • Do not manually overwrite grid.source or grid.columns with Pivot active unless you mean to replace the base data and trigger a reapply.
Section titled “Related Guides”