Handling Events

If you're familiar with vanilla Javascript events, you'll know that there are different ways to add & remove event listeners. Arguably the most common way to add & remove native event listeners is the one below:

var clickHandler = function(event){
	console.log('button was clicked!', event);
};

// add event handler
someButton.addEventListener('click', clickHandler);
// remove event handler
someButton.removeEventListener('click', clickHandler);

Any vanilla Javascript event will pass an event object to any of its listeners. The event object holds all kinds of useful information, like mouse coordinates at the moment the button was clicked.

DataGridXL events

DataGridXL events work in a similar fashion. Any DataGridXL event will pass a gridEvent object that contains useful information about the event. This is how you add & remove DataGridXL event listeners:

// add event handler
grid.events.on(eventName, eventHandler);
// remove event handler
grid.events.off(eventName, eventHandler);

Inserting Rows

We've created a little demo grid that lets you insert rows. The first button calls grid.insertRows(2,1) which inserts two rows starting at "row index" 1. The second button adds a single row at the very start.

You can also insert a row by selecting "Insert Rows" from the Context Menu:

We've attached a listener to our grid's rowinsert event, so we'll get notified whenever rows are inserted.

var rowInsertHandler = function(gridEvent){
	console.log('rows were inserted!', gridEvent);
};

// add event handler
grid.events.on('rowinsert', rowInsertHandler);
// remove event handler
grid.events.off('rowinsert', rowInsertHandler);

The gridEvent object for rowinsert holds two properties: an array of IDs of the newly inserted rows and a target index (the row position after which the rows are inserted). You can view it in your browser console.

Canceling events

In some cases you might want to cancel the actual execution of an event.

For native Javascript events you would either return false or use event.preventDefault(). For certain DataGridXL events, you can return false to do the same.

Let's say you want to prevent the user from removing more than 10 rows at a time. A little weird, we agree, but here's how to do do it:

var beforeRowDeleteHandler = function(gridEvent){

	if(gridEvent.amount > 10){
		console.log('user is not allowed to remove this many rows at once');
		return false;
	}

};

// add event handler
grid.events.on('beforerowdelete', beforeRowDeleteHandler);

Not all events can be canceled. Only the events that start with "before".Our API will tell you for every DataGridXL event whether they're cancelable or not.

Furter reading

We hope we've given you a solid introduction to working with DataGridXL, and we can't wait to see what you'll create with DataGridXL!

We recommend studying DataGridXL features & limits before planning to create a Google Spreadsheets competitor and take over the world (hint: you might need to find another product).

To become a data grid master, study the data grid demos and read the How To's & How It's Made articles. Then there's always the API, of course!