开源软件名称：

开源软件地址：

开源编程语言：

开源软件介绍：

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 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.

insertRowLocation (default: "bottom")

Specifies the location of an inserted row within the grid.
When insertRowLocation is "bottom" the new row will appear at the bottom of the grid. When set to "top", the new row will appear at the top.

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       // data item
     itemIndex  // data item index
     event      // jQuery 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       // data item
     itemIndex  // data item index
     event      // jQuery 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.

pagerContainer (default null)

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.

pagerFormat

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}     // link to first page
{prev}      // link to previous page
{pages}     // page links
{next}      // link to next page
{last}      // link to last page
{pageIndex} // current page index
{pageCount} // total amount of pages
{itemCount} // total amount of items

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.

invalidMessage (default "Invalid data entered!")

A string specifying the text of the alert message, when invalid data was entered.

invalidNotify

A function triggered, when invalid data was entered. By default all violated validators messages are alerted. The behavior can be customized by providing custom function.

The function accepts a single argument with the following structure:

{
    item                // inserting/editing item
    itemIndex           // inserting/editing item index
    errors              // array of validation violations in format { field: "fieldName", message: "validator message" }
}

In the following example error messages are printed in the console instead of alerting:

    
$("#grid")