Setting Options

DataGridXL does not require a long list of options. You can create a fully functional grid by just passing data.

However, you may wish to change some or all of your grid's default settings.

Default user actions

By default, all user-actions are enabled and allowed. These are all user actions that can be disallowed:

Row Actions

• allowRowDelete
• allowRowInsert
• allowRowMove

Column Actions

• allowColDelete
• allowColInsert
• allowColMove
• allowColResize

Cell Actions

• allowCellFill
• allowCellEdit

Clipboard Actions

• allowCopy
• allowCut
• allowPaste

To disallow any of these actions, set them to false in your DataGridXL options object:

var grid = new DataGridXL("grid", {
	data: [...],
	allowColResize: false,
	allowCellFill: false
});

By disallowing a user action, the corresponding mouse and touch drag-actions are disabled and the matching items are excluded from the Context Menu. Any related keyboard listeners are de-activated as well. (Meaning that CTRL+V won't work when allowPaste is set to false).

If you want a non-editable data grid, simply set all these allow-options to false. You'll end up with a high performance readonly data table.

Headers and Labels

Row headers

A default grid will display plain center-aligned "numbers" row header labels (1, 2, 3...). By setting a few simple options, you can align the row labels to the left and add a prefix as well.

var grid = new DataGridXL("grid", {
	data 				: [...],
	rowHeaderLabelAlign : "left",
	rowHeaderLabelPrefix: "Item #"
});

With these settings, row headers will neatly display "Item #1", "Item #2", "Item #3", etc.

Column headers

If your data array is a JSON-style array of objects, your object field names will automatically serve as column header labels.

If you use a 2D array, your columns are untitled. In case of untitled columns, "letters" (A, B, C...) will be used as header labels.

With row headers set to "numbers" and column headers set to "letters", any data grid that has (untitled) 2D-array data will default to spreadsheet-like headers (123 for rows, ABC for columns):

You might want to change these default settings, as DataGridXL does not support formulas at this time. Seeing those spreadsheet-style headers, your user might type something like "=B1+B2" only to be confused to see their raw formula end up as the rendered cell value.

To avoid confusion, use "numbers" for your column headers, same like row headers. You can choose to use a prefix as well.

var grid = new DataGridXL("grid", {
	data: [...],
	rowHeaderWidth: 120,
	rowHeaderLabelAlign : "left",
	rowHeaderLabelPrefix: "Row "
	colHeaderLabelType 	: "numbers",
	colHeaderLabelAlign : "left",
	colHeaderLabelPrefix: "Col "
});

Hiding headers

You can also choose to not show headers for both dimensions. However, be aware that without headers your user cannot modify rows or columns (delete, insert, move or resize).

var grid = new DataGridXL("grid", {
	data : [...],
	showColHeaders: false,
	showRowHeaders: false
});

Column Options

You can also use the columns option to assign titles to unnamed columns, or rename existing columns. We've demonstrated this in the Passing Data article.

Not only can you re-name or re-order columns, you also give them unique widths and set their alignment:

var grid = new DataGridXL("grid", {
	data 	: [
		["Kooikerhondje", 210, "The Netherlands"],
		["Beagle", 235, "Great Britain"],
		["Dalmatian", 90, "Croatia"]
	],
	columns : [{
		width: 200,
		align: "right",
		title: "Country",
		source: 2
	}, {
		width: 140,
		align: "center",
		title: "Dog Breed",
		source: 0
	}]
});

Theming

You might have noticed that you don't need to include a CSS file along with the DataGridXL Javascript file. That CSS file simply doesn't exist. You can still customize your grid styles, of course.

It's mainly colors and opacities. You cannot affect cell spacing or cell margins only to pretend that your highly advanced grid is actually an HTML table that is made with Bootstrap ;-) Maybe one day.

// extremely ugly custom theme
var my_theme = {
	colHeaderBackgroundColor: "#0000cc",
	rowHeaderBackgroundColor: "#cc0000",
	cellCursorColor: "green"
};

var grid = new DataGridXL("grid", {
	data 	: [...],
	theme 	: my_theme
});

There are many more style settings. Our docs has an entire page dedicated to DataGridXL themes.

Changing options on-the-fly

At this time, you can only pass in options when first creating the grid. It's not possible to change an option on-the-fly like grid.data = new_data; and expect the grid to magically refresh itself.

We'll surely find a way to make that work in the future. For now, your best option is to create a new grid with fresh options. Just target the same container id and your old grid will be replaced, like it never existed:

// create grid (1st time)
var initialOptions = {
	data: DataGridXL.createDummyData(5,5)
};
var grid = new DataGridXL("grid", initialOptions);

someButton.onclick = function(){

	// create a new grid with new options
	// just overwrite grid variable
	var newOptions = {
		data: DataGridXL.createDummyData(10,5),
		rowHeight: 40
	};
	grid = new DataGridXL("grid", newOptions);

};

Exceptions to this "rule" are the setTheme() and setData() methods. Use these if you want to change the grid theme or the grid's data, without having to set up a new DataGridXL instance.

Further reading

Now that you know how to change default options, we think you're ready to create a mini app. Follow us to the wonderful land of DataGridXL methods.