Javascript API
This page documents the JavaScript API for WooCommerce Product Table. Choose the section that matches your table's frontend.
- Current frontend (DataViews)
- Moving from legacy events
- Legacy frontend (DataTables)
- Cart events for both frontends
Current frontend (DataViews)
The current frontend uses native DOM events and a DataViewManager instance for each table. The legacy .wcpt events do not fire on this frontend.
The table instance
The wptDataViewReady event provides the table instance in event.detail.table. You can use the following methods:
getId(): returns the instance ID. This is not the saved table ID from the table builder.getContainer(): returns the table's outer container as an HTML element.getConfig(): returns the current configuration.on(eventName, handler): adds an instance-event listener.off(eventName, handler): removes a listener. Pass the same handler function that you used withon().
To find existing instances, use window.Barn2DataViews.getAllInstances(), or window.Barn2DataViews.getInstance(id) with an instance ID.
Events
Listen for wptDataViewReady with document.addEventListener(). Listen for the other events below with table.on(). Instance-event handlers receive the payload directly, rather than a DOM event.
wptDataViewReady
WooCommerce Product Table dispatches this native event on document after creating a table instance.
Event details: event.detail.table is the DataViewManager instance.
The instance is available at this point, but its rows may still be loading or rendering. Use contentRendered for code that needs the table content.
contentRendered
Fires when table or grid content is present in the DOM. This includes the initial render and later updates after searching, filtering, sorting or pagination. Responsive changes and virtual scrolling can also trigger it.
The handler receives an object with:
container: the HTML element containing the rendered content. For responsive modals, this can be the modal container.displayMode:tableorgrid.itemCount: the number of data items loaded for the current view. This is not necessarily the number of visible DOM rows.state: the current pagination, sorting, filters and search state.
This event can fire more than once for an update. Make your DOM setup safe to repeat. Image loading and other plugins' asynchronous setup may finish later.
You can also listen for contentRendered as a bubbling native DOM event. In that case, its payload is in event.detail.
stateChange
This event reports the initial table state and later state updates. The handler receives the state object, with pagination, sorting, filters and search properties.
A state update can occur before the new content has rendered. Use contentRendered for DOM setup.
error
This event reports errors from the table instance, such as a failed data request. The handler receives an Error object.
configUpdate
This event fires when table.updateConfig(updates) is called. The handler receives the configuration updates passed to that method.
rowSelectionAction
This event fires when the selected-products action button is used. The handler receives:
items: the selected rows, each with anidand anattributesobject containing the checkbox's data attributes.count: the number of selected items.
WooCommerce Product Table handles the bulk cart request itself. Use added_to_cart to react after a successful cart request.
Example: run code after content renders
This example connects to new and existing tables. It uses the event's container so your code can also reach responsive modal content.
(function () {
const connectedTables = new WeakSet();
function updateContent(container) {
// Replace this with your own DOM setup.
container.querySelectorAll('.my-custom-element').forEach(function (element) {
element.classList.add('my-script-ready');
});
}
function connectTable(table) {
const root = table.getContainer();
if (
!root.matches('.wpt-dataview[data-frontend="dataviews"]') ||
connectedTables.has(table)
) {
return;
}
connectedTables.add(table);
table.on('contentRendered', function (details) {
updateContent(details.container);
});
// Process any content that is already present.
updateContent(root);
}
document.addEventListener('wptDataViewReady', function (event) {
connectTable(event.detail.table);
});
// Pick up tables that were created before this script loaded.
if (window.Barn2DataViews) {
window.Barn2DataViews.getAllInstances().forEach(connectTable);
}
})();Replace .my-custom-element and the contents of updateContent() with your own code. Keep that code safe to run more than once.
Moving from legacy events
The two frontends have different event timing and payloads. Choose the event that matches what your script needs to do.
| Legacy event | Current frontend |
|---|---|
init.wcpt |
Use wptDataViewReady to access the instance, and contentRendered to work with rendered content. |
draw.wcpt |
Use contentRendered for DOM setup after content updates. |
lazyload.wcpt |
Use contentRendered when you need the resulting content in the DOM. It is not a notification for each network request. |
load.wcpt |
Use the native load event on window for page loading, or contentRendered for table content. |
responsiveDisplay.wcpt |
Use contentRendered and its container for responsive content setup. It can also fire for other content updates. |
Legacy frontend (DataTables)
This section applies to legacy mode only. The DataTables frontend runs when legacy mode is enabled.
The ProductTable object
Each legacy table has a ProductTable object with these main properties:
id: the ID assigned to the<table>element.config: the configuration used to initialise the table.$table: a jQuery object for the<table>element.$tableWrapper: a jQuery object for the wrapper<div>.$filters: a jQuery collection of the filter<select>elements, if used.ajaxData: data returned from the server, when available.
Events
These jQuery events fire on the legacy table element and bubble to document. The first additional argument is the ProductTable instance.
jQuery(document).on('draw.wcpt', function (event, table) {
console.log('Legacy table drawn:', table.id);
});init.wcpt
Fires once for each table after it has initialised and its initial data has been drawn.
Parameter: table, the ProductTable instance.
draw.wcpt
Fires for the initial draw and when the table is redrawn after sorting, pagination, filtering or searching.
Parameter: table, the ProductTable instance.
lazyload.wcpt
Fires when data loaded from the server updates the table, before draw.wcpt.
Parameter: table, the ProductTable instance.
load.wcpt
Fires once for each table on the browser's load event on window.
Parameter: table, the ProductTable instance.
responsiveDisplay.wcpt
Fires when a responsive child row or modal opens. It does not fire when the content is hidden.
Parameters:
table: theProductTableinstance.datatable: the DataTables API instance.row: the DataTables row API object. For child rows, userow.child()to access the child content.showHide:truewhen the content is shown.
Cart events for both frontends
Both frontends use WooCommerce's jQuery cart events for AJAX cart requests. You can listen on document.body.
adding_to_cart
Fires before an AJAX cart request. A bulk request fires one event for the submission.
Parameters:
$button: the jQuery object supplied by the request. This is usually the clicked button; bulk requests may supply a form or table container instead.data: the submitted cart data, including product IDs and quantities.
added_to_cart
Fires after a successful AJAX cart request when the response is handled on the page. A bulk add fires once for the submission.
Parameters:
fragments: the cart fragments returned by WooCommerce.cart_hash: the returned cart hash, when supplied.$button: the add to cart button as a jQuery object, when supplied.
Bulk cart requests can omit cart_hash or $button. Custom handlers should check that these values exist before using them.