JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 23088
  • Score
    100M100P100Q152313F
  • License

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

Package Exports

  • jsgrid

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (jsgrid) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

jsGrid Lightweight Grid jQuery Plugin

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.

jsGrid lightweight client-side data grid

Table of contents

Requirement

jQuery (1.8.3 or later)

Demo

See Demos on project site.

Compatibility

Desktop

  • Chrome
  • Safari
  • Firefox
  • Opera 15+
  • IE 8+

Mobile

  • Safari for iOS
  • Chrome for Android
  • IE10 for WP8

Basic Usage

Ensure that jQuery library of version 1.8.3 or later is included.

Include jsgrid.min.js 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) { ... },

    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,

    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: "",
    css: "",
    align: "",
    width: 100,

    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.
  • css is a string representing css classes to be attached to the table cell.
  • align is alignment of text in the cell. Accepts following values "left"|"center"|"right".
  • width is a width of the column.
  • 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       // data item
     itemIndex  // data item index
     event      // jQuery event
}

By default rowClick performs row editing when editing is true.

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

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.

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.

headerRowRenderer (default null)

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: { ... },      // simple text input
    number: { ... },    // number input
    select: { ... },    // select control
    checkbox: { ... },  // checkbox input
    textarea: { ... },  // textarea control (renders textarea for inserting and editing and text input for filtering)
    control: { ... }    // control field with delete and editing buttons for data rows, search and add buttons for filter and inserting row
}

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    // triggers searching when the user presses `enter` key in the filter input
}

number

Number field renders <input type="number"> in filter, inserting and editing rows.

Custom properties:

{
    sorter: "number",   // uses sorter for numbers
    align: "right"      // right text alignment
}

select

Select field renders <select> control in filter, inserting and editing rows.

Custom properties:

{
    align: "center",        // center text alignment
    autosearch: true,       // triggers searching when the user changes the selected item in the filter
    items: [],              // an array of items for select
    valueField: "",         // name of property of item to be used as value
    textField = "",         // name of property of item to be used as displaying value
    selectedIndex: -1       // index of selected item by default
}

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",   // uses sorter for numbers
    align: "center"     // center text alignment
    autosearch: true    // triggers searching when the user clicks checkbox in filter
}

textarea

Textarea field renders '