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

• allowDeleteRows
• allowInsertRows
• allowMoveRows
• allowHideRows
• allowShowRows
• allowFreezeRows

Column Actions

• allowDeleteCols
• allowInsertCols
• allowMoveCols
• allowHideCols
• allowShowCols
• allowFreezeCols
• allowResizeCols

Cell Actions

• allowEditCells
• allowFillCells

Clipboard Actions

• allowCopy
• allowCut
• allowPaste

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

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

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

Read-only Data Table

If you want a non-editable data grid, simply set most or all of 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.

By default, row headers are set to "numbers" and column headers are set to "letters". This means that any data grid displaying (untitled) 2D-array data will default to showing spreadsheet-like header labels (123 for rows, ABC for columns).

Numbers as Column Headers

You might want to change these default settings, as DataGridXL does not (yet) support formulas. 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 "
});

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
	}]
});

Style

You might have noticed that you don't need to include a CSS file along with the DataGridXL Javascript file. Changing the grid's colors is done via the theme setting, which takes a plain Javascript object.

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 a fresh set of 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);

};

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 next chapter: DataGridXL methods.