jsGrid Lightweight Grid jQuery Plugin
Project site js-grid.com
jsGrid is a lightweight client-side data grid control based on jQuery.
It supports basic grid operations like inserting, filtering, editing, deleting, paging and sorting.
Although jsGrid is tunable and allows to customize appearance and components.
Table of contents
Demos
See Demos on project site.
Sample projects showing how to use jsGrid with the most popular backend technologies
Installation
Install jsgrid with bower:
$ bower install js-grid
Find jsGrid cdn links here.
Basic Usage
Ensure that jQuery library of version 1.8.3 or later is included.
Include jsgrid.min.js
, jsgrid-theme.min.css
, and jsgrid.min.css
files into the web page.
Create grid applying jQuery plugin jsGrid
with grid config as follows:
$("#jsGrid").jsGrid({
width: "100%",
height: "400px",
filtering: true,
editing: true,
sorting: true,
paging: true,
data: db.clients,
fields: [
{ name: "Name", type: "text", width: 150 },
{ name: "Age", type: "number", width: 50 },
{ name: "Address", type: "text", width: 200 },
{ name: "Country", type: "select", items: db.countries, valueField: "Id", textField: "Name" },
{ name: "Married", type: "checkbox", title: "Is Married", sorting: false },
{ type: "control" }
]
});
Configuration
The config object may contain following options (default values are specified below):
{
fields: [],
data: [],
autoload: false,
controller: {
loadData: $.noop,
insertItem: $.noop,
updateItem: $.noop,
deleteItem: $.noop
},
width: "auto",
height: "auto",
heading: true,
filtering: false,
inserting: false,
editing: false,
selecting: true,
sorting: false,
paging: false,
pageLoading: false,
rowClass: function(item, itemIndex) { ... },
rowClick: function(args) { ... },
rowDoubleClick: function(args) { ... },
noDataContent: "Not found",
confirmDeleting: true,
deleteConfirm: "Are you sure?",
pagerContainer: null,
pageIndex: 1,
pageSize: 20,
pageButtonCount: 15,
pagerFormat: "Pages: {first} {prev} {pages} {next} {last} {pageIndex} of {pageCount}",
pagePrevText: "Prev",
pageNextText: "Next",
pageFirstText: "First",
pageLastText: "Last",
pageNavigatorNextText: "...",
pageNavigatorPrevText: "...",
loadIndication: true,
loadIndicationDelay: 500,
loadMessage: "Please, wait...",
loadShading: true,
loadIndicator: function(config) { ... }
loadStrategy: function(config) { ... }
updateOnResize: true,
rowRenderer: null,
headerRowRenderer: null,
filterRowRenderer: null,
insertRowRenderer: null,
editRowRenderer: null
}
fields
An array of fields (columns) of the grid.
Each field has general options and specific options depending on field type.
General options peculiar to all field types:
{
type: "",
name: "",
title: "",
align: "",
width: 100,
css: "",
headercss: "",
filtercss: "",
insertcss: "",
editcss: "",
filtering: true,
inserting: true,
editing: true,
sorting: true,
sorter: "string",
headerTemplate: function() { ... },
itemTemplate: function(value, item) { ... },
filterTemplate: function() { ... },
insertTemplate: function() { ... },
editTemplate: function(value, item) { ... },
filterValue: function() { ... },
insertValue: function() { ... },
editValue: function() { ... },
cellRenderer: null
}
- type is a string key of field (
"text"|"number"|"checkbox"|"select"|"textarea"|"control"
) in fields registry jsGrid.fields
(the registry can be easily extended with custom field types). - name is a property of data item associated with the column.
- title is a text to be displayed in the header of the column. If
title
is not specified, the name
will be used instead. - align is alignment of text in the cell. Accepts following values
"left"|"center"|"right"
. - width is a width of the column.
- css is a string representing css classes to be attached to the table cell.
- headercss is a string representing css classes to be attached to the table header cell. If not specified, then css is attached instead.
- filtercss is a string representing css classes to be attached to the table filter row cell. If not specified, then css is attached instead.
- insertcss is a string representing css classes to be attached to the table insert row cell. If not specified, then css is attached instead.
- editcss is a string representing css classes to be attached to the table edit row cell. If not specified, then css is attached instead.
- filtering is a boolean specifying whether or not column has filtering (
filterTemplate()
is rendered and filterValue()
is included in load filter object). - inserting is a boolean specifying whether or not column has inserting (
insertTemplate()
is rendered and insertValue()
is included in inserting item). - editing is a boolean specifying whether or not column has editing (
editTemplate()
is rendered and editValue()
is included in editing item). - sorting is a boolean specifying whether or not column has sorting ability.
- sorter is a string or a function specifying how to sort item by the field. The string is a key of sorting strategy in the registry
jsGrid.sortStrategies
(the registry can be easily extended with custom sorting functions). Sorting function has the signature function(value1, value2) { return -1|0|1; }
. - headerTemplate is a function to create column header content. It should return markup as string, DomNode or jQueryElement.
- itemTemplate is a function to create cell content. It should return markup as string, DomNode or jQueryElement. The function signature is
function(value, item)
, where value
is a value of column property of data item, and item
is a row data item. - filterTemplate is a function to create filter row cell content. It should return markup as string, DomNode or jQueryElement.
- insertTemplate is a function to create insert row cell content. It should return markup as string, DomNode or jQueryElement.
- editTemplate is a function to create cell content of editing row. It should return markup as string, DomNode or jQueryElement. The function signature is
function(value, item)
, where value
is a value of column property of data item, and item
is a row data item. - filterValue is a function returning the value of filter property associated with the column.
- insertValue is a function returning the value of inserting item property associated with the column.
- editValue is a function returning the value of editing item property associated with the column.
- cellRenderer is a function to customize cell rendering. The function signature is
function(value, item)
, where value
is a value of column property of data item, and item
is a row data item. The function should return markup as a string, jQueryElement or DomNode representing table cell td
.
Specific field options depends on concrete field type.
Read about build-in fields in Grid Fields section.
data
An array of items to be displayed in the grid. The option should be used to provide static data. Use the controller
option to provide non static data.
autoload (default false
)
A boolean value specifying whether controller.loadData
will be called when grid is rendered.
controller
An object or function returning an object with the following structure:
{
loadData: $.noop,
insertItem: $.noop,
updateItem: $.noop,
deleteItem: $.noop
}
- loadData is a function returning an array of data or jQuery promise that will be resolved with an array of data (when
pageLoading
is true
instead of object the structure { data: [items], itemsCount: [total items count] }
should be returned). Accepts filter parameter including current filter options and paging parameters when pageLoading
is true
. - insertItem is a function returning inserted item or jQuery promise that will be resolved with inserted item. Accepts inserting item object.
- updateItem is a function returning updated item or jQuery promise that will be resolved with updated item. Accepts updating item object.
- deleteItem is a function deleting item. Returns jQuery promise that will be resolved when deletion is completed. Accepts deleting item object.
Read more about controller interface in Grid Controller section.
width (default: "auto"
)
Specifies the overall width of the grid.
Accepts all value types accepting by jQuery.width
.
height (default: "auto"
)
Specifies the overall height of the grid including the pager.
Accepts all value types accepting by jQuery.height
.
heading (default: true
)
A boolean value specifies whether to show grid header or not.
filtering (default: false
)
A boolean value specifies whether to show filter row or not.
inserting (default: false
)
A boolean value specifies whether to show inserting row or not.
editing (default: false
)
A boolean value specifies whether editing is allowed.
selecting (default: true
)
A boolean value specifies whether to highlight grid rows on hover.
sorting (default: false
)
A boolean value specifies whether sorting is allowed.
paging (default: false
)
A boolean value specifies whether data is displayed by pages.
pageLoading (default: false
)
A boolean value specifies whether to load data by page.
When pageLoading
is true
the loadData
method of controller accepts filter
parameter with two additional properties pageSize
and pageIndex
.
rowClass
A string or a function specifying row css classes.
A string contains classes separated with spaces.
A function has signature function(item, itemIndex)
. It accepts the data item and index of the item. It should returns a string containing classes separated with spaces.
rowClick
A function handling row click. Accepts single argument with following structure:
{
item
itemIndex
event
}
By default rowClick
performs row editing when editing
is true
.
rowDoubleClick
A function handling row double click. Accepts single argument with the following structure:
{
item
itemIndex
event
}
noDataContent (default "Not found"
)
A string or a function returning a markup, jQueryElement or DomNode specifying the content to be displayed when data
is an empty array.
confirmDeleting (default true
)
A boolean value specifying whether to ask user to confirm item deletion.
deleteConfirm (default "Are you sure?"
)
A string or a function returning string specifying delete confirmation message to be displayed to the user.
A function has the signature function(item)
and accepts item to be deleted.
A jQueryElement or DomNode to specify where to render a pager. Used for external pager rendering. When it is equal to null
, the pager is rendered at the bottom of the grid.
pageIndex (default 1
)
An integer value specifying current page index. Applied only when paging
is true
.
pageSize (default 20
)
An integer value specifying the amount of items on the page. Applied only when paging
is true
.
pageButtonCount (default 15
)
An integer value specifying the maximum amount of page buttons to be displayed in the pager.
A string specifying pager format.
The default value is "Pages: {first} {prev} {pages} {next} {last} {pageIndex} of {pageCount}"
There are placeholders that can be used in the format:
{first}
{prev}
{pages}
{next}
{last}
{pageIndex}
{pageCount}
{itemCount}
pageNextText (default "Next"
)
A string specifying the text of the link to the next page.
pagePrevText (default "Prev"
)
A string specifying the text of the link to the previous page.
pageFirstText (default "First"
)
A string specifying the text of the link to the first page.
pageLastText (default "Last"
)
A string specifying the text of the link to the last page.
pageNavigatorNextText (default "..."
)
A string specifying the text of the link to move to next set of page links, when total amount of pages more than pageButtonCount
.
pageNavigatorPrevText (default "..."
)
A string specifying the text of the link to move to previous set of page links, when total amount of pages more than pageButtonCount
.
loadIndication (default true
)
A boolean value specifying whether to show loading indication during controller operations execution.
loadIndicationDelay (default 500
)
An integer value specifying the delay in ms before showing load indication. Applied only when loadIndication
is true
.
loadMessage (default "Please, wait..."
)
A string specifying the text of loading indication panel. Applied only when loadIndication
is true
.
loadShading (default true
)
A boolean value specifying whether to show overlay (shader) over grid content during loading indication. Applied only when loadIndication
is true
.
loadIndicator
An object or a function returning an object representing grid load indicator. Load indicator could be any js object supporting two methods show
and hide
.
show
is called on each loading start. hide
method is called on each loading finish. Read more about custom load indicator in the Load Indication section.
loadStrategy
An object or a function returning an object representing grid load strategy. Load strategy defines behavior of the grid after loading data (any interaction with grid controller methods including data manipulation like inserting, updating and removing).
There are two build-in load strategies: DirectLoadingStrategy
and PageLoadingStrategy
. Load strategy depends on pageLoading
option value.
For advanced scenarios custom load strategy can be provided. Read more about custom load strategies in the Load Strategies section.
updateOnResize (default true
)
A boolean value specifying whether to refresh grid on window resize event.
rowRenderer (default null
)
A function to customize row rendering. The function signature is function(item, itemIndex)
, where item
is row data item, and itemIndex
is the item index.
The function should return markup as a string, jQueryElement or DomNode representing table row tr
.
A function to customize grid header row.
The function should return markup as a string, jQueryElement or DomNode representing table row tr
.
filterRowRenderer (default null
)
A function to customize grid filter row.
The function should return markup as a string, jQueryElement or DomNode representing table row tr
.
insertRowRenderer (default null
)
A function to customize grid inserting row.
The function should return markup as a string, jQueryElement or DomNode representing table row tr
.
editRowRenderer (default null
)
A function to customize editing row rendering. The function signature is function(item, itemIndex)
, where item
is row data item, and itemIndex
is the item index.
The function should return markup as a string, jQueryElement or DomNode representing table row tr
.
Grid Fields
All fields supporting by grid are stored in jsGrid.fields
object, where key is a type of the field and the value is the field class.
jsGrid.fields
contains following build-in fields:
{
text: { ... },
number: { ... },
select: { ... },
checkbox: { ... },
textarea: { ... },
control: { ... }
}
Each build-in field can be easily customized with general configuration properties described in fields section and custom field-specific properties described below.
text
Text field renders <input type="text">
in filter, inserting and editing rows.
Custom properties:
{
autosearch: true
}
number
Number field renders <input type="number">
in filter, inserting and editing rows.
Custom properties:
{
sorter: "number",
align: "right"
}
select
Select field renders <select>
control in filter, inserting and editing rows.
Custom properties:
{
align: "center",
autosearch: true,
items: [],
valueField: "",
textField: "",
selectedIndex: -1
}
If valueField is not defined, then the item index is used instead.
If textField is not defined, then item itself is used to display value.
For instance the simple select field config may look like:
{
name: "Country",
type: "select",
items: [ "", "United States", "Canada", "United Kingdom" ]
}
or more complex with items as objects:
{
name: "Country",
type: "select"
items: [
{ Name: "", Id: 0 },
{ Name: "United States", Id: 1 },
{ Name: "Canada", Id: 2 },
{ Name: "United Kingdom", Id: 3 }
],
valueField: "Id",
textField: "Name"
}
checkbox
Checkbox field renders <input type="checkbox">
in filter, inserting and editing rows.
Filter checkbox supports intermediate state for, so click switches between 3 states (checked|intermediate|unchecked).
Custom properties:
{
sorter: "number",
align: "center"
autosearch: true
}
textarea
Textarea field renders <textarea>
in inserting and editing rows and <input type="text">
in filter row.
Custom properties:
{
autosearch: true
}
control
Control field renders delete and editing buttons in data row, search and add buttons in filter and inserting row accordingly.
It also renders button switching between filtering and searching in header row.
Custom properties:
{
editButton: true,
deleteButton: true,
clearFilterButton: true,
modeSwitchButton: true,
align: "center",
width: 50,
filtering: false,
inserting: false,
editing: false,
sorting: false,
searchModeButtonTooltip: "Switch to searching",
insertModeButtonTooltip: "Switch to inserting",
editButtonTooltip: "Edit",
deleteButtonTooltip: "Delete",
searchButtonTooltip: "Search",
clearFilterButtonTooltip: "Clear filter",
insertButtonTooltip: "Insert",
updateButtonTooltip: "Update",
cancelEditButtonTooltip: "Cancel edit",
}
Custom Field
If you need a completely custom field, the object jsGrid.fields
can be easily extended.
In this example we define new grid field date
:
var MyDateField = function(config) {
jsGrid.Field.call(this, config);
};
MyDateField.prototype = new jsGrid.Field({
css: "date-field",
align: "center",
myCustomProperty: "foo",
sorter: function(date1, date2) {
return new Date(date1) - new Date(date2);
},
itemTemplate: function(value) {
return new Date(value).toDateString();
},
insertTemplate: function(value) {
return this._insertPicker = $("<input>").datepicker({ defaultDate: new Date() });
},
editTemplate: function(value) {
return this._editPicker = $("<input>").datepicker().datepicker("setDate", new Date(value));
},
insertValue: function() {
return this._insertPicker.datepicker("getDate").toISOString();
},
editValue: function() {
return this._editPicker.datepicker("getDate").toISOString();
}
});
jsGrid.fields.date = MyDateField;
To have all general grid field properties custom field class should inherit jsGrid.Field
class or any other field class.
Here itemTemplate
just returns the string representation of a date.
insertTemplate
and editTemplate
create jQuery UI datePicker for inserting and editing row.
Of course jquery ui library should be included to make it work.
insertValue
and editValue
return date to insert and update items accordingly.
We also defined date specific sorter.
Now, our new field date
can be used in the grid config as follows:
{
fields: [
...
{ type: "date", myCustomProperty: "bar" },
...
]
}
Methods
jsGrid methods could be called with jsGrid
jQuery plugin or directly.
To use jsGrid plugin to call a method, just call jsGrid
with method name and required parameters as next arguments:
$("#grid").jsGrid("methodName", param1, param2);
To call method directly you need to retrieve grid instance or just create grid with the constructor:
var grid = $("#grid").data("JSGrid");
var grid = new jsGrid.Grid($("#grid"), { ... });
grid.methodName(param1, param2);
cancelEdit()
Cancels row editing.
$("#grid").jsGrid("cancelEdit");
clearFilter(): Promise
Clears current filter and performs search with empty filter.
Returns jQuery promise resolved when data filtering is completed.
$("#grid").jsGrid("clearFilter").done(function() {
console.log("filtering completed");
});
clearInsert()
Clears current inserting row.
$("#grid").jsGrid("clearInsert");
deleteItem(item|$row|rowNode): Promise
Removes specified row from the grid.
Returns jQuery promise resolved when deletion is completed.
item|$row|rowNode is the reference to the item or the row jQueryElement or the row DomNode.
$("#grid").jsGrid("deleteItem", item);
$("#grid").jsGrid("deleteItem", $(".specific-row"));
$("#grid").jsGrid("deleteItem", rowNode);
destroy()
Destroys the grid and brings the Node to its original state.
$("#grid").jsGrid("destroy");
editItem(item|$row|rowNode)
Sets grid editing row.
item|$row|rowNode is the reference to the item or the row jQueryElement or the row DomNode.
$("#grid").jsGrid("editItem", item);
$("#grid").jsGrid("editItem", $(".specific-row"));
$("#grid").jsGrid("editItem", rowNode);
getFilter()
Get grid filter as plain object.
var filter = $("#grid").jsGrid("getFilter");
insertItem([item]): Promise
Inserts row into the grid based on item.
Returns jQuery promise resolved when insertion is completed.
item is the item to pass to controller.insertItem
.
If item
is not specified the data from inserting row will be inserted.
$("#grid").jsGrid("insertItem");
$("#grid").jsGrid("insertItem", { Name: "John", Age: 25, Country: 2 }).done(function() {
console.log("insertion completed");
});
loadData([filter]): Promise
Loads data calling corresponding controller.loadData
method.
Returns jQuery promise resolved when data loading is completed.
It preserves current sorting and paging unlike the search
method .
filter is a filter to pass to controller.loadData
.
If filter
is not specified the current filter (filtering row values) will be applied.
$("#grid").jsGrid("loadData");
$("#grid").jsGrid("loadData", { Name: "John" }).done(function() {
console.log("data loaded");
});
openPage(pageIndex)
Opens the page of specified index.
pageIndex is one-based index of the page to open. The value should be in range from 1 to [total amount of pages].
option(key, [value])
Gets or sets the value of an option.
key is the name of the option.
value is the new option value to set.
If value
is not specified, then the value of the option key
will be returned.
$("#grid").jsGrid("option", "paging", false);
var pageIndex = $("#grid").jsGrid("option", "pageIndex");
refresh()
Refreshes the grid. Renders the grid body and pager content, recalculates sizes.
$("#grid").jsGrid("refresh");
render(): Promise
Performs complete grid rendering. If option autoload
is true
calls controller.loadData
. The state of the grid like current page and sorting is retained.
Returns jQuery promise resolved when data loading is completed. If auto-loading is disabled the promise is instantly resolved.
$("#grid").jsGrid("render").done(function() {
console.log("rendering completed and data loaded");
});
reset()
Resets the state of the grid. Goes to the first data page, resets sorting, and then calls refresh
.
$("#grid").jsGrid("reset");
search([filter]): Promise
Performs filtering of the grid.
Returns jQuery promise resolved when data loading is completed.
It resets current sorting and paging unlike the loadData
method.
filter is a filter to pass to controller.loadData
.
If filter
is not specified the current filter (filtering row values) will be applied.
$("#grid").jsGrid("search");
$("#grid").jsGrid("search", { Name: "John" }).done(function() {
console.log("filtering completed");
});
showPrevPages()
Shows previous set of pages, when total amount of pages more than pageButtonCount
.
$("#grid").jsGrid("showPrevPages");
showNextPages()
Shows next set of pages, when total amount of pages more than pageButtonCount
.
$("#grid").jsGrid("showNextPages");
sort(sortConfig|field, [order]): Promise
Sorts grid by specified field.
Returns jQuery promise resolved when sorting is completed.
sortConfig is the plain object of the following structure { field: (fieldIndex|fieldName|field), order: ("asc"|"desc") }
field is the field to sort by. It could be zero-based field index or field name or field reference
order is the sorting order. Accepts the following values: "asc"|"desc"
If order
is not specified, then data is sorted in the reversed to current order, when grid is already sorted by the same field. Or "asc"
for sorting by another field.
When grid data is loaded by pages (pageLoading
is true
) sorting calls controller.loadData
with sorting parameters. Read more in Grid Controller section.
$("#grid").jsGrid("sort", 0);
$("#grid").jsGrid("sort", { field: "Name", order: "desc" });
$("#grid").jsGrid("sort", myField, "asc").done(function() {
console.log("sorting completed");
});
updateItem([item|$row|rowNode], [editedItem]): Promise
Updates item and row of the grid.
Returns jQuery promise resolved when update is completed.
item|$row|rowNode is the reference to the item or the row jQueryElement or the row DomNode.
editedItem is the changed item to pass to controller.updateItem
.
If item|$row|rowNode
is not specified then editing row will be updated.
If editedItem
is not specified the data from editing row will be taken.
$("#grid").jsGrid("updateItem");
$("#grid").jsGrid("updateItem", { ID: 1, Name: "John", Age: 25, Country: 2 });
$("#grid").jsGrid("updateItem", item, { ID: 1, Name: "John", Age: 25, Country: 2 }).done(function() {
console.log("update completed");
});
jsGrid.setDefaults(config)
Set default options for all grids.
jsGrid.setDefaults({
filtering: true,
inserting: true
});
jsGrid.setDefaults(fieldName, config)
Set default options of the particular field.
jsGrid.setDefaults("text", {
width: 150,
css: "text-field-cls"
});
Callbacks
onDataLoading
Fires before data loading.
Has following arguments:
{
grid
filter
}
onDataLoaded
Fires after data loading.
Has following arguments:
{
grid
data
}
onError
Fires when controller handler promise failed.
Has following arguments:
{
grid
args
}
onItemDeleting
Fires before item deletion.
Has following arguments:
{
grid
row
item
itemIndex
}
onItemDeleted
Fires after item deletion.
Has following arguments:
{
grid
row
item
itemIndex
}
onItemInserting
Fires before item insertion.
Has following arguments:
{
grid
item
}
onItemInserted
Fires after item insertion.
Has following arguments:
{
grid
item
}
onItemUpdating
Fires before item update.
Has following arguments:
{
grid
row
item
itemIndex
previousItem
}
onItemUpdated
Fires after item update.
Has following arguments:
{
grid
row
item
itemIndex
previousItem
}
onOptionChanging
Fires before grid option value change.
Has following arguments:
{
grid
option
oldValue
newValue
}
onOptionChanged
Fires after grid option value change.
Has following arguments:
{
grid
option
value
}
onRefreshing
Fires before grid refresh.
Has following arguments:
{
grid
}
onRefreshed
Fires after grid refresh.
Has following arguments:
{
grid
}
Grid Controller
The controller is a gateway between grid and data storage. All data manipulations call accordant controller methods.
By default grid has an empty controller and can work with static array of items stored in option data
.
A controller should implement following interface:
{
loadData: function(filter) { ... },
insertItem: function(item) { ... },
updateItem: function(item) { ... },
deleteItem: function(item) { ... }
}
For instance the controller for typical REST service might look like:
{
loadData: function(filter) {
return $.ajax({
type: "GET",
url: "/items",
data: filter,
dataType: "json"
});
},
insertItem: function(item) {
return $.ajax({
type: "POST",
url: "/items",
data: item,
dataType: "json"
});
},
updateItem: function(item) {
return $.ajax({
type: "PUT",
url: "/items",
data: item,
dataType: "json"
});
},
deleteItem: function(item) {
return $.ajax({
type: "DELETE",
url: "/items",
data: item,
dataType: "json"
});
},
}
loadData(filter): Promise|dataResult
Called on data loading.
filter contains all filter parameters of fields with enabled filtering
When pageLoading
is true
and data is loaded by page, filter
includes two more parameters:
{
pageIndex
pageSize
}
When grid sorting is enabled, filter
includes two more parameters:
{
sortField
sortOrder
}
Method should return dataResult
or jQuery promise that will be resolved with dataResult
.
dataResult depends on pageLoading
. When pageLoading
is false
(by default), then data result is a plain javascript array of objects.
If pageLoading
is true
data result should have following structure
{
data
itemsCount
}
insertItem(item): Promise|insertedItem
Called on item insertion.
Method should return insertedItem
or jQuery promise that will be resolved with insertedItem
.
If no item is returned, inserting item will be used as inserted item.
item is the item to be inserted.
updateItem(item): Promise|updatedItem
Called on item update.
Method should return updatedItem
or jQuery promise that will be resolved with updatedItem
.
If no item is returned, updating item will be used as updated item.
item is the item to be updated.
deleteItem(item): Promise
Called on item deletion.
If deletion is asynchronous, method should return jQuery promise that will be resolved when deletion is completed.
item is the item to be deleted.
Sorting Strategies
All supported sorting strategies are stored in jsGrid.sortStrategies
object, where key is a name of the strategy and the value is a sortingFunction
.
jsGrid.sortStrategies
contains following build-in sorting strategies:
{
string: { ... },
number: { ... },
date: { ... },
numberAsString: { ... }
}
sortingFunction is a sorting function with the following format:
function(value1, value2) {
if(value1 < value2) return -1;
if(value1 === value2) return 0;
if(value1 > value2) return 1;
}
Custom Sorting Strategy
If you need a custom sorting strategy, the object jsGrid.sortStrategies
can be easily extended.
In this example we define new sorting strategy for our client objects:
var clients = [{
Name: "John",
Age: 25
}, ...];
jsGrid.sortStrategies.client = function(client1, client2) {
return client1.Name.localeCompare(client2.Name)
|| client1.Age - client2.Age;
};
Now, our new sorting strategy client
can be used in the grid config as follows:
{
fields: [
...
{ type: "text", name: "Name", sorter: "client" },
...
]
}
Worth to mention, that if you need particular sorting only once, you can just inline sorting function in sorter
not registering the new strategy:
{
fields: [
...
{
type: "text",
name: "Name",
sorter: function(client1, client2) {
return client1.Name.localeCompare(client2.Name)
|| client1.Age - client2.Age;
}
},
...
]
}
Load Strategies
The behavior of the grid regarding data source interaction is defined by load strategy.
The load strategy has the following methods:
{
firstDisplayIndex: function() {},
lastDisplayIndex: function() {},
itemsCount: function() {},
openPage: function(index) {},
loadParams: function() {},
sort: function() {},
finishLoad: function(loadedData) {},
finishInsert: function(insertedItem) {},
finishDelete: function(deletedItem, deletedItemIndex) {}
}
There are two build-in load strategies: DirectLoadingStrategy (for pageLoading=false
) and PageLoadingStrategy (for pageLoading=true
).
DirectLoadingStrategy
DirectLoadingStrategy is used when loading by page is turned off (pageLoading=false
).
It provides the following behavior:
- firstDisplayIndex returns the index of the first item on the displayed page
- lastDisplayIndex returns the index of the last item on the displayed page
- itemsCount returns the actual amount of all the loaded items
- openPage refreshes the grid to render items of current page
- loadParams returns empty object, since no extra load params are needed
- sort sorts data items and refreshes the grid
- finishLoad puts the data coming from
controller.loadData
into the option data
of the grid - finishInsert pushes new inserted item into the option
data
and refreshes the grid - finishDelete removes deleted item from the option
data
and resets the grid
PageLoadingStrategy
PageLoadingStrategy is used when data is loaded to the grid by pages (pageLoading=true
).
It provides the following behavior:
- firstDisplayIndex returns 0, because all loaded items displayed on the current page
- lastDisplayIndex returns the amount of loaded items, since data loaded by page
- itemsCount returns
itemsCount
provided by controller.loadData
(read more in section controller.loadData) - openPage calls
grid.loadData
to load data for the current page - loadParams returns an object with the structure
{ pageIndex, pageSize }
to provide server with paging info - sort calls
grid.loadData
to load sorted data from the server - finishLoad saves
itemsCount
returned by server and puts the data
into the option data
of the grid - finishInsert calls
grid.search
to reload the data - finishDelete calls
grid.search
to reload the data
Custom LoadStrategy
The option loadStrategy
allows to specify a custom load strategy to customize the behavior of the grid.
The easiest way to do it is to inherit from existing strategy.
By default DirectLoadingStrategy resets the grid (resets the paging and sorting) when an item is deleted.
The following example shows how to create a custom strategy to avoid grid reset on deletion of an item.
var MyCustomDirectLoadStrategy = function(grid) {
jsGrid.loadStrategies.DirectLoadingStrategy.call(this, grid);
};
MyCustomDirectLoadStrategy.prototype = new jsGrid.loadStrategies.DirectLoadingStrategy();
MyCustomDirectLoadStrategy.prototype.finishDelete = function(deletedItem, deletedItemIndex) {
var grid = this._grid;
grid.option("data").splice(deletedItemIndex, 1);
grid.refresh();
};
$("#grid").jsGrid({
loadStrategy: function() {
return new MyCustomDirectLoadStrategy(this);
},
...
});
Load Indication
By default jsGrid uses jsGrid.LoadIndicator. Load indicator can be customized with the loadIndicator
option.
Set an object or a function returning an object supporting the following interface:
{
show: function() { ... }
hide: function() { ... }
}
This simple example prints messages to console instead of showing load indicator:
{
loadIndicator: {
show: function() {
console.log("loading started");
},
hide: function() {
console.log("loading finished");
}
}
}
If loadIndicator
is a function, it accepts the config of load indicator in the following format:
{
container,
message,
shading
}
The similar example printing messages to console shows how to configure loading indicator with a function returning an object:
{
loadIndicator: function(config) {
return {
show: function() {
console.log("loading started: " + config.message);
},
hide: function() {
console.log("loading finished");
}
};
}
}
Customization of loading indicator is useful, when you want to use any external load indicator that is used for all other ajax requests on the page.
This example shows how to use spin.js to indicate loading:
{
loadIndicator: function(config) {
var container = config.container[0];
var spinner = new Spinner();
return {
show: function() {
spinner.spin(container);
},
hide: function() {
spinner.stop();
}
};
}
}
Requirement
jQuery (1.8.3 or later)
Compatibility
Desktop
- Chrome
- Safari
- Firefox
- Opera 15+
- IE 8+
Mobile
- Safari for iOS
- Chrome for Android
- IE10 for WP8