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, sorting, and validating. jsGrid is tunable and allows to customize appearance and components.

Table of contents

• Demos
• Installation
• Basic Usage
• Configuration
• Grid Fields
• Methods
• Callbacks
• Grid Controller
• Validation
• Localization
• Sorting Strategies
• Load Strategies
• Load Indication
• Requirement
• Compatibility

Demos

See Demos on project site.

Sample projects showing how to use jsGrid with the most popular backend technologies

• PHP - https://github.com/tabalinas/jsgrid-php
• ASP.NET WebAPI - https://github.com/tabalinas/jsgrid-webapi
• Express (NodeJS) - https://github.com/tabalinas/jsgrid-express
• Ruby on Rail - https://github.com/tabalinas/jsgrid-rails
• Django (Python) - https://github.com/tabalinas/jsgrid-django

Installation

Install jsgrid with bower:

$ bower install js-grid --save

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,

    insertRowLocation: "bottom",
    
    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: "...",

    invalidNotify: function(args) { ... }
    invalidMessage: "Invalid data entered!",
    
    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,
    pagerRenderer: 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,
    visible: true,

    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,
    
    validate: 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.
• visible is a boolean specifying whether to show a column or not. (version added: 1.3)
• 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.
• validate is a string as validate rule name or validation function or a validation configuration object or an array of validation configuration objects. Read more details about validation in the Validation section.

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