APIs

WebPivotTable exposes a rich JavaScript API directly on the <web-pivot-table> DOM element. You can call any method below after obtaining a reference to the element.

How to Call APIs

const wpt = document.getElementById('wpt');
// or
const wpt = document.querySelector('web-pivot-table');

// Call any method directly
await wpt.setWptFromCsvUrl('https://example.com/data.csv');

All methods are available as soon as the element is connected to the DOM. Async methods (data loading, locale switching) return Promises.

Multi-instance support: Each <web-pivot-table> element has its own isolated state. Methods always operate on the element they are called on.

Source Methods

Methods for loading data from various sources into the pivot table.

setWptFromDataArray

Load source data from in-memory arrays and generate the pivot.

await wpt.setWptFromDataArray(attrArray, dataArray, url?, type?);

Notes:

• This is the core API for loading data. All other setWptFrom* methods use it internally.
• You can load data from any source (SQL databases, REST APIs, etc.) by formatting it as attrArray + dataArray.

getSourceFromDataArray

Parse arrays into a source object without generating the pivot.

const source = await wpt.getSourceFromDataArray(attrArray, dataArray, url?, type?);

Parameters are the same as setWptFromDataArray. Returns a source object.

setWptFromCsvUrl

Load a CSV file from a URL and generate the pivot.

await wpt.setWptFromCsvUrl(url, delimiter?);

getSourceFromCsvUrl

Parse a CSV URL into a source object without generating the pivot.

const source = await wpt.getSourceFromCsvUrl(url, delimiter?);

setWptFromExcelUrl

Load an Excel file from a URL and generate the pivot.

await wpt.setWptFromExcelUrl(url, delimiter?);

getSourceFromExcelUrl

Parse an Excel URL into a source object without generating the pivot.

const source = await wpt.getSourceFromExcelUrl(url, delimiter?);

setWptFromWebService

Load data from a Web Service URL. The service must return JSON in the format { attrArray: [], dataArray: [] }.

await wpt.setWptFromWebService(url);

Notes:

• The web service should return:

  {
    "attrArray": ["col1", "col2", "col3"],
    "dataArray": [["a", "b", 100], ["c", "d", 200]]
  }
  

• This is ideal for accessing SQL databases or other backend data stores.

getSourceFromWebService

Parse a web service response into a source object without generating the pivot.

const source = await wpt.getSourceFromWebService(url);

setWptFromGoogleSpreadSheet

Load data from a published Google Spreadsheet URL and generate the pivot.

await wpt.setWptFromGoogleSpreadSheet(url);

getSourceFromGoogleSpreadSheet

Parse a Google Spreadsheet into a source object without generating the pivot.

const source = await wpt.getSourceFromGoogleSpreadSheet(url);

setWptFromOlapCube

Connect to an OLAP cube via XMLA and generate the pivot.

await wpt.setWptFromOlapCube(olapData);

olapData format:

{
  xmlaUrl: "https://your-olap-server/xmla",
  dataSourceInfo: "Provider=MSOLAP;Data Source=localhost;",
  catalog: "Adventure Works DW",
  cubeName: "Adventure Works"
}

getSourceFromOlapCube

Retrieve OLAP cube fields without generating the pivot.

const source = await wpt.getSourceFromOlapCube(olapData);

setWptFromWptUrl

Load a .wpt file from a URL. This restores saved pivot state including source data, pivot field selections, and options.

await wpt.setWptFromWptUrl(url);

setWptFromLocalFile

Load a local file (from a file input or drag-and-drop). Supports CSV, Excel, and WPT file types.

await wpt.setWptFromLocalFile(file, type);

setWpt

Load a pre-saved WPT JSON object directly.

wpt.setWpt(wptObject);

generateWptString

Export the current pivot state as a JSON string.

const wptString = wpt.generateWptString(ignoreData?);

Returns: A JSON string in WPT format.

generateWptJSON

Export the current pivot state as a JSON object.

const wptObj = wpt.generateWptJSON(ignoreData?);

Returns: A JSON object in WPT format.

getSourceObject

Get the current internal source state object.

const source = wpt.getSourceObject();

Returns: The source state object containing data, fields, lookups, mode, type, etc.

setSourceObject

Set the internal source state directly.

wpt.setSourceObject(source);

System Methods

Methods for controlling the UI behavior and state.

setLocale

Change the UI language. If localeFilePath is configured, the locale file is fetched automatically.

await wpt.setLocale(locale);

See Internationalization for available locales and configuration.

setOptions

Merge options into the current configuration. Changes take effect immediately.

wpt.setOptions(options);

Examples:

// Set locale file path
wpt.setOptions({ localeFilePath: '/wpt-locales/' });

// Customize toolbar visibility
wpt.setOptions({ toolbar: { showNewWpt: false, showSaveWpt: false } });

// Register custom handlers
wpt.setOptions({ customHandlers: { connectSource: true, saveWpt: true } });

See Options for the full list of available options.

getOptions

Get the current options object.

const opts = wpt.getOptions();

Returns: The current options object.

showControlPanel

Show the control panel (pivot fields, chart/grid options tabs).

wpt.showControlPanel();

hideControlPanel

Hide the control panel.

wpt.hideControlPanel();

toggleControlPanel

Toggle the control panel visibility.

wpt.toggleControlPanel();

openDialog

Open a built-in dialog programmatically.

wpt.openDialog({ type: 'CONNECT_SOURCE' });

Available dialog types:

• CONNECT_SOURCE - Data source connection dialog
• OPEN_WPT - Open a .wpt file
• SAVE_WPT - Save as .wpt file
• EXPORT - Export to PDF/image
• SHEET_FIELD_SETTING - Field settings (sort, filter, format)
• SHEET_VALUE_FIELD_SETTING - Value field aggregation settings
• SHEET_CALCULATED_FIELD - Calculated field editor
• SHEET_MDX_STATEMENT - MDX statement viewer (OLAP)
• SOURCE_FIELD_SETTING - Source field settings
• ABOUT_ME - About dialog

closeDialog

Close any currently open dialog.

wpt.closeDialog();

reset

Clear all data and reset the component to its initial state.

wpt.reset();

refresh

Re-generate the pivot data from the current source and field selections.

wpt.refresh();

loadingMessage

Show a loading overlay with a custom message.

wpt.loadingMessage('Processing data...');

clearMessage

Clear any loading or error overlay.

wpt.clearMessage();

errorMessage

Show an error overlay.

wpt.errorMessage('Failed to load data');

Sheet Methods

Methods for manipulating pivot field layout.

swapAxis

Swap row fields and column fields.

wpt.swapAxis();

clearAllPivot

Remove all fields from rows, columns, filters, and values areas.

wpt.clearAllPivot();

clearAllFilters

Clear all applied filters while keeping field placements.

wpt.clearAllFilters();

Element-Level Methods

Additional methods defined directly on the <web-pivot-table> element.

getData

Get the raw source data rows.

const rows = wpt.getData();

setData

Set data rows directly. Dispatches a wpt:data event.

wpt.setData(rows);

getLocale

Get the current locale code.

const locale = wpt.getLocale(); // e.g. "en"

resize

Trigger a resize recalculation. Call this after the container size changes programmatically.

wpt.resize();

setSize

Set the element's width and height.

wpt.setSize(800, 600);      // pixels
wpt.setSize('100%', '80vh'); // CSS values

getSize

Get the current rendered size.

const { width, height } = wpt.getSize();

showLoading / hideLoading

Manually control the loading overlay.

wpt.showLoading();
// ... do work ...
wpt.hideLoading();

version

Read-only property returning the current version string.

console.log(wpt.version); // "7.0.0"

Events

The component dispatches DOM CustomEvents on the <web-pivot-table> element. Use standard addEventListener to listen:

wpt.addEventListener('SAVE_WPT', (e) => {
  console.log('Save requested:', e.detail);
});

Application Events

Important: To receive these events, you must first enable the corresponding custom handler so the default built-in dialog is suppressed:

wpt.setOptions({
  customHandlers: {
    connectSource: true,
    openWpt: true,
    saveWpt: true,
    drillThrough: true,
  }
});

Internal Events

Custom Handlers Pattern

Override default behaviors by providing customHandlers in options. When a custom handler is enabled, the component emits the corresponding DOM event instead of opening its built-in dialog.

wpt.setOptions({
  customHandlers: {
    connectSource: true,  // Suppress default ConnectSource dialog
    openWpt: true,        // Suppress default OpenWpt dialog
    saveWpt: true,        // Suppress default SaveWpt dialog
    drillThrough: true,   // Suppress default DrillThrough modal
  }
});

// Then listen for the events and handle them yourself
wpt.addEventListener('CONNECT_SOURCE', () => {
  // Show your own data source picker
});

wpt.addEventListener('SAVE_WPT', (e) => {
  // Save to your own backend
  fetch('/api/save', { method: 'POST', body: JSON.stringify(e.detail) });
});