API Events

ZingGrid comes with its own set of events that work similarly to modern event handlers. Many of these events help signal when the grid or its components are rendered, or when an interaction occurs.

Event Usage

ZingGrid events have to be added after ZingGrid is available in the DOM. You can do this but assigning a reference to your grid.

CloseCopy Copied
// Grab reference to grid
const zgRef = document.querySelector('zing-grid');

These events are added like native events and the best practice is to use addEventListener. In the example below, we attach the record:click event to demonstrate how to properly add an event in ZingGrid.

CloseCopy Copied
const zgRef = document.querySelector('zing-grid');
zgRef.addEventListener('record:click', (e) => {
  // destruct e.detail object for ZingGrid information
  const { ZGData, ZGEvent, ZGTarget } = e.detail;
  console.log('--- Event Details ---\n', ZGData, ZGEvent, ZGTarget);
});

All event detail can be accessed through e.detail. Most events will return the following object structure:

CloseCopy Copied
e.detail: {
  // Information from ZingGrid internal components.
  ZGData: {...},
  // Points to any relevant built in event.
  ZGEvent: {...},
  // Points the DOM element the event actually happened on.
  ZGTarget: {...},
}
e.detail Object's
ZGDataZGEventZGTarget
Information from ZingGrid internal components. Including cell, row, grid and other components.Points to any relevant built in event. ie. The actual click event in the case of cell:click.A reference to the DOM object relative to that action e.g. cell, row, grid.

If you need to wait till everything in the grid is ready, typically when running set methods on the grid, you will use zgRef.executeOnLoad() to determine synchronous actions on the grid.

CloseCopy Copied
const zgRef = document.querySelector('zing-grid');
zgRef.executeOnLoad(() => {
  // apply ZingGrid methods in here like data:
  zgRef.setData();
});

Note that ZingGrid events are not compatible with on-tag event attributes or direct bound events. Therefore, the following examples will not work!

Adding an event handler as an attribute:

CloseCopy Copied
<zing-grid onclick="click"></zing-grid>

<script>
  function click() { alert('Click!'); }
</script>
or binding events directly (as opposed to using a modern event listener):
CloseCopy Copied
document.querySelector('zing-grid').onrender = function click() { alert('Rendered'); };

Grid Events

zing-grid refers to the grid, and its events target the grid as a whole (zing-grid Events Playground).

Example Usage

CloseCopy Copied
const zgRef = document.querySelector('zing-grid');
zgRef.addEventListener('grid:ready', function(e) {
  console.log('--- (grid:ready) event fired ---', e);
});

Card Events

zg-card events are events that target the grid as a whole (zg-card Events Playground).

Example Usage

CloseCopy Copied
const zgRef = document.querySelector('zing-grid');
zgRef.addEventListener('card:click', function(e) {
  console.log('--- (card:click) event fired ---', e);
});

Cell Events

zg-cell events are events that are triggered by each individual cell of the grid (zg-cell Events Playground).

Example Usage

CloseCopy Copied
const zgRef = document.querySelector('zing-grid');
zgRef.addEventListener('cell:click', function(e) {
  console.log('--- (cell:click) event fired ---', e);
});

When implementing your own custom renderer function and binding an event, only attempt to bind events to contents of zg-cell! Do not bind events to zg-cell or zg-row — these components are reused to enhance performance. To bind events to zg-cell or zg-row, please use ZingGrid's custom events.

Edit
Download
CloseCopy Copied
CloseCopy Copied
CloseCopy Copied

Column Events

zg-column refers to the columns of the grid. Events triggered by columns are zg-column events (zg-column Events Playground).

CloseCopy Copied
const zgRef = document.querySelector('zing-grid');
zgRef.addEventListener('column:click', function(e) {
  console.log('--- (column:click) event fired ---', e);
});

Data Events

zg-data events relate to data and any changes made to a record (zg-data Events Playground).

CloseCopy Copied
const zgRef = document.querySelector('zing-grid');
zgRef.addEventListener('data:load', function(e) {
  console.log('--- (data:load) event fired ---', e);
});

Header Events

zg-header events are triggered by the header cell of a column (zg-header Events Playground).

CloseCopy Copied
const zgRef = document.querySelector('zing-grid');
zgRef.addEventListener('header:click', function(e) {
  console.log('--- (header:click) event fired ---', e);
});

Record Events

A record refers to a row and card in the grid. Events triggered by row and card mode are grouped into record events.

CloseCopy Copied
const zgRef = document.querySelector('zing-grid');
zgRef.addEventListener('record:click', function(e) {
  console.log('--- (record:click) event fired ---', e);
});

Row Events

zg-row refers to a row in the grid. Events triggered by rows are zg-row events (zg-row Events Playground).

CloseCopy Copied
const zgRef = document.querySelector('zing-grid');
zgRef.addEventListener('row:click', function(e) {
  console.log('--- (row:click) event fired ---', e);
});

When implementing your own custom renderer function and binding an event, only attempt to bind events to contents of zg-cell! Do not bind events to zg-cell or zg-row — these components are reused to enhance performance. To bind events to zg-cell or zg-row, please use ZingGrid's custom events.

Edit
Download
CloseCopy Copied
CloseCopy Copied
CloseCopy Copied
loadingloadBgloadBgloadBgloadBgloadBgloadBgloadBgloadBgloadBgloadBgloadBgloadBgloadBgloadBgloadingloadingloadingloadingloadingloadingloadingloadingloadingloadingloadingloadingloadingloadingloadingloadingloadingloadingloadingloadingloadingloading