jQuery.grid plugin helps to display read-only tabular data.
Features
Virtual scrolling.
Data paging.
Multi-row headers.
Custom rendering available for cells and header.
Lazy loading.
Three themes available - Flick, Cupertino, Vader.
Themable scroll.
Theme:
Options
Events
Events log:
API
Options
numberOfElementsInDataSource - number of elements in data source.
alternatingRowEnabled - Default: false.
true - odd and even rows will have different styles.
false - all rows will have the same style.
numberOfRowsInScrollableArea - number of visible rows in grid. In other words it's grid height in rows.
columns - array of column definitions.
Every element of this array has following fields:
caption - column caption.
name - unique column name.
filed - field in data source for this column. For band columns (columns with sub-columns) this value should be empty.
subColumns - array of of column definitions that will be displayed as sub-columns of this column.
pagerSettings - object with following fields
showPager - Default: true.
true - show pager.
false - virtual scrolling mode
pageSize - Default: 15. Number of rows in one page.
position - Default: 'PAGER_POSITION_BOTTOM'.
'PAGER_POSITION_TOP'
'PAGER_POSITION_BOTTOM'
'PAGER_POSITION_TOP_AND_BOTTOM'
Events
columnHeaderCustomDraw - triggers on every column header rendering. Subscribe to this event if you need custom appearance for column headers.
Event handler arguments:
event – standard jQuery event object.
data – event data. Object with following fields:
columnName - column name.
caption – column caption.
cell – root html element of this column header. You can modify content of this element to change header appearance.
columnObj – object that represents this column in grid.
Example of event handler:
//change header background for column 'Author'
function onColumnHeaderCustomDraw(event, data){
if (data.columnName == 'Author') {
data.cell.css('background', 'red');
}
}
//add checkbox to column header 'Author'
function onColumnHeaderCustomDraw(event, data){
if (data.columnName == 'Author') {
// find caption element
var captionElement = $('.' + gridConstants.CSS_HEADER_CELL_CAPTION, data.cell);
// insert checkbox right after column caption
$('<br /><input type="checkbox" />').insertAfter(captionElement);
var checkbox = $('input[type=checkbox]', data.cell);
// restore state from column object
checkbox.attr('checked', data.columnObj.customCheckboxChecked);
checkbox.click(function (e) {
// click on checkbox will be treated by grid as click on column header, that in turn will cause sorting
// to prevent this we need to stop click event propagation
e.stopPropagation();
});
checkbox.change(function () {
// grid can recreate column header element in future, that's why we need to keep checkbox state
// save state in column object
data.columnObj.customCheckboxChecked = $(this).is(':checked');
});
}
}
bodyCellCustomDraw - triggers on every grid cell rendering. Subscribe to this event if you need custom appearance for cells.
Event handler arguments:
event – standard jQuery event object.
data – event data. Object with following fields:
cell - root html element of this cell. You can modify content of this element to change cell appearance.
field – data field.
value – cell value.
dataRow – data object associated with current row.
dataSourceIndex - index of data object associated with current row
isEmpty - true if this cell is empty, otherwise false. Cell can be empty, when for example you have 3 elements in data source and 10 rows page size, then you'll get 7 empty rows.
Example of event handler:
//highlight author names with red color, for all books with price higher than $30
function onBodyCellCustomDraw(event, data){
if (data.field == "FirstName" || data.field == "SecondName") {
if (data.dataRow["Price"] > 30) {
data.cell.css('background', 'red');
} else {
data.cell.css('background', 'white');
}
}
}
getDataFrame - triggers when new portion of data is needed to render grid. For example when user switch between pages, or move scroll in virtual scrolling mode. This is the right place to request new portion of data from your server.
Event handler arguments:
event – standard jQuery event object.
data – event data. Object with following fields:
orderByFields - list of column names used in sorting. Usually this array contains only one column, but when user sort grid by band column (column that has several sub-columns) then this array contains all data columns of this band column.
direction – order direction. Possible values: 'ASC' and 'DESC'.
startFromRecord – position of requested data frame in sorted data source.
numberOfRecordsToShow – number of records in requested data frame.
Typically, within handler of this event you should do the following:
get your data
order data by fields specified in orderByFields and with direction specified in direction.
take numberOfRecordsToShow starting from record startFromRecord.
pass resulting array of data rows to setDataFrame method.
In real life steps 1,2, and 3 should be executed on server side. But if you have all your data on the client, you can perform all these steps on client side and avoid callbacks.
Example of event handler:
//load data from server
function onGetDataFrame(event, data) {
$.ajax({
type: "POST",
url: "http://www.myserver.com/data",
data: JSON.stringify(data),
contentType: 'application/json; charset=utf-8'
})
.done(function(res) {
$('#gridContainer').data('jsg-grid').setDataFrame(res);
});
}
Methods
setDataFrame(dataFrame) - call this method only when you recieved resulting data after getDataFrame event. See getDataFrame event for more details.
refreshData() - reloads data from the data source.