User Guide

Overview

The Wijmo Grid widget (wijgrid) is a datagrid that allows users to interactively select, edit, sort, scroll through, filter, and group data. The grid is highly customizable and can be used to better understand and visualize data more effectively.

The wijgrid widget is defined in the jquery.wijmo.wijgrid.js file. The image below illustrates some of its main elements.

NOTE: Please check the version history for an outline of new features, improvements, and changes to the Wijmo widgets.

Markup and Scripting

The wijgrid consumes a table HTML element. The markup used to create the wijgrid widget should resemble the following:

<table></table>

If wijgrid uses the table itself as a datasource, the table should contain data rows and optionally tHead section with column headers:

<table>
  <thead>
    <th>column0</th> ... <th>columnN</th>
  </thead>
  <tbody>
    <tr>
      <td>cell00</td> ... <td>cell0N</td>
    </tr>
    ...
    <tr>
      <td>cellN0</td> ... <td>cellNN</td>
    </tr>
  </tbody>
</table>

Cells should not contain colspan and/or rowspan attributes; cell and row attributes and styles are ignored.

You can initialize the wijgrid with the following code:

$("#table-element").wijgrid({
    data: [[0, "a"], [1, "b"], [2, "c"]]
});

Quick Start

The following topic demonstrates how to create a basic grid.

Create a new HTML page with the following markup:

<!DOCTYPE HTML>
<HTML>
<head>

<!-- Add references to dependencies from the Wijmo CDN. The ones below may not be the most recent; please reference the latest dependencies from the Wijmo CDN at http://wijmo.com/downloads/#wijmo-cdn. -->
<!--jQuery References-->
<script src="http://code.jquery.com/jquery-1.9.1.min.js" type="text/javascript"></script>
<script src="http://code.jquery.com/ui/1.10.1/jquery-ui.min.js" type="text/javascript"></script>
 
<!--Theme-->
<link href="http://cdn.wijmo.com/themes/rocket/jquery-wijmo.css" rel="stylesheet" type="text/css" />
 
<!--Wijmo Widgets CSS-->
<link href="http://cdn.wijmo.com/jquery.wijmo-pro.all.3.20131.1.min.css" rel="stylesheet" type="text/css" />
 
<!--Wijmo Widgets JavaScript-->
<script src="http://cdn.wijmo.com/jquery.wijmo-open.all.3.20131.1.min.js" type="text/javascript"></script>
<script src="http://cdn.wijmo.com/jquery.wijmo-pro.all.3.20131.1.min.js" type="text/javascript"></script>

<!-- Initialize the widget and populate the wijgrid with data -->
<script id="scriptInit" type="text/javascript">
        $(document).ready(function () {
            $("#wijgrid").wijgrid({
                allowSorting: true,
                allowPaging: true,
                pageSize: 3,
                data: [
                    [27, 'Canada', 'Adams, Craig', 'RW'],
                    [43, 'Canada', 'Boucher, Philippe', 'D', 'R'],
                    [24, 'Canada', 'Cooke, Matt', 'LW', 'L'],
                    [87, 'Canada', 'Crosby, Sidney (C)', 'C', 'L'],
                    [1, 'United States', 'Curry, John', 'G', 'L'],  
                ],
                columns: [
                    { headerText: "Number" }, 
                    { headerText: "Nationality" }, 
                    { headerText: "Player" }, 
                    { headerText: "Position" }
                ]
            });
        });
    </script>
</head>
<body>
     <!--Create the grid -->
     <table id="wijgrid">
     </table>

</body>
</HTML>

Take a look at this line in the script:

$("#wijgrid").wijgrid({

The selector $("#wijgrid") finds the first element with the id "wijgrid", or in this case the table element <table id="wijgrid">. The second part of that markup tells the page to use the wijgrid widget. The markup that follows specifies the grid options:

The allowSorting option is set to true, allowing users to click a column header to sort the data by that column.
The allowPaging option is set to true, allowing users to click the page numbers at the bottom of the grid to move through the pages of data.
The pageSize option is set to 3, specifying three rows of data to a page.
The data option specifies the content of each row.
The columns option provides the header text for each column.

The wijgrid widget appears like the following image:

Concepts

Adaptive for Mobile Use

This widget is an adaptive widget in v3. If you are running v2.3.x, it is not adaptive. You can download v3 2013 1 here: Downloads Page.

An adaptive widget is different from a jQuery UI widget in that you can use it in both mobile and non-mobile web applications. To use it in non-mobile applications, just use the regular help. To use it in mobile applications:

Use jQuery Mobile instead of jQuery UI references
Do not initialize the widget in script (unless you need to for complex widgets like charts)
Use the data-role attribute to create the widget in markup

These steps are demonstrated in the Adaptive Widgets for jQuery Mobile topic.

Binding Wijgrid with Knockout

This example will show you how to create a grid bound with Knockout that allows users to dynamically add a new row. See the Knockout Grid sample to view the live sample.

Create a new HTML page with the following markup:

<!DOCTYPE HTML>
<HTML>
<head>

<!--Add the jQuery References-->
<script src="http://code.jquery.com/jquery-1.9.1.min.js" type="text/javascript"></script>
<script src="http://code.jquery.com/ui/1.10.1/jquery-ui.min.js" type="text/javascript"></script>
  
<!--Add a Theme-->
<link href="http://cdn.wijmo.com/themes/rocket/jquery-wijmo.css" rel="stylesheet" type="text/css" />
  
<!--Add the Wijmo Widgets CSS-->
<link href="http://cdn.wijmo.com/jquery.wijmo-pro.all.3.20131.1.min.css" rel="stylesheet" type="text/css" />
  
<!--Add the Wijmo Widgets JavaScript reference-->
<script src="http://cdn.wijmo.com/jquery.wijmo-open.all.3.20131.1.min.js" type="text/javascript"></script>
<script src="http://cdn.wijmo.com/jquery.wijmo-pro.all.3.20131.1.min.js" type="text/javascript"></script>
 
 
<!--Add a reference to the Knockout JS Library-->
<script src="http://cdn.wijmo.com/wijmo/external/knockout-2.2.0.js" type="text/javascript"></script>
  
<!--Add a reference to the Wijmo Knockout Integration Library-->
<script src="http://cdn.wijmo.com/interop/knockout.wijmo.3.20131.1.js" type="text/javascript"></script>

<script type="text/javascript">
        
<!-- Create a view model to define the data and behavior of the UI-->
       function Person(data) { 
          this.ID = ko.observable(data.ID); 
          this.Company = ko.observable(data.Company); 
          this.Name = ko.observable(data.Name); 
       }; 
  
       var viewModel = { 
              data: ko.observableArray([ 
                  new Person({ ID: "ANATR", Company: "Ana Trujillo Emparedados y  helados", Name: "Ana Trujillo" }), 
                  new Person({ ID: "ANTON", Company: "Antonio Moreno Taqueria", Name:  "Antonio Moreno" }), 
                  new Person({ ID: "AROUT", Company: "Around the Horn", Name: "Thomas  Hardy" }), 
                  new Person({ ID: "BERGS", Company: "Berglunds snabbkop", Name:  "Christina Berglund" }) 
              ]) 
           }; 
  
 <!-- Bind to the ViewModel and activate knockout.js -->
       $(document).ready(function () { 
           ko.applyBindings(viewModel, $(".container").get(0)); 
        }); 
  
        function addRow() { 
           var len = viewModel.data().length; 
           viewModel.data.push(new Person({ ID: "ID" + len, Company: "Company" + len,  Name: "Name" + len })); 
        }; 
    </script>
 
</head>
<body>
     <!--Create the grid -->
     <table id="dataGrid" data-bind="wijgrid: { data: data, allowEditing: true }"> 
     </table>  

     <!--Create a button for users to click to dynamically add rows -->
     <input type="button" id="btnAddRow" onclick="addRow()" value="Add row" />        
</body>
</HTML>

Note: The versions of the .js files named in this example may not be the most recent. Please reference the latest dependencies from the Wijmo CDN at http://wijmo.com/downloads/#wijmo-cdn.

As this sample markup shows, the steps to binding wijgrid with Knockout include:

Add references to dependencies from the Wijmo CDN, including references to the Knockout JS library and the Knockout extension library for Wijmo.
Create the ViewModel. In this example, four people, including their ID, Company, and name, will appear in the grid; they are defined in the ViewModel.
Create the View, or in this example, the grid and "Add row" button.
Bind wijgrid to the ViewModel and activate KO.

The rendered wijgrid looks like the following image. Users can click the "Add row" button to dynamically add rows to the grid.

Loading Data Dynamically

The dynamic data load feature in wijgrid allows:

Loading only the data visible on the current page (if paging is enabled).
Handling filtering, sorting, total aggregates, and paging on the server.

In the data option of wijgrid, create a new wijdatasource and set its dynamic option to true like this:

$("#demo").wijgrid({
        ...
        data: new wijdatasource({
            ...
            dynamic: true
            ...
        })
        ...
    });

Wijgrid does not reshape data in this mode. When wijgrid needs to get data, it collects reshaping settings into a single object and calls the load() method of the bound wijdatasource passing this object in the userData argument: wijdatasource.load(reshapingSettings, true)

Notes: If the wijdatasource.proxy is set, then before calling the load() method, wijgrid merges the reshaping settings object with wijdatasource.proxy.options.data. Thus if wijhttpproxy is used as a proxy, then reshaping settings will be automatically passed to server.

Reshaping settings object has the following format:

{
filtering: array of { dataKey, filterOperator, filterValue },
paging: { pageIndex, pageSize },
sorting: array of { dataKey, sortDirection },
totals: array of { dataKey, aggregate }
}

where:

filtering – An array of filtered columns settings, each item in the array corresponds to a column and has the following column fields:
- dataKey
- filterOperator
- filterValue
paging – Paging settings have the following fields:
- pageIndex – wijgrid.pageIndex value.
- pageSize – wijgrid.pageSize value.
sorting – An array of sorted columns; each item in the array corresponds to a column and has the following column fields:
- dataKey
- sortDirection
totals – An array of columns for which aggregate values are calculated; each item in the array corresponds to a column and has the following column fields:
- dataKey
- aggregate

Wijgrid constructs its wrapper for the wijdatasource.reader object and assumes that when the read() method is called, the wijdatasource.data option has the following object:

{
   rows: array,
   totalRows: int, 
   totals: one dimensional array or object
}

where:

rows – An array of data items to display. If paging is enabled, only the current page data should be returned.
totalRows – The total number of items in the dataset (filtered rows should be excluded).
totals – An optional parameter containing calculated aggregate values for columns specified in the totals option of reshaping settings object. This should have the same dimension as a single data item. For example, if the data item looks like this:

{ ID: idValue, Name: nameValue. Phone: phoneValue }

then totals should look like the following:

{ ID: idTotalsValue, Name: nameTotalsValue, Phone: phoneTotalsValue }

If totals for a particular column are not calculated, then you can provide null for this column in the totals parameter.

Notes: If the wijdatasource.data.rows option is empty or is not an array, wijgrid tries to get data items from the wijdatasource.data.items and wijdatasource.data. Please see the Custom paging sample for an example.

Loading Remote Data

This example will demonstrate how to load data from a remote wijdatasource using the data option. See the Data sources sample to view the live sample.

Create a new HTML page with the following markup:

<!DOCTYPE HTML>
<HTML>
<head>

<!-- Add references to dependencies from the Wijmo CDN -->
<!-- Add references to dependencies from the Wijmo CDN. The ones below may not be the most recent; please reference the latest dependencies from the Wijmo CDN at http://wijmo.com/downloads/#wijmo-cdn. -->
<!--jQuery References-->
<script src="http://code.jquery.com/jquery-1.9.1.min.js" type="text/javascript"></script>
<script src="http://code.jquery.com/ui/1.10.1/jquery-ui.min.js" type="text/javascript"></script>
 
<!--Theme-->
<link href="http://cdn.wijmo.com/themes/rocket/jquery-wijmo.css" rel="stylesheet" type="text/css" />
 
<!--Wijmo Widgets CSS-->
<link href="http://cdn.wijmo.com/jquery.wijmo-pro.all.3.20131.1.min.css" rel="stylesheet" type="text/css" />
 
<!--Wijmo Widgets JavaScript-->
<script src="http://cdn.wijmo.com/jquery.wijmo-open.all.3.20131.1.min.js" type="text/javascript"></script>
<script src="http://cdn.wijmo.com/jquery.wijmo-pro.all.3.20131.1.min.js" type="text/javascript"></script>

<!-- Initialize wijgrid -->
<script id="scriptInit" type="text/javascript">
        $(document).ready(function () {
<!-- Populate wijgrid with data from a remote data source-->
          $("#remotedata").wijgrid({
                data: new wijdatasource({
                    proxy: new wijhttpproxy({
                        url: "http://ws.geonames.org/searchJSON",
                        dataType: "jsonp",
                        data: {
                            featureClass: "P",
                            style: "full",
                            maxRows: 5,
                            name_startsWith: "ab"
                        },
                        key: "geonames"
                    }),
                    reader: new wijarrayreader([
                     { name: "label", mapping: function (item) { return item.name  
+ (item.adminName1 ? ", " + item.adminName1 : "") + ", " + item.countryName } },
                     { name: "name", mapping: "name" },
                     { name: "countryCode", mapping: "countryCode" },
                     { name: "continentCode", mapping: "continentCode" }
                  ])
                })
            });
        });
    </script>

</head>
<body>
     <!--Create the grid -->
<table id="remotedata">
            </table>

</body>
</HTML>

The rendered wijgrid looks like the following:

Updating Data in a Wijgrid

The following markup shows the correct way to change underlying data in a wijgrid:

 $("#demo").wijgrid({
       data: [
               [0, "Dabolio"],
               [1, "Fuller"]
       ]
 });

 $("#btn").click(function() {
      var $obj = $("#demo"),
           data = $obj.wijgrid("data"); // get underlying data 

      data[0][1] = "Davolio"; // change "Dabolio" to "Davolio" 
      data.push([2, "Leverling"]); // add a new item 

      $obj.wijgrid("ensureControl", true);  // re-render wijgrid 
});

The data format of the structure returned by the data() method is the same as the original dataset. If the format was an HTML table or 2D array, a 2D array would be returned. If the format was an array of objects, an array of objects would be returned.

API

Enumerations

The wijmo.wijgrid widget includes the following enumerations:

renderState

This enumeration can be used with the cellStyleFormatter and rowStyleFormatter options to get a formatted object state. Members include:

none: This is the normal state. The object is rendered and not hovered, selected, or one of the elements determining the current position of the wijgrid.; Value: 0

rendering: The object is being rendered. In the cellStyleFormatter, the rendered object is a table cell. In the rowStyleFormatter, the object is a table row.; Value: 1

current: The object is one of the elements determining the current position of the wijgrid.; Value: 2

hovered: The object is hovered over.; Value: 4

selected: The object is selected.; Value: 8

rowType

Specifies the type of a row in the grid. Members include:

header: The header row.; Value: 1

data: Data row; Value: 2

dataAlt: Alternating data row (used only as modifier of the rowType.data, not as an independent value).; Value: 4

filter: Filter row; Value: 8

footer: Footer row.; Value: 64

groupHeader: Group header row.; Value: 16

groupFooter: Group footer row.; Value: 32

Options

The wijmo.wijgrid widget includes the following options:

allowColMoving

A value indicating whether columns can be moved.

Type: Boolean

Default: false

Remarks: This option must be set to true in order to drag column headers to the group area.

Sample: See the Column moving sample.

Code Example:

/* Columns cannot be dragged and moved if this option is set to false */
$("#element").wijgrid({ 
         allowColMoving: false 
});

allowColSizing

Determines whether the column width can be increased and decreased by dragging the sizing handle, or the edge of the column header, with the mouse.

Type: Boolean

Default: false

Sample: See the Column resizing sample.

Code Example:

/* The sizing handle cannot be dragged and column width cannot be changed if this option is set to false */
$("#element").wijgrid({ 
   allowColSizing: false
});

allowEditing

Determines whether the user can make changes to cell contents in the grid.

Type: Boolean

Default: false

Sample: See the Editing sample.

Code Example:

/* Users cannot change cell contents in the grid if this option is set to false */
$("#element").wijgrid({ 
   allowEditing: false
});

allowKeyboardNavigation

Determines whether the user can move the current cell using the arrow keys.

Type: Boolean

Default: false

Code Example:

/* Users cannot move the selection using arrow keys if this option is set to false */
$("#element").wijgrid({ 
   allowKeyboardNavigation: false
});

allowPaging

Determines whether the grid should display paging buttons. The number of rows on a page is determined by the pageSize option.

Type: Boolean

Default: false

Sample: See the Paging sample.

Code Example:

/* Grid displays paging buttons when allowPaging is true. The pageSize here sets 5 rows to a page.*/
$("#element").wijgrid({ 
   allowPaging: true,
   pageSize: 5
});

allowSorting

Determines whether the widget can be sorted by clicking the column header.

Type: Boolean

Default: false

Sample: See the Sorting sample.

Code Example:

/* Sort a column by clicking its header when allowSorting is set to true. */
$("#element").wijgrid({ 
   allowSorting: true
});

allowVirtualScrolling

A value that indicates whether virtual scrolling is allowed. The pageSize option determines the limit of simultaneously rendered rows when virtual scrolling is used. Set allowVirtualScrolling to true when using large amounts of data to improve efficiency.

Remarks: This option is ignored if the grid uses paging, columns merging or fixed rows. This option cannot be enabled when using dynamic wijdatasource.

Type: Boolean

Default: false

Code Example:

$("#element").wijgrid({ allowVirtualScrolling: false });

alwaysParseData

Determines whether wijgrid should parse underlying data at each operation requiring data re-fetching, like calling the ensureControl(true) method, paging, sorting, and so on. If the option is disabled, wijgrid parses data only at the first fetch. The option is ignored if the dynamic data load feature is used; in this case data is always parsed.

Remarks: At each data fetch, wijgrid assumes that the data changed completely and parses it again. This can have a negative impact on performance with large amounts of data. The developer can disable this behavior, but in this case, he is responsible for data having a valid data type.

Type: Boolean

Default: true

Code Example:

$("#demo").wijgrid({
  data: [ {ID: 0, Name: “Susan” } ],
  alwaysParseData: false,
  columns:[ { dataType: “number” }]
});

…

var data = $(“#demo”).wijgrid(“data”);
  data.push({ID: “1”, Name: “Alice” }); // incorrect
  data.push({ID: 1, Name: “Alice” }); // correct

cellStyleFormatter

Function used for styling the cells in wijgrid.

Remarks: Parameters include:

$cell: jQuery object that represents cell to format.
column: Options of the column to which the cell belongs.
state: State of a cell to format; the following $.wijmo.wijgrid.renderState values or their combination can be applied to the cell: rendering, current, selected.
row: Information about associated row.
row.$rows: jQuery object that represents rows to format.
row.data: Associated data.
row.dataRowIndex: Data row index.
row.dataItemIndex: Data item index.
row.virtualDataItemIndex: Virtual data item index.
row.type: Type of the row, one of the $.wijmo.wijgrid.rowType values.

Returns true if wijgrid does not apply the default formatting.

Type: Function

Default: undefined

Code Example:

// Make the text of the current cell italic.
$("#element").wijgrid({
  highlightCurrentCell: true,
  cellStyleFormatter: function(args) {
    if ((args.row.type & $.wijmo.wijgrid.rowType.data)) {
      if (args.state & $.wijmo.wijgrid.renderState.current) {
        args.$cell.css("font-style", "italic");
       } else {
        args.$cell.css("font-style", "normal");
       }
    }
  }
});

columns

An array of column options. For example, the following array sets up the columns as shown in the image:

columns: [                     
    { dataType: "number", sortDirection: "ascending", dataFormatString: "n0" },              
    { dataType: "currency" }, 
    { dataType: "number", dataFormatString: "n0" },                     
    { dataType: "number", dataFormatString: "p0" }                 
]});

Type: Array

Default: []

Code Example:

$("#element").wijgrid(
 { 
      columns: [ 
           { headerText: "column0", allowSort: false }, 
           { headerText: "column1", dataType: "number" } 
      ] 
  });

columnsAutogenerationMode

Determines behavior for column autogeneration. Possible values are: "none", "append", "merge".

Remarks:

Possible values are:

"none": Column auto-generation is turned off.
"append": A column will be generated for each data field and added to the end of the columns collection.
"merge": Each column having dataKey option not specified will be automatically bound to the first unreserved data field. For each data field not bound to any column a new column will be generated and added to the end of the columns collection. To prevent automatic binding of a column to a data field set its dataKey option to null.

Note: Autogenerated columns are added to the columns collection.

Type: String.

Default: "merge"

Code Example:

$("#element").wijgrid({ columnsAutogenerationMode: "merge" });

culture

Determines the culture ID.

Type: String

Default: ""

Code Example:

/* This markup sets the culture to English. */
$("#element").wijgrid({ 
   culture: "en"
});

customFilterOperators

An array of custom user filters. Use this option if you want to extend the default set of filter operators with your own. Custom filters will be shown in the filter dropdown.

Remarks:

Custom user filter is an object which contains the following properties:

name: Operator name.
arity: The number of filter operands. Can be either 1 or 2.
applicableTo: An array of datatypes to which the filter can be applied. Possible values for elements of the array are "string", "number", "datetime", "currency" and "boolean".
operator: Comparison operator; the number of accepted parameters depends on the arity. The first parameter is a data value, the second parameter is a filter value.

Type: Array

Default: []

Code Example:

var oddFilterOp = {
    name: "customOperator-Odd",
    arity: 1,
    applicableTo: ["number"],
    operator: function(dataVal) { return (dataVal % 2 !== 0); }
}
$("#element").wijgrid({ customFilterOperators: [oddFilterOp] });

data

Determines the datasource.

Possible datasources include:

A DOM table. This is the default datasource, used if the data option is null. The table must have no cells with rowSpan and colSpan attributes.
A two-dimensional array, such as [[0, "a"], [1, "b"]].
An array of objects, such as [{field0: 0, field1: "a"}, {field0: 1, field1: "b"}].
A wijdatasource.

Remarks:

Wijdatasource usage details:

1. Wijgrid converts field values to column target types.

2. Wijgrid wraps loading, loaded, proxy.error event handlers and a reader object with its own code implementation.

Pass a copy of the original wijdatasource if these do not work for you:

  $('#demo').wijgrid({
      data: $.extend(true, {}, wijdatasourceInstance)
  });

Type: Object

Default: null

Sample: See the Data sources sample.

Code example:

/* DOM table */
$("#element").wijgrid();

/* two-dimensional array */
$("#element").wijgrid({ 
   data: [
      [0, "a"], 
      [1, "b"]
   ]
});

ensureColumnsPxWidth

Determines if the exact column width, in pixels, is used.

Type: Boolean

Default: false

Remarks: By default, wijgrid emulates the table element behavior when using a number as the width. This means wijgrid may not have the exact width specified. If exact width is needed, please set the ensureColumnsPxWidth option of wijgrid to true. If this option is set to true, wijgrid will not expand itself to fit the available space. Instead, it will use the width option of each column widget.

Code example:

$("#element").wijgrid({ ensureColumnsPxWidth: false });

filterOperatorsSortMode

Determines the order of items in the filter drop-down list.

Remarks:

Possible values include: "none", "alphabetical", "alphabeticalCustomFirst" and "alphabeticalEmbeddedFirst".

"none": Operators follow the order of addition; built-in operators appear before custom ones.
"alphabetical": Operators are sorted alphabetically.
"alphabeticalCustomFirst": Operators are sorted alphabetically with custom operators appearing before built-in ones.
"alphabeticalEmbeddedFirst": Operators are sorted alphabetically with built-in operators appearing before custom operators.

Note: "NoFilter" operator is always first.

Type: String

Default: "alphabeticalCustomFirst"

Code Example:

$("#element").wijgrid({ filterOperatorsSortMode: "alphabeticalCustomFirst" });

groupAreaCaption

Determines the caption of the group area.

Type: String

Default: "Drag a column here to group by that column."

Sample: See the Group area sample.

Code Example:

/* Set the groupAreaCaption to a string and the text appears above the grid. */
$("#element").wijgrid({ 
   groupAreaCaption: "Drag a column here to group by that column."
});

groupIndent

Determines the indentation of the groups, in pixels.

Type: Number

Default: 10

Sample: See the Grouping and aggregates sample.

Code Example:

/* Set the groupIndent option to the number of pixels to indent data when grouping. */
$("#element").wijgrid({ 
   groupIndent: 50
});

highlightCurrentCell

Determines whether the position of the current cell is highlighted or not.

Type: Boolean

Default: false

Code Example:

$("#element").wijgrid({ highlightCurrentCell: false });

loadingText

Determines the text to be displayed when the grid is loading.

Default: "Loading..."

Code Example:

$("#element").wijgrid({ loadingText: "Loading..."});

nullString

Cell values equal to this property value are considered null values. Use this option if you want to change default representation of null values (empty strings) with something else.

Remarks: Case-sensitive for built-in parsers.

Type: String

Default: undefined

Code Example:

$("#element").wijgrid({ nullString: "" });

pageIndex

Determines the zero-based index of the current page. You can use this to access a specific page, for example, when using the paging feature.

Type: Number

Default: 0

Sample: See the Paging sample.

Code Example:

$("#element").wijgrid({ pageIndex: 0 });

pageSize

Number of rows to place on a single page.

Type: Number

Default: 10

Sample: See the Paging sample.

Code Example:

/* The pageSize here sets 10 rows to a page. The allowPaging option is set to true so paging buttons appear. */
$("#element").wijgrid({ 
   allowPaging: true,
   pageSize: 10
});

pagerSettings

Determines the pager settings for the grid including the mode (page buttons or next/previous buttons), number of page buttons, and position where the buttons appear.

Type: Object

Default: { mode: "numeric", pageButtonCount: 10, position: "bottom" }

Remarks: See the Pager widget documentation for more information on pager settings.

Possible values for the mode are:

"nextPrevious": A set of pagination controls consisting of Previous and Next buttons.
"nextPreviousFirstLast": A set of pagination controls consisting of Previous, Next, First, and Last buttons.
"numeric": A set of pagination controls consisting of numbered link buttons to access pages directly.
"numericFirstLast": A set of pagination controls consisting of numbered and First and Last link buttons.

Possible values for the position are:

"bottom": Page buttons appear below the grid.
"top": Page buttons appear above the grid.
"topAndBottom": Page buttons appear above and below the grid.

Sample: See the Paging sample.

Code Example:

<script id="scriptInit" type="text/javascript">
        $(document).ready(function () {
            $("#wijgrid").wijgrid({
                /* Page buttons are displayed and there are 3 rows to a page */
                allowPaging: true,
                pageSize: 3,

               /* The pagerSettings option here specifies Previous and Next buttons that appear above and below the grid.  */
                pagerSettings:{
                        mode: "nextPrevious",
                        position: "topAndBottom"},

                data: [ 
                               [27, 'Canada', 'Adams, Craig', 'RW'],
                               [43, 'Canada', 'Boucher, Philippe', 'D'],
                               [24, 'Canada', 'Cooke, Matt', 'LW'],
                               [87, 'Canada', 'Crosby, Sidney (C)', 'C'],
                               [1, 'United States', 'Curry, John', 'G' ],
                               [9, 'Canada', 'Dupuis, Pascal', 'W'],
                         ],
                columns: [
                                  { headerText: "Number" }, { headerText: "Nationality"},
                                  { headerText: "Player" }, { headerText: "Position" },            
                               ]
            });
        });
    </script>

readAttributesFromData

A value indicating whether DOM cell attributes can be passed within a data value.

Type: Boolean

Default: false

Code Example:

Code example: $("#element").wijgrid({ readAttributesFromData: false });

This option allows binding a collection of values to data and automatically converting them as attributes of corresponding DOM table cells during rendering.

Values should be passed as an array of two items, where the first item is a value of the data field and the second item is a list of values:

Code example: $("#element").wijgrid({
  data: [
    [ [1, { "style": "color: red", "class": "myclass" } ], a ]
  ]
});

or:

$("#element").wijgrid({
  data: [
    { col0: [1, { "style": "color: red", "class": "myclass" }], col1: "a" }
  ]
});

Note: During conversion, wijgrid extracts the first item value and makes its data a field value; the second item (list of values) is removed:

[ { col0: 1, col1: "a" } ]

If a DOM table is used as a datasource, then attributes belonging to the cells in the tBody section of the original table will be read and applied to the new cells.

rowSpan and colSpan attributes are not allowed.

rowStyleFormatter

Function used for styling rows in wijgrid.

Remarks: The parameters include:

state: state of a row to format, the following $.wijmo.wijgrid.renderState values or their combination can be applied to the row: rendering, current, hovered.
$rows: jQuery object that represents rows to format.
data: associated data.
dataRowIndex: data row index.
dataItemIndex: data item index.
virtualDataItemIndex: virtual data item index.
type: type of the row, one of the $.wijmo.wijgrid.rowType values.

Returns true if wijgrid should not apply the default formatting.

Type: Function

Default: undefined

Sample: See the Cell and row formatting sample.

Code Example:

This example shows how to make the text for alternating rows italic.

// Make text of the alternating rows italic.
$("#demo").wijgrid({
  data: [
    [0, "Nancy"], [1, "Susan"], [2, "Alice"], [3, "Kate"]
  ],
  rowStyleFormatter: function (args) {
    if ((args.state === $.wijmo.wijgrid.renderState.rendering) && (args.type & $.wijmo.wijgrid.rowType.dataAlt)) {
      args.$rows.find("td").css("font-style", "italic");
    }
  }
});

scrollMode

Determines which scrollbars are active and if they appear automatically based on content size.

Remarks: Possible values are: "none", "auto", "horizontal", "vertical", and "both".

"none": Scrolling is not used; the staticRowIndex and staticColumnIndex values are ignored.
"auto": Scrollbars appear automatically depending upon content size.
"horizontal": The horizontal scrollbar is active.
"vertical": The vertical scrollbar is active.
"both": Both horizontal and vertical scrollbars are active.

Type: String

Default: "none"

Sample: See the Scolling sample.

Code Example:

$("#element").wijgrid({
     /* The horizontal and vertical scrollbars are active when the scrollMode is set to both. */  
     scrollMode: "both" 
});

selectionMode

Determines which cells, range of cells, columns, or rows can be selected at one time.

Remarks: Possible values are: "none", "singleCell", "singleColumn", "singleRow", "singleRange", "multiColumn", "multiRow" and "multiRange".

"none": Selection is turned off.
"singleCell": Only a single cell can be selected at a time.
"singleColumn": Only a single column can be selected at a time.
"singleRow": Only a single row can be selected at a time.
"singleRange": Only a single range of cells can be selected at a time.
"multiColumn": It is possible to select more than one row at the same time using the mouse and the CTRL or SHIFT keys.
"multiRow": It is possible to select more than one row at the same time using the mouse and the CTRL or SHIFT keys.
"multiRange": It is possible to select more than one cells range at the same time using the mouse and the CTRL or SHIFT keys.

Type: String

Default: "singleRow"

Sample: See the Selection sample.

Code Example:

$("#element").wijgrid({ 
        /* Set selectionMode to muliColumn and users can select more than one column using the CTRL or SHIFT keys. */ 
        selectionMode: "multiColumn"
   });

showFilter

A value indicating whether the filter row is visible.

Type: Boolean

Default: false

Sample: See the Filtering sample.

Code Example:

$("#element").wijgrid({ 
/* Set showFilter to true to view the filter row as shown in the previous image. */
    showFilter: true
});

showFooter

A value indicating whether the footer row is visible.

Type: Boolean

Default: false

Code Example:

<script id="scriptInit" type="text/javascript">
        $(document).ready(function () {
            $("#wijgrid").wijgrid({
                /* Setting showFooter to true makes the footer row, specified in the <body> tags, visible. */
                showFooter: true,
                data: [ 
                    [27, 'Canada', 'Adams, Craig', 'RW'],
                    [43, 'Canada', 'Boucher, Philippe', 'D'],
                    [24, 'Canada', 'Cooke, Matt', 'LW'],
                    [87, 'Canada', 'Crosby, Sidney (C)', 'C'],
                    [1, 'United States', 'Curry, John', 'G' ],
                    [9, 'Canada', 'Dupuis, Pascal', 'W'],
                 ],
                 columns: [
                       { headerText: "Number" }, { headerText: "Nationality"},
                       { headerText: "Player" }, { headerText: "Position" },
                 ]
            });
        });
    </script>

</head>
<body>
  <table id="wijgrid">
  </table>
  /* The footer row text is specified here. */
  <div class="footer demo-description">             
     <p>This sample demonstrates the default wijgrid behavior.</p>
  </div> 
</body>

showGroupArea

A value indicating whether the group area is visible.

Type: Boolean

Default: false

Sample: See the Group area sample.

Code Example:

$("#element").wijgrid({ showGroupArea: false });

showRowHeader

A value indicating whether the row header is visible.

Type: Boolean

Default: false

Code Example:

$("#element").wijgrid({ showRowHeader: false });

showSelectionOnRender

A value indicating whether a selection will be automatically displayed at the current cell position when the wijgrid is rendered. Set this option to false if you want to prevent wijgrid from selecting the currentCell automatically.

Type: Boolean

Default: true

Code Example:

$("#element").wijgrid({ showSelectionOnRender: true});

staticColumnIndex

Indicates the index of columns that will always be shown on the left when the grid view is scrolled horizontally. Note that all columns before the static column will be automatically marked as static, too. This can only take effect when the scrollMode option is not set to "none". It will be considered "-1" when grouping or row merging is enabled. A "-1" means there is no data column but the row header is static. A zero (0) means one data column and row header are static.

Type: Number

Default: -1

Code Example:

$("#element").wijgrid({ staticColumnIndex: -1 });

staticRowIndex

Indicates the index of data rows that will always be shown on the top when the wijgrid is scrolled vertically. Note, that all rows before the static row will be automatically marked as static, too. This can only take effect when the scrollMode option is not set to "none". This will be considered "-1" when grouping or row merging is enabled. A "-1" means there is no data row but the header row is static. A zero (0) means one data row and the row header are static.

Type: Number

Default: -1

Code Example:

$("#element").wijgrid({ staticRowIndex: -1 });

totalRows

Gets or sets the virtual number of items in the wijgrid and enables custom paging. Setting option to a positive value activates custom paging, the number of displayed rows and the total number of pages will be determined by the totalRows and pageSize values.

Remarks: In custom paging mode sorting, paging and filtering are not performed automatically. This must be handled manually using the sorted, pageIndexChanged, and filtered events. Load the new portion of data there followed by the ensureControl(true) method call.

Type: Number

Default: -1

Code Example:

$("#element").wijgrid({ totalRows: -1 });

Events

The wijmo.wijgrid widget includes the following events:

afterCellEdit

The afterCellEdit event handler is a function called after cell editing is completed. This function can assist you in completing many tasks, such as in making changes once editing is completed; in tracking changes in cells, columns, or rows; or in integrating custom editing functions on the front end.

Parameters:

e: jQuery.Event object. This parameter's type is Object.
args: The data with this event. This parameter's type is Object.

args.cell: An instance of the wijmo.grid.cellInfo class. This parameter gets the edited cell's information.
args.event: This is the event that initiates the cell update.
args.handled: This parameter gets or sets a value that determines how cell editing is finalized: automatically or manually. The possible values are "true" or "false." The default value is "false," which means that the widget will try to finalize cell editing automatically by applying the column's cell formatter to the cell. If this behavior is not suitable for you, then this property must be set to "true."

Type: Function

Default: null

Code Examples:

You can see the afterCellEdit event in use in the Custom editors sample. Here's the script calling the afterCellEdit function:

function afterCellEdit(e, args) { 
            switch (args.cell.column().dataKey) { 
                case "Position": 
                    args.cell.container().find("input").wijcombobox("destroy"); 
                    break; 
  
                case "Acquired": 
                    args.cell.container().find("input").wijinputnumber("destroy"); 
                    break; 
            } 
        }

In this sample, once cell editing is complete, the function calls the destroy method to destroy the wijcombobox widget and the wijinputnumber widget which are used as the custom editors.

In the Editing sample, you can see a simpler afterCellEdit event handler:

 function onAfterCellEdit(e, args) {
            $(args.cell.container())
                  .removeClass("ui-state-error");

In this sample, once cell editing has been completed, and a user-entered incorrect value has been corrected or removed, the "ui-state-error" class is removed.

This is the general form for supplying a callback function to handle the afterCellEdit event:

$("#element").wijgrid({ 
          afterCellEdit: function (e, args) { 
                //Handle the afterCellEdit event here. 
      } 
});

You can bind to the event either by type or by name.

This format binds by type to the event after the wijgrid is created:

$("#element").bind("wijgridaftercelledit", function (e, args) {
                 //some code here });

Or you can bind to the event by name. In this sample onAfterCellEdit is the custom function that will handle the event:

$("#element").wijgrid({ afterCellEdit: onAfterCellEdit });

afterCellUpdate

The afterCellUpdate event handler is a function that is called after a cell has been updated. Among other functions, this event allows you to track and store the indices of changed rows or columns.

Parameters:

e: The jQuery.Event object. This parameter's type is Object.
args: The data with this event. This parameter's type is Object.

args.cell: An instance of the wijmo.grid.cellInfo class.This property gets the edited cell's information.

Type: Function

Default: null

Code Examples:

You can see the afterCellUpdate event in both the Editing and the Custom editors samples. Here's the script sample from the Custom editors sample:

 function afterCellUpdate(e, args) {
            $("#log").html(dump($("#demo").wijgrid("data")));
        }

In the sample above, once the cell has been updated, the information from the cell is dumped into the "#log" element.

This is the general form for supplying a callback function to handle the afterCellUpdate event:

$("#element").wijgrid({ afterCellUpdate: function (e, args) {
             //Handle afterCellEdit here
       } 
});

You can bind to the event in two ways: by type or by name.

Binding to the event by type allows you to bind the event handler after the wijgrid is created:

$("#demo").bind("wijgridaftercellupdate", function (e, args) { });

Binding by name allows you to bind to a named function. In this sample, onAfterCellUpdate is your custom function that will handle the event:

$("#demo").wijgrid({ afterCellUpdate: onAfterCellUpdate });

ajaxError

The ajaxError event handler is a function that is called when the wijgrid is bound to remote data and the ajax request fails. This is an optional Ajax setting that is not called for cross-domain script and cross-domain JSONP requests.

Parameters:

e: The jQuery.Event object. This parameter's type is Object.
args: The data corresponding with this event. This parameter's type is Object.

args.XMLHttpRequest: the XMLHttpRequest object.
args.textStatus: A string describing the error type. The possible values are null, timeout, error, abort, or parseerror.
args.errorThrown: An optional exception object that receives the textual part of the HTTP status, such as "Not Found" or "Internal Server Error."

Refer to the jQuery.ajaxError event documentation for more information about these arguments.

Type: Function

Default: null

Code Example:

In the following sample, you trigger an alert when there is an error during the ajax request that informs the user that there was an error and gives them the error type:

$("#element").wijgrid({ 
        ajaxError: function (e, args) { 
           alert(“An error occurred during an ajax request: ” + args.textStatus); 
        } 
  });

This is the general form for supplying a callback function to handle the ajaxError event:

$("#element").wijgrid({ 
        ajaxError: function (e, args) { 
             //Handle the ajaxError event here
     } 
  });

You can bind to the event in two ways: by type or by name.

Binding to the event by type allows you to bind the event handler after the wijgrid is created:

$("#element").bind("wijgridajaxerror", function (e, args) { });

Binding by name allows you to bind to a named function. In this sample, onAjaxError is your custom function that will handle the event:

$("#element").wijgrid({ ajaxError: onAjaxError });

beforeCellEdit

The beforeCellEdit event handler is a function that is called before a cell enters edit mode. The beforeCellEdit event handler assists you in appending a widget, data, or other item to a wijgrid's cells before the cells enter edit mode. This event is cancellable.

Parameters:

e: The jQuery.Event object. This parameter's type is Object.
args: The data with this event. This parameter's type is Object.

args.cell: An instance of the wijmo.grid.cellInfo class.The information about the cell to be edited.
args.event: This parameter is the event initiated cell editing.
args.handled: This parameter gets or sets a value that determines how cell editing is initiated: manually or automatically. The possible values are "true" or "false." The default value is "false," which means that the widget will handle editing automatically. If the cells contain custom controls or if you wish to provide custom editing on the front end, then the property must be set to "true."

Type: Function

Default: null

Code Example:

You can see the beforeCellEdit event in use in the Custom editors sample. In this sample, the beforeCellEdit event is set as in the following script:

function beforeCellEdit(e, args) {
            switch (args.cell.column().dataKey) {
                case "Position":
                    $("<input />")
                        .val(args.cell.value())
                        .appendTo(args.cell.container().empty())
                        .wijcombobox({
                            data: $.map($.extend(true, [], positions), function (item, index) {
                                if (item.value === args.cell.value()) {
                                    item.selected = true;
                                }
  
                                return item;
                            }),
                            isEditable: false
                        });
  
                    args.handled = true;
  
                    break;
  
                case "Acquired":
                    $("<input />")
                        .width("100%")
                        .appendTo(args.cell.container().empty())
                        .wijinputnumber({
                            decimalPlaces: 0,
                            showSpinner: true,
                            value: args.cell.value()
                        })
                        .focus();
  
                    args.handled = true;
  
                    break;
            }
        }

In the sample above, you can see that you're applying custom editing to two of the columns: the "Position" column and the "Acquired" column. For the Position column, you create a wijcombobox and map the position values to the wijcombobox. In the Acquired column, you create a wijinputnumber that will allow you to enter a date.

Note that for both columns, the args.handled property is set to "true", allowing custom editing.

Before the cell enters edit mode, it checks to see if the user-selected cell has the value "Available". If it doesn't, then an alert will appear and the "false" value will be returned to cancel the editing:

beforeCellEdit: function (e, args) {
      if (args.cell.column().headerText == “colName” && args.cell.value() != ‘Available’) {
                     alert(“Select any other cell”);
                     return false;
             }
       }

The beforeCellEdit event handler also allows you to disable editing based on the values present in a different grid column. In this example, you'll allow the user to change the price only if the product hasn't been discontinued:

function beforeCellEdit(e, args) {
return !((args.cell.column().dataKey === “Price”) && args.cell.row().data.Discontinued);
}.

This is the general form for supplying a callback function to handle the event:

$("#element").wijgrid({ beforeCellEdit: function (e, args) {
        //Handle the beforeCellEdit event here
     }
 });

You can bind to the event in two ways: by type or by name.

Binding to the event by type allows you to bind the event handler after the wijgrid is created:

$("#demo").bind("wijgridbeforecelledit", function (e, args) {  });

Binding by name allows you to bind to a named function. In this sample, onBeforeCellEdit is your custom function that will handle the event:

$("#demo").wijgrid({ beforeCellEdit: onBeforeCellEdit });

beforeCellUpdate

The beforeCellUpdate event handler is a function that is called before the cell is updated with new or user-entered data. There are many instances where this event is helpful, such as when you need to check a cell's value before the update occurs or when you need to apply an alert message based on the cell's value. This event is cancellable.

Parameters:

e: The jQuery.Event object. This parameter's type is Object.
args: The data with this event. This parameter's type is Object.

args.cell: An instance of the wijmo.grid.cellInfo class. This parameter gets the information of the edited cell.
args.value: This parameter returns the new cell value. If the property value is not changed, then the widget will try to extract the new cell value automatically. If you provide custom editing on the front end, then they new cell value must be returned in this property.

Type: Function

Default: null

Code Example:

You can see the beforeCellUpdate event in use in the Custom editors sample. In this sample, the beforeCellEdit event is set as in the following script:

       function beforeCellUpdate(e, args) { 
            switch (args.cell.column().dataKey) { 
                case "Position": 
                    args.value = args.cell.container().find("input").val(); 
                    break; 
  
                case "Acquired": 
                    var $editor = args.cell.container().find("input"), 
                        value = $editor.wijinputnumber("getValue"), 
                        curYear = new Date().getFullYear(); 
  
                    if (value < 1990 || value > curYear) { 
                        $editor.addClass("ui-state-error") 
  
                        alert("value must be between 1990 and " + curYear); 
  
                        $editor.focus(); 
  
                        return false; 
                    } 
                      
                    args.value = value; 
                    break; 
            } 
        }

In the above sample, you use args.value to check the year that the user enters in the "Acquired" column. If it's less than 1990 or greater than the current year, then the event handler will return false to cancel updating and show the user an alert message.

This is the general form for supplying a callback function to handle the beforeCellUpdate event:

$("#element").wijgrid({ beforeCellUpdate: function (e, args) { 
            //Handle the beforeCellUpdate event here
       } 
});

You can bind to the event in two ways: by type or by name.

Binding to the event by type allows you to bind the event handler after the wijgrid is created:

$("#element").bind("wijgridbeforecellupdate", function (e, args) { });

Binding by name allows you to bind to a named function. In this sample, onBeforeCellUpdate is your custom function that will handle the event:

$("#element").wijgrid({ beforeCellUpdate: onBeforeCellUpdate });

cellClicked

The cellClicked event handler is a function that is called when a cell is clicked. You can use this event to get the information of a clicked cell using the args parameter.

Parameters:

e: The jQuery.Event Object. The parameter's type is Object.
args: The data with this event. The parameter's type is Object.

args.cell: This is an instance of the wijmo.grid.cellInfo class that represents the clicked cell.

Type: Function

Default: Null

Code Example:

The sample below uses the cellClicked event to trigger an alert when the cell is clicked.

$("#element").wijgrid({ cellClicked: function (e, args) { 
            alert(args.cell.value()); 
        } 
   });

This is the general form for supplying a callback function to handle the cellClicked event:

$("#element").wijgrid({ 
        cellClicked: function (e, args) {      
             //Handle the event here. 
        } 
   });

You can bind to the event in two ways: by type or by name.

Binding to the event by type allows you to bind the event handler after the wijgrid is created:

$("#element").bind("wijgridcellclicked", function (e, args) { });

Binding by name allows you to bind to a named function. In this sample, onCellClicked is your custom function that will handle the event:

$("#element").wijgrid({ cellClicked: onCellClicked });

columnDragged

The columnDragged event handler is a function that is called when column dragging has been started. You can use this event to find the column being dragged or the dragged column's location.

Parameters:

e: The jQuery.Event object. This parameter's type is Object.
args: The data with this event. This parameter's type is Object.

args.drag: This is the column being dragged.
args.dragSource: This is the location of the column that has been dragged. The possible values are "groupArea" and "columns."

Type: Function

Default: null

Code Example:

This is the general form for supplying a callback function to handle the columnDragged event

$("#element").wijgrid({ columnDragged: function (e, args) {
        //Handle the columnDragged event here
     } 
});

You can bind to the event in two ways: by type or by name.

Binding to the event by type allows you to bind the event handler after the wijgrid is created:

$("#element").bind("wijgridcolumndragged", function (e, args) { });

Binding by name allows you to bind to a named function. In this sample, onColumnDragged is your custom function that will handle the event:

$("#element").wijgrid({ columnDragged: onColumnDragged });

columnDragging

The columnDragging event handler is a function that is called when column dragging has been started, but before the wijgrid handles the operation. This event is cancellable.

Parameters:

e: The jQuery.Event object. This parameter's type is Object.
args: The data with this event. This parameter's type is Object.

args.drag: This is the column being dragged.
args.dragSource: This is the location of the column that is being dragged. The possible values are "groupArea" or "columns."

Type: Function

Default: null

Code Examples:

This event is cancellable if you return false:

columnDragging: function(e, args) {
     return false;
}

In this sample you are preventing a user from dragging a specific column. You identify this column by its dataKey:

columnDragging: function(e, args) {
// Preventing the user from dragging the “ID” column.
         return !(args.drag.dataKey == “ID”);
}

This is the general form for supplying a callback function to handle the columnDragging event:

$("#element").wijgrid({ columnDragging: function (e, args) { 
       //Handle the columnDragging event here
      } 
});

You can bind to the event in two ways: by type or by name.

Binding to the event by type allows you to bind the event handler after the wijgrid is created:

$("#element").bind("wijgridcolumndragging", function (e, args) { });

Binding by name allows you to bind to a named function. In this sample, onColumnDragging is your custom function that will handle the event:

$("#element").wijgrid({ columnDragging: onColumnDragging });

columnDropped

The columnDropped event handler is a function that is called when a column has been dropped into the columns area.

Parameters:

e: The jQuery.Event object. This parameter's type is Object.
args: The data with this event. This parameter's type is Object.

args.drag: This is the column being dragged.
args.drop: This is the column on which the dragged column is dropped: the drop target.
args.at: This is the position at which the dragged column is dropped relative to the drop target. The possible values are "left", "right", or "center."

Type: Function

Default: null

Code Example:

This is the general form for supplying a callback function to handle the columnDropped event:

$("#element").wijgrid({ 
         columnDropped: function (e, args) {
             //Handle the columnDropped event handler here. 
       } 
  });

You can bind to the event in two ways: by type or by name.

Binding to the event by type allows you to bind the event handler after the wijgrid is created:

$("#element").bind("wijgridcolumndropped", function (e, args) { });

Binding by name allows you to bind to a named function. In this sample, onColumnDropped is your custom function that will handle the event:

$("#element").wijgrid({ columnDropped: onColumnDropped });

columnDropping

The columnDropping event handler is a function that is called when a column is dropped into the columns area, but before wijgrid handles the operation. This event is cancellable.

Parameters:

e: The jQuery.Event object. This parameter type is Object.
args: The data with this event. This parameter type is Object.

args.drag: This is the column being dragged.
args.drop: This is the column on which the drag source is dropped: the drop target.
args.at: The position at which the dragged column is dropped relative to the drop target. The possible values are "left", "right", or "center."

Type: Function

Default: null

Code Example:

This event is cancellable if you return false.

columnDropping: function (e, args) {
     return false;
}

In the following event code you're preventing users from dropping any column before the "ID" column. Note that you identify the "ID" column by its dataKey :

columnDropping: function (e, args) {
// Preventing user from dropping any column before the “ID” column.
     	    return !(args.drop.dataKey == “ID” && args.at == “left”);
}

This is the general form for supplying a callback function to handle the columnDropping event:

$("#element").wijgrid({ 
               columnDropping: function (e, args) { 
                   //Handle the columnDropping event here. 
          } 
    });

You can bind to the event in two ways: by type or by name.

Binding to the event by type allows you to bind the event handler after the wijgrid is created:

$("#element").bind("wijgridcolumndropping", function (e, args) { });

Binding by name allows you to bind to a named function. In this sample, onColumnDropping is your custom function that will handle the event:

$("#element").wijgrid({ columnDropping: onColumnDropping });

columnGrouped

The columnGrouped event handler is a function that is called when a column has been dropped into the group area. You can see the group area in the labeled image below:

Parameters:

e: The jQuery.Event object. This parameter's type is Object.
args: The data with this event. This parameter's type is Object.

args.drag: This is the column being dragged: the drag source.
args.drop: This parameter is the column on which the drag source is dropped: the drop target. args.drop is null if you are dropping the column into an empty group area.
args.dragSource: This parameter is the location of the dragged column. The possible values are "groupArea" and "columns."
args.dropSource: This parameter is the location of the dropped column. The possible values are "groupArea" and "columns."
args.at: The position at which you wish to drop a column relative to the drop target. The value is "left" if you're dropping the column into an empty group area.

Type: Function

Default: null

Code Example:

In this sample, you can see that the column that's been dropped is sorted in ascending order.

 columnGrouped: function (e, args) {
        sortBy($(this), args.drag.dataKey, ‘ascending’);
    }

This is the general form for supplying a callback function to handle the event:

$("#element").wijgrid({ 
       columnGrouped: function (e, args) { 
           //Handle the event here. 
      } 
});

You can bind to the event in two ways: by type or by name.

Binding to the event by type allows you to bind the event handler after the wijgrid is created:

$("#demo").bind("wijgridcolumngrouped", function (e, args) {  });

Binding by name allows you to bind to a named function. In this sample, onColumnGrouped is your custom function that will handle the event:

$("#demo").wijgrid({ columnGrouped: onColumnGrouped });

columnGrouping

The columnGrouping event handler is a function that is called when a column is dropped into the group area, but before the wijgrid handles the operation. This event is cancellable. You can see the group area in the labeled image below:

Parameters:

e: The jQuery.Event object. This parameter's type is Object.
args: The data with this event. This parameter's type is Object.

args.drag: This is the column being dragged: the drag source.
args.drop: This is the drop target, the place where the dragged column is dropped. This parameter is null if you are dropping a column into an empty group area.
args.dragSource: This is the location of the dragged column. The possible values are "groupArea" and "columns."
args.dropSource: This is the location of the dropped column. The possible values are "groupArea" and "columns."
args.at: The position at which you wish to drop a column relative to the drop target. The value is "left" if you're dropping the column into an empty group area.

Type: Function

Default: null

Code Examples:

You can see the columnGrouping event in the Group Area sample:

columnGrouping: function (e, args) {
                   if (args.dragSource !== "groupArea") {
                       $.each(demo2.wijgrid("columns"), function (i, w) {
                           if (w.options.dataKey == args.drag.dataKey) {
                               w.options.visible = false;
                           }
                       });

In the above sample, you can see that the script sets the columnGrouping event to hide the dragged column if the drag source is not "groupArea."

The columnGrouping event can also be used to disable grouping on a specific column. This is also an example of cancelling the event by returning false:

columnGrouping: function (e, args) {
                     if (args.drag.headerText == “UnitPrice”) {
                           return false;
    }

Note that in the sample above you are preventing the default behavior on the column with the headerText "UnitPrice."

This is the general form for supplying a callback function to handle the event:

columnGrouping: function (e, args) {
         //Handle the event here. 
    }

You can bind to the event in two ways: by type or by name.

Binding to the event by type allows you to bind the event handler after the wijgrid is created:

$("#demo").bind({ data: [[0, "a"], [1, "b"]] }).bind("wijgridcolumngrouping" function(e, args) { alert("!"); });

Binding by name allows you to bind to a named function. In this sample, onColumnGrouping is your custom function that will handle the event:

$("#demo").wijgrid({ columnGrouping: onColumnGrouping });

columnResized

The columnResized event handler is called when a user has changed a column's size.

Parameters:

e: The jQuery.Event object. The parameter's type is Object.
args: The data with this event. The parameter's type is Object.

args.column: The column that is being resized.

Type: Function

Default: null

Code Example:

This is the general form for supplying a callback function to handle the columnResized event:

$("#element").wijgrid({ columnResized: function (e) { 
             //Handle the columnResized event here. 
        } 
  });

You can bind to the event in two ways: by type or by name.

Binding to the event by type allows you to bind the event handler after the wijgrid is created:

$("#element").bind("wijgridcolumnresized", function (e) { });

Binding by name allows you to bind to a named function. In this sample, onColumnResized is your custom function that will handle the event:

$("#element").wijgrid({ columnResized: onColumnResized });

columnResizing

The columnResizing event handler is called when a user resizes the column but before the wijgrid handles the operation. This operation is cancellable.

Parameters:

e: The jQuery.Event object. The parameter's type is Object.
args: The data with this event. The parameter's type is Object.

args.column: The column that is being resized.
args.oldWidth: The width of the column before it is resized.
args.newWidth: The new width being set for the column.

Type: Function

Default: null

Code Example:

You can cancel this event by returning false:

columnResizing: function (e, args) {
         return false;
}

This sample shows that you can use the columnResizing event to prevent a user from setting a particular column's width to less than a specified number of pixels. You're using the args.column and args.newWidth parameters in this sample:

// prevent setting the width of “ID” column less than 100 pixels.
columnResizing: function(e, args) {
           if (args.column.dataKey == “ID” && args.newWidth < 100) {
                    args.newWidth = 100;
        }
}

This is the general form for supplying a callback function to handle the columnResizing event:

$("#element").wijgrid({ 
        columnResizing: function (e, args) { 
              //Handle the columnResizing event here. 
         } 
    });

You can bind to the event in two ways: by type or by name.

Binding to the event by type allows you to bind the event handler after the wijgrid is created:

$("#element").bind("wijgridcolumnresizing", function (e, args) { });

Binding by name allows you to bind to a named function. In this sample, onColumnResizing is your custom function that will handle the event:

$("#element").wijgrid({ columnResizing: onColumnResizing });

columnUngrouped

The columnUngrouped event handler is called when a column has been removed from the group area. You can see the group area in the labeled image below:

Parameters:

e: The jQuery.Event object. The parameter's type is Object.
args: The data with this event. The parameter's type is Object

args.column: This is the column that has been removed.

Type: Function

Default: null

Code Example:

This is the general form for supplying a callback function to handle the columnUngrouped event:

columnUngrouped: function (e, args) {
                    args.column.visible = true;
                },

You can bind to the event in two ways: by type or by name.

Binding to the event by type allows you to bind the event handler after the wijgrid is created:

$("#demo").bind("wijgridcolumnungrouped", function (e, args) { });

Binding by name allows you to bind to a named function. In this sample, onColumnGrouped is your custom function that will handle the event:

$("#demo").wijgrid({ columnUngrouped: onColumnUngrouped });

columnUngrouping

The columnUngrouping event handler is called when a column has been removed from the group area but before the wjgrid handles the operation. This event is cancellable. You can see the group area in the labeled image below:

Parameters:

e: The jQuery.Event object. The parameter's type is Object.
args: The data with this event. The parameter's type is Object.

args.column: The column being removed.

Type: Function

Default: null

Code Examples:

You can see the columnUngrouping event in the Group Area sample. Here's the script from the sample:

columnUngrouping: function (e, args) {
                    args.column.visible = true;
                },

In this sample the column you move from the grid to the group area is no longer visible in the grid. You can see in this event that when the column is removed from the group area, it becomes visible in the grid again.

You can also cancel this event by returning false:

columnUngrouping: function (e, args) {
        return false;
}

This is the general form for supplying a callback function to handle the event:

columnUngrouping: function (e, args) {
       //Handle the event here.
}

You can bind to the event in two ways: by type or by name.

Binding to the event by type allows you to bind the event handler after the wijgrid is created:

$("#demo").bind("wijgridcolumnungrouping", function (e, args) { });

Binding by name allows you to bind to a named function. In this sample, onColumnUngrouping is your custom function that will handle the event:

$("#demo").wijgrid({ columnUngrouping: onColumnUngrouping });

currentCellChanging

The currentCellChanging event handler is called before the cell is changed. You can use this event to get a selected row or column or to get a data row bound to the current cell. This event is cancellable.

Parameters:

e: The jQuery.Event object. The parameter's type is Object.
args: The data with this event. The parameter's type is Object.

args.cellIndex: The new cell index.
args.rowIndex: The new row index.
args.oldCellIndex: The old cell index.
args.oldRowIndex: The old row index.

Type: Function

Default: null

Code Example:

There are a couple of samples that give a good example of the currentCellChanging event in use. Both of these samples are examples of supplying a callback function to handle the event.

You can use the currentCellChanging event to get a selected row or column:

currentCellChanging: function (e, args) {
     var col = args.cellIndex;
     var row = args.rowIndex;
  }

This event will allow you to get a data row bound to the current cell:

currentCellChanging: function (e, args) {
   var rowObj = $(e.target).wijgrid(‘currentCell’).row();
   if (rowObj) {
      var dataItem = rowObj.data; // current data item (old position)
   }
}

Note that in above sample the jQuery event object's target is set to the row containing the current cell. When the function gets the data row bound to the current cell, it gets the old position since this event fires before the cell is changed.

This event is cancellable if you return false:

currentCellChanging: function (e, args) {
     return false;
}

This is the general form for supplying a callback function to handle the event:

$("#element").wijgrid({ 
         currentCellChanging: function (e, args) { 
               //Handle the currentCellChanging event here. 
          }  
    });

You can bind to the event in two ways: by type or by name.

Binding to the event by type allows you to bind the event handler after the wijgrid is created:

$("#demo").wijgrid("wijgridcurrentcellchanging", function (e, args) { 	});

Binding by name allows you to bind to a named function. In this sample, onCurrentCellChanging is your custom function that will handle the event:

$("#demo").wijgrid({ currentCellChanging: onCurrentCellChanging });

currentCellChanged

The currentCellChanged event handler is called after the current cell is changed. For example, this function allows you to get the selected row index.

Parameters:

e: The jQuery.Event object. This parameter's type is Object.

Type: Function

Default: null

Code Example:

You can use the currentCellChanged event to get a selected row index:

currentCellChanged: function (e, args) {
       var currentCell = $(e.target).wijgrid(‘currentCell’);
       var dataItemIndex = currentCell.row().dataItemIndex;
}

This is the general form for supplying a callback function to handle an event:

$("#element").wijgrid({ 
          currentCellChanged: function (e) { 
              //Handle the currentCellChanged event here. 
       } 
   });

You can bind to the event in two ways: by type or by name.

Binding to the event by type allows you to bind the event handler after the wijgrid is created:

$("#demo).bind("wijgridcurrentcellchanged" function(e, args) { });

Binding by name allows you to bind to a named function. In this sample, onCurrentCellChanged is your custom function that will handle the event:

$("#demo").wijgrid({ currentCellChanged: onCurrentCellChanged });

dataLoaded

The dataLoaded event handler is a function that is called when data is loaded.

Parameters:

e: The jQuery.Event object. The parameter's type is Object.

Type: Function

Default: null

Code Example:

In the following sample, you're supplying a function that will display the number of entries found:

dataLoaded: function() {
     alert($(this).wijgrid(“dataView”).count());
		}

This is the general form for supplying a callback function to handle the dataLoaded event:

$("#element").wijgrid({ 
          dataLoaded: function (e) { 
              //Handle the dataLoaded event here.  
        } 
    });

You can bind to the event in two ways: by type or by name.

Binding to the event by type allows you to bind the event handler after the wijgrid is created:

$("#element").bind("wijgriddataloaded", function (e) { });

Binding by name allows you to bind to a named function. In this sample, onDataLoaded is your custom function that will handle the event:

$("#demo").wijgrid({ dataLoaded: onDataLoaded });

dataLoading

The dataLoading event handler is a function that is called when the wijgrid loads a portion of data from the underlying datasource. This can be used for modification of data sent to server if using dynamic remote wijdatasource.

Parameters:

e: The jQuery.Event object. The parameter's type is Object.

Type: Function

Default: null

Code Example:

This sample allows you to get the session ID when loading a portion of data from the underlying datasource:

dataLoading: function (e) {
         var dataSource = $(this).wijgrid(“option”, “data”);
         dataSource.proxy.options.data.sessionID = getSessionID();
     }

This is the general form for supplying a callback function to handle the dataLoading event:

$("#element").wijgrid({ 
          dataLoading: function (e) { 
              //Handle the dataLoading event here. 
          } 
     });

You can bind to the event in two ways: by type or by name.

Binding to the event by type allows you to bind the event handler after the wijgrid is created:

$("#element").bind("wijgriddataloading", function (e) { });

Binding by name allows you to bind to a named function. In this sample, onDataLoading is your custom function that will handle the event:

$("#demo").wijgrid({ dataLoading: onDataLoading });

filterOperatorsListShowing

The filterOperatorsListShowing event handler is a function that is called before the filter drop-down list is shown. You can use this event to customize the list of filter operators for your users.

Parameters:

e: The jQuery.Event object. The parameter's type is Object.
args: The data with this event. The parameter's type is Object.

args.operator: An array of filter operators.
args.column: Associated column.

Type: Function

Default: null

Code Example:

If you want to customize your filter list, you can use script that resembles the following sample. In the sample, you limit the filters that will be shown to the "Equals" filter operator.:

filterOperatorsListShowing: function(e, args) {
   args.operators = $.grep(args.operators, function(op) {
      return op.name === ‘Equals’ || op.name === ‘NoFilter’;
   });
}

This is the general form for supplying a callback function to handle the event:

$("#element").wijgrid({ filterOperatorsListShowing: function (e, args) { } });

You can bind to the event in two ways: by type or by name.

Binding to the event by type allows you to bind the event handler after the wijgrid is created:

$("#demo").wijgrid("wijgridfilteroperatorslistshowing", function (e, args) {  });

Binding by name allows you to bind to a named function. In this sample, onFilterOperatorsListShowing is your custom function that will handle the event:

$("#demo").wijgrid({ filterOperatorsListShowing: onFilterOperatorsListShowing });

filtering

The filtering event handler is a function that is called before the filtering operation is started. For example, you can use this event to change a filtering condition before a filter will be applied to the data. This event is cancellable.

Parameters:

e: The jQuery.Event object. The parameter's type is Object.
args: The data with this event. The parameter's type is Object.

args.column: The column that is being filtered.
args.operator: The new filter operator name.
args.value: The new filter value.

Type: Function

Default: null

Code Example:

You can cancel this event if you return false:

filtering: function (e, args) {
    return false;
}

You can use this event to customize filtering operations. This sample prevents filtering by negative values:

filtering: function(e, args) {
        if (args.column.dataKey == “Price” && args.value < 0) {
              args.value = 0;
     }

This is the general form for supplying a callback function to handle the filtering event:

$(“#demo”).wijgrid({ 
            filtering: function(e, args) {
                 //Handle the filtering event here.
      }

You can bind to the event in two ways: by type or by name.

Binding to the event by type allows you to bind the event handler after the wijgrid is created:

$("#demo").wijgrid("wijgridfiltering", function (e, args) { });

Binding by name allows you to bind to a named function. In this sample, onFiltering is your custom function that will handle the event:

$("#demo").wijgrid({ filtering: onFiltering });

filtered

The filtered event handler is a function that is called after the wijgrid is filtered. This event is useful if you wish to get the filtered data.

Parameters:

e: The jQuery.Event object. This parameter's type is Object.
args: The data with this event. This parameter's type is Object.

args.column: column that is being filtered.

Type: Function

Default: null

Code Example:

The following sample triggers and alert that informs the user of the number of filtered rows in the grid:

filtered: function(e, args) {
	alert(“The filtered data contains: ” + $(this).wijgrid(“dataView”).count() + “ rows”);
   }

This is the general form for supplying a callback function to handle the filtered event:

$(“#demo”).wijgrid({ 
            filtered: function(e, args) {
               //Handle the filtered event here. 
     }

You can bind to the event in two ways: by type or by name.

Binding to the event by type allows you to bind the event handler after the wijgrid is created:

$("#demo").bind("wijgridfiltered", function (e, args) { });

Binding by name allows you to bind to a named function. In this sample, onFiltered is your custom function that will handle the event:

$("#demo").wijgrid({ filtered: onFiltered });

groupAggregate

The groupAggregate event handler is a function that is called when groups are being created and the column object's aggregate option has been set to "custom". This event is useful when you want to calculate custom aggregate values.

Parameters:

e: The jQuery.Event object. The parameter's type is Object.
args: The data with this event. The parameter's type is Object.

args.data: The data object.
args.column: The column that is being grouped.
args.groupByColumn: The column initiated grouping.
args.groupText: The text that is being grouped.
args.text: The text that will be displayed in the group header or group footer.
args.groupingStart: The first index for the data being grouped.
args.groupingEnd: The last index for the data being grouped.
args.isGroupHeader: args.isGroupHeader specifies whether or not the row you are grouping is a group header.

Type: Function

Default: null

Code Example:

This sample demonstrates using the groupAggregate event handler to calculate an average in a custom aggregate:

groupAggregate: function (e, args) {
     if (args.column.dataKey == "Price") {
	var aggregate = 0;

	for (var i = args.groupingStart; i <= args.groupingEnd; i++) {
		aggregate += args.data[i][args.column.dataIndex].value;
	}

	aggregate = aggregate/ (args.groupingEnd -	 args.groupingStart + 1);
	args.text = aggregate;
}

This is the general form for supplying a callback function to handle the groupAggregate event:

$("#element").wijgrid({ 
          groupAggregate: function (e, args) {
               //Handle the groupAggregate event handler here.
           } 
    });

You can bind to the event in two ways: by type or by name.

Binding to the event by type allows you to bind the event handler after the wijgrid is created:

$("#element").bind("wijgridgroupaggregate", function (e, args) { });

Binding by name allows you to bind to a named function. In this sample, onGroupAggregate is your custom function that will handle the event:

$("#demo").wijgrid({ groupAggregate: onGroupAggregate });

groupText

The groupText event handler is a function that is called when groups are being created and the groupInfo option has the groupInfo.headerText or the groupInfo.footerText options set to "custom". This event can be used to customize group headers and group footers.

Parameters:

e: The jQuery.Event object. The parameter's type is Object.
args: The data with this event. The parameter's type is Object.

args.data: The data object.
args.column: The column that is being grouped.
args.groupByColumn: The column initiated grouping.
args.groupText: The text that is being grouped.
args.text: The text that will be displayed in the group header or group footer.
args.groupingStart: The first index for the data being grouped.
args.groupingEnd: The last index for the data being grouped.
args.isGroupHeader: args.isGroupHeader specifies whether or not the row you are grouping is a group header.
args.aggregate: The aggregate value.

Type: Function

Default: null

Code Example:

The following sample sets the groupText event handler to avoid empty cells. The custom formatting applied to group headers left certain cells appearing as if they were empty. This script avoids that:

groupText: function (e, args) {
  if (!args.groupText) {
    args.text = “null”;
 }
}

This is the general form for supplying a callback function to handle the groupText event:

$("#element").wijgrid({ 
          groupText: function (e, args) { 
             //Handle the groupText event handler here. 
    } 
});

You can bind to the event in two ways: by type or by name.

Binding to the event by type allows you to bind the event handler after the wijgrid is created:

$("#demo").bind("wijgridgrouptext", function (e, args) { });

Binding by name allows you to bind to a named function. In this sample, onGroupText is your custom function that will handle the event:

$("#demo").wijgrid({ groupText: onGroupText });

invalidCellValue

The invalidCellValue event handler is a function called when a cell needs to start updating but the cell value is invalid. So if the value in a wijgrid cell can't be converted to the column target type, the invalidCellValue event will fire.

Parameters:

e: The jQuery.Event object. The parameter's type is Object.
args: The data with this event. The parameter's type is Object.

args.cell: An instance of the wijmo.grid.cellInfo class. This parameter gets the information of the edited cell.
args.value: The current value.

Type: Function

Default: null

Code Example:

The following sample adds a style to the cell if the value entered is invalid:

 
function onInvalidCellValue(e, args) {
            $(args.cell.container())
                 .addClass("ui-state-error");
        }

This is the general form for supplying a callback function to handle the invalidCellValue event:

 
$("#element").wijgrid({ 
         invalidCellValue: function (e, args) { 
               //Handle the invalidCellValue event here. 
      }
 });

You can bind to the event in two ways: by type or by name.

Binding to the event by type allows you to bind the event handler after the wijgrid is created:

$("#element").bind("wijgridinvalidcellvalue", function (e, args) { });

Binding by name allows you to bind to a named function. In this sample, onInvalidCellValue is your custom function that will handle the event:

$("#demo").wijgrid({ invalidCellValue: onInvalidCellValue });

loaded

The loaded event handler is a function that is called at the end the wijgrid's lifecycle when wijgrid is filled with data and rendered. You can use this event to manipulate the grid html content or to finish a custom load indication.

Parameters:

e: The jQuery.Event object. The parameter's type is Object.

Type: Function

Default: null

Code Example:

The loaded event in the sample below ensures that whatever is selected on load is cleared.

loaded: function (e) {
    $(e.target).wijgrid('selection').clear(); // clear selection                    
},

This is the general form for supplying a callback function to handle the event:

$("#element").wijgrid({
          loaded: function (e) { 
                //Handle the loaded event here. 
       } 
   });

You can bind to the event in two ways: by type or by name.

Binding to the event by type allows you to bind the event handler after the wijgrid is created:

$("#demo").bind("wijgridloaded", function (e, args) { });

Binding by name allows you to bind to a named function. In this sample, onLoaded is your custom function that will handle the event:

$("#demo").wijgrid({ loaded: onLoaded });

loading

The loading event handler is a function that is called at the beginning of the wijgrid's lifecycle. You can use this event to activate a custom load progress indicator.

Parameters:

e: The jQuery.Event object. The parameter's type is Object.

Type: Function

Default: null

Code Example:

You can see the loading event creating an indeterminate progressbar during loading in the sample below:

loading: function (e) {
         $(“#progressBar”).show().progressbar({ value: false });
     }

This is the general form for supplying a callback function to handle the event:

$("#element").wijgrid({ 
          loading: function (e) { 
             //Handle the loading event here. 
      } 
   });

You can bind to the event in two ways: by type or by name.

Binding to the event by type allows you to bind the event handler after the wijgrid is created:

$("#demo").bind("wijgridloading", function (e, args) { });

Binding by name allows you to bind to a named function. In this sample, onLoading is your custom function that will handle the event:

$("#demo").wijgrid({ loading: onLoading });

pageIndexChanging

The pageIndexChanging event handler is a function that is called before the page index is changed. This event is cancellable.

Parameters:

e: The jQuery.Event object. This parameter's type is Object.
args: The data with this event. This parameter's type is Object.

args.newPageIndex: new page index.

Type: Function

Default: null

Code Example:

You can use script that resembles the following to cancel the event by returning false:

pageIndexChanging: function (e, args) {
      return false;
}

This is the general form for supplying a callback function to handle the pageIndexChanging event:

$("#element").wijgrid({ 
          pageIndexChanging: function (e, args) { 
              //Handle the pageIndexChanging event here. 
     } 
});

You can bind to the event in two ways: by type or by name.

Binding to the event by type allows you to bind the event handler after the wijgrid is created:

$("#element").bind("wijgridpageindexchanging", function (e, args) { });

Binding by name allows you to bind to a named function. In this sample, onPageIndexChanging is your custom function that will handle the event:

$("#demo").wijgrid({ pageIndexChanging: onPageIndexChanging });

pageIndexChanged

The pageIndexChanged event handler is a function that is called after the page index is changed, such as when you use the numeric buttons to swtich between pages or assign a new value to the pageIndex option.

Parameters:

e: The jQuery.Event object. This paramter's type is Object.
args: The data with this event. This parameter's type is Object.

args.newPageIndex: The new page index

Type: Function

Default: null

Code Example:

The following sample handles the pageIndexChanged event and selects a specific row by index:

pageIndexChanged: function (e, args) {
      var pageIndex = $(t).wijgrid(“option”, “pageIndex”);
           if (pageIndex == 1) { //match the saved page index
               var selection = $(this).wijgrid(“selection”);
                selection.beginUpdate();
                selection.clear();
                selection.addRows(1); //add the saved row index
                selection.endUpdate();
                    }
          }

Note that in the sample above you called both the beginUpdate() and endUpdate() methods.

This is the general form for supplying a callback function to handle the pageIndexChanged event:

$("#element").wijgrid({ 
         pageIndexChanged: function (e) { 
             //Handle the pageIndexChanged event here. 
    } 
});

You can bind to the event in two ways: by type or by name.

Binding to the event by type allows you to bind the event handler after the wijgrid is created:

$("#demo").bind("wijgridpageindexchanged", function (e, args) { });

Binding by name allows you to bind to a named function. In this sample, onPageIndexChanged is your custom function that will handle the event:

$("#demo").wijgrid({ pageIndexChanged: onPageIndexChanged });

rendered

The rendered event handler is a function that is called when the wijgrid is rendered. Normally you do not need to use this event.

Parameters:

e: The jQuery.Event object. The parameter's type is Object.

Type: Function

Default: null

Code Example:

This is the general form for supplying a callback function to handle the rendered event:

$("#element").wijgrid({ 
        rendered: function (e, args) { 
             //Handle the rendered event here. 
      } 
});

You can bind to the event in two ways: by type or by name.

Binding to the event by type allows you to bind the event handler after the wijgrid is created:

$("#demo").bind("wijgridrendered", function (e, args) { });

Binding by name allows you to bind to a named function. In this sample, onRendered is your custom function that will handle the event:

$("#demo").wijgrid({ rendered: onRendered });

rendering

The rendering event handler is a function that is called when the wijgrid is about to render. Normally you do not need to use this event.

Parameters:

e: The jQuery.Event object. The parameter's type is object.

Type: Function

Default: null

Code Example:

This is a general form for supplying a callback function to handle the rendering event:

$("#element").wijgrid({ 
          rendering: function (e, args) { 
             //Handle the rendering event here. 
     } 
});

You can bind to the event in two ways: by type or by name.

Binding to the event by type allows you to bind the event handler after the wijgrid is created:

$("#element").bind("wijgridrendering", function (e) { });

Binding by name allows you to bind to a named function. In this sample, onRendering is your custom function that will handle the event:

$("#demo").wijgrid({ rendering: onRendering });

selectionChanged

The selectionChanged event handler is a function that is called after the selection is changed. wijgrid selection changes during rendering, so this is a useful event if you want to track the changes that occur when a column is shown or hidden, when the page size changes, or when the page loads.

Parameters:

e: The jQuery.Event object. The parameter's type is Object.
args: The data with this event. The parameter's type is Object.

args.addedCells: The cells that have been added to the selection.
args.removedCells: The cells that have been removed from the selection.

Type: Function

Default: null

Code Example:

The Selection sample uses the selectionChanged event. Here's the script from the sample:

function onSelectionChanged() {
                var sc = $("#demo").wijgrid("selection").selectedCells();
                var log = $("#demoLogTable");
  
                log.find("td").removeClass("ui-state-highlight").html("<span>&nbsp</span>");
  
                for (var i = 0, len = sc.length(); i < len; i++) {
                    var cellInfo = sc.item(i);
                    var logCell = $(log[0].tBodies[0].rows[cellInfo.rowIndex()].cells[cellInfo.cellIndex()]);
                    logCell.addClass("ui-state-highlight").text(cellInfo.value().toString());
                }
            }

You can see in the sample above that when an item in the grid is selected, it is highlighted and displayed in the selection log table next to the grid.

In the next sample, you handle the selectionChanged event and get the value of the first column of the selected row from the addedCells option. This sample is supplying a callback function to handle the event:

selectionChanged: function (e, args) {
     alert(args.addedCells.item(0).value()); 
}

You can bind to the event in two ways: by type or by name.

Binding to the event by type allows you to bind the event handler after the wijgrid is created:

$("#element").bind("wijgridselectionchanged", function (e, args) { });

Binding by name allows you to bind to a named function. In this sample, onSelectionChanged is your custom function that will handle the event:

$("#demo").wijgrid({ selectionChanged: onSelectionChanged });

sorting

The sorting event handler is a function that is called before the sorting operation is started. allowSorting must be set to "true" for this event to fire. This event is cancellable.

Parameters:

e: The jQuery.Event object. The parameter's type is Object.
args: The data with this event. The parameter's type is Object.

args.column: The column that is being sorted.
args.sortCommand: args.sortCommand combines args.column.dataKey and args.sortDirection in a shorthand notation to represent a sorting command: "<dataKey> <asc|desc>".
args.sortDirection: The new sort direction.

Type: Function

Default: null

Code Examples:

The following script sample handles the sorting function and will give you access to the column or source of the event and the sort direction:

sorting: function (e, args) {
          alert(“Column ” + args.column.headerText + ” sorted in ” + args.sortDirection + ” order”);
   }
});

The sample above is an example of supplying a callback function to handle the event.

You can also cancel the event by returning false:

          sorting: function (e) {  
                    return false; 
     }

You can bind to the event in two ways: by type or by name.

Binding to the event by type allows you to bind the event handler after the wijgrid is created:

$("#element").bind("wijgridsorting", function (e) { });

Binding by name allows you to bind to a named function. In this sample, onSorting is your custom function that will handle the event:

$("#demo").wijgrid({ sorting: onSorting });

sorted

The sorted event handler is a function that is called after the widget is sorted. allowSorting must be set to "true" to allow this event to fire.

Parameters:

e: The jQuery.Event object.

Type: Object

args: The data with this event.

Type: Object

args.column: The column that is being sorted.
args.sortDirection: The new sort direction.
args.sortCommand: args.sortCommand combines args.column.dataKey and args.sortDirection in a shorthand notation to represent a sorting command: "<dataKey> <asc|desc>".

Type: Object

Type: Function

Default: null

Code Example:

This sample, taken from the custom-paging-using-totalRows sample, updates the wijgrid with the data depending on the new sort:

sorted: function (e, args) {
  var gridInstance = $(e.target).data("wijmo-wijgrid");
  dataSource.sort(args.column.dataKey, args.column.sortDirection),
  gridInstance.options.update(gridInstance,  dataSource.getData(gridInstance.options.pageIndex));
	},

This is the general form for supplying a callback function to handle the sorted event:

$("#element").wijgrid({ 
          sorted: function (e) { 
             //Handle the sorted event here. 
      } 
});

You can bind to the event in two ways: by type or by name.

Binding to the event by type allows you to bind the event handler after the wijgrid is created:

$("#element").bind("wijgridsorted", function (e) { });

Binding by name allows you to bind to a named function. In this sample, onSorted is your custom function that will handle the event:

$("#demo").wijgrid({ sorted: onSorted });

Methods

The wijmo.wijgrid widget includes the following methods:

beginEdit

This method puts the current cell into edit mode, as long as the allowEditing option is set to "true." beginEdit returns true if the cell is successfully put into edit mode, otherwise it returns false.

Code Examples:

You can see the beginEdit method called in the following sample:

currentCellChanged: function (e, args) {
      if ($(e.target).wijgrid(“option”, “isLoaded”)) {
         window.setTimeout(function () {
            $(e.target).wijgrid(“beginEdit”);
         }, 100);
      }
   },

This particular line of code calls the beginEdit method:

$(e.target).wijgrid(“beginEdit”);

destroy

This method destroys the wijgrid widget and resets the DOM element.

Code Example:

$("#element").wijgrid("destroy");

doRefresh

doRefresh redraws or refreshes the wijgrid. This method doesn't load any updated data from a datasource, it only redraws the grid. This is useful if you've made some changes in the grid options and want the grid rendered with the new settings.

Code example:

$("#element").wijgrid("doRefresh");

columns

wijgrid columns are represented as widgets. This method returns a one-dimensional array of widgets that are bound to visible column headers.

The column widget is initiated with values taken from the corresponding item in the wijgrid.options.columns array. However, the options of a column widget instance reference not the original object but a copy created by the widget factory. Due to that, changes to the wijgrid.options.columns options are not automatically propagated to the column widget options and vice versa.

To solve this issue, the wijgrid synchronized the column widget option values with the source items. This synchronization occurs inside the ensureControl() method which is automatically called at each action requiring the wijgrid to enter.

Still, there is a drawback. For example, a user may want to filter wijgrid data from user code as in this sample:

$("#demo").wijgrid("option", "columns")[0].filterValue = "newValue";
$("#demo").wijgrid("ensureControl", true); // make wijgrid re-shape data and re-render.

In the sample above, nothing will happen since at synchronization user changes will be ignored.You need to change the filterValue of a column widget. This is what the columns() method is for:

$("#demo").wijgrid("columns")[0].options.filterValue = "newValue";
$("#demo").wijgrid("ensureControl", true); // make wijgrid re-shape data and re-render.

Here's the best way to change the filterValue:

$("#demo").wijgrid("columns")[0].option("filterValue", "newValue"); // column widget handles all the needful.

Code Example:

var colWidgets = $("#element").wijgrid("columns");

currentCell

This method gets or sets the current cell for the grid. If you wish to hide the current cell, use (-1, -1) for the value.

Parameters:

cellInfo - The Object that represents a single cell. The parameter's type is wijmo.grid.cellInfo
cellIndex - The zero-based index of the required cell inside the corresponding row. The parameter's type is Number.
rowIndex - The zero-based index of the row that contains required cell. The parameter's type is Number.

Returns: The currentCell method returns type wijmo.grid.cellInfo. This represents the grid's current cell.

Code example:

You can use currentCell as a Getter:

var current = $("#element).wijgrid("currentCell");

or you can use the currentCell method as a Setter. Here's one way:

 $("#element).wijgrid("currentCell", new wijmo.grid.cellInfo(0, 0));

and here's a second way:

$("#element).wijgrid("currentCell", 0, 0);

If you're using currentCell as a setter and you wish to hide the current cell, use code that resembles the following:

$("#element).wijgrid("currentCell", -1, -1);

data

This method gets an array of the underlying data.

Code Example:

This is the general form for calling the data method:

var data = $("#element").wijgrid("data");

For example, you can update the underlying data with the following code:

$(“#demo”).wijgrid({
data: [
{ ID: 0, Name: “Name0” },
{ ID: 1, Name: “Name1” },
]
});

var data = $(“element”).wijgrid(“data”);

// add two new lines
data.push({ ID: 2, Name: “Name2” });
data.push({ ID: 3, Name: “Name3” });

// make the wijgrid re-render itself
$(“element”).wijgrid(“ensureControl”, true);

endEdit

The endEdit method finishes editing the current cell.

Code Examples:

In the first example you can see that endEdit is being called from within the saveChanges event:

function saveChanges() {
            $("#demogrid").wijgrid("endEdit");
        };

This sample shows the method being called.

$("#element").wijgrid("endEdit");

ensureControl

The ensureControl method moves the column widget options to the wijgrid options and renders the wijgrid. Use this method when you need to re-render the wijgrid and reload remote data from the datasource.

Parameters:

loadData - This parameter determines if the wijgrid must load data from a linked data source before rendering. The parameter type is Boolean.

Code Example:

$("#element").wijgrid("ensureControl", true);

You can see this method being called from a click event in the following sample:

 function btnAdd_click() {
            var len = viewModel.data().length;
            viewModel.data.push(new Person({ ID: "11" + len, Company: "New Company" + len, Name: "New Name" + len }));
            $("#dataGrid").wijgrid("ensureControl", true);
        }

getCellInfo

This event gets an instance of the wijmo.grid.cellInfo class that represents the grid's specified cell.

Parameters:

domCell: An HTML DOM Table cell object. The parameter's type is object.

Returns: This event returns an object that represents a cell of the grid. The return type is wijmo.grid.cellInfo.

Code Example:

var cellInfo = $("#element").wijgrid("getCellInfo", domCell);

getFilterOperatorsByDataType

This method returns a one-dimensional array of filter operators which are applicable to the specified data type.

Parameters:

dataType – This parameter specifies the type of data to which you apply the filter operators. The possible values are: "string", "number", "datetime", "currency", and "boolean". This parameter's type is String.

Code Example:

var operators = $("#element").wijgrid("getFilterOperatorsByDataType", "string");

pageCount

The pageCount method gets the number of pages.

Code Example:

var pageCount = $("#element").wijgrid("pageCount");

selection

The selection method gets an object that manages selection in the grid.

Remarks: See the "wijmo.grid.selection" section below for more details.

Code Example:

var selection = $("#element").wijgrid("selection");

If you want to select rows using this method, you can use the row index to add the row to the selection object:

var selection = $(“#demo”).wijgrid(“selection”);
selection .addRows(2);

setSize

The setSize method sets the size of the grid using the width and height parameters. Width should be the first parameter you set.

Parameters:

width - Determines the width of the grid.
height - Determines the height of the grid.

Code Example:

$("#element").wijgrid("setSize", 200, 200);

Internal Widgets

wijmo.grid.cellInfo class

constructor

The wijmo.grid.cellInfo function creates an object that represents a single cell.

Parameters:

cellIndex: The zero-based index of the required cell inside the corresponding row.
rowIndex: The zero-based index of the row that contains the required cell.

Return: Returns an object that represents a single cell.

Return type: wijmo.grid.cellInfo

Code Example:

var cell = new wijmo.grid.cellInfo(0, 0);

wijmo.grid.cellInfo Methods

The wijmo.grid.cellinfo object includes the following methods:

cellIndex

Gets the zero-based index of the cell in the row which it corresponds to.

Returning Type: Number

Code Example:

var index = cellInfoObj.cellIndex();

column

The column method gets the associated column object.

Return Type: Object

Code example:

var column = cellInfoObj.column();

container

The container method returns the jQuery object containing a cell content.

Return Type: jQuery

Code example:

var $container = cellInfoObj.container();

isEqual

The isEqual method compares the current object with an object you have specified and indicates whether they are identical. This method returns true if the objects are identical, otherwise it will return false.

Parameters include:

cellInfo: The object to compare.

Return Type: Boolean

Code Example:

var isEqual = cellInfoObj1.isEqual(cellInfoObj2);

row

The row method gets the associated row's information.

Remarks: Returns information about associated row.

Return Type: object

The return value has the following properties:

$rows: The jQuery object that represents the associated rows.
data: The associated data.
dataRowIndex: The data row index.
dataItemIndex: The data item index.
virtualDataItemIndex: The virtual data item index.
type: The type of the row. This property is one of the $.wijmo.wijgrid.rowType values.

Code Example:

var row = cellInfoObj.row();

rowIndex

The rowIndex method gets the zero-based index of the row containing the cell.

Return Type: Number

Code Example:

var index = cellInfoObj.rowIndex();

tableCell

The tableCell method returns the table cell element corresponding to this object.

Returning Type: DOM object

Code Example:

var domCell = cellInfoObj.tableCell();

value

The value method gets and sets the cell data.

Remarks: An "invalid value" exception will be thrown by the setter if the value does not correspond to the associated column.

Parameter:

value: The value to set. The parameter's type is Object.

Return Type: Object

Code Example:

var value = cellInfoObj.value();
cellInfoObj.value("value");

wijmo.grid.cellInfoOrderedCollection class

constructor

The wijmo.grid.cellInfoOrderedCollection function creates an ordered read-only collection of wijmo.grid.cellInfo objects. You do not need to create instances of this class.

Parameter:

gridview: The grid

Return Type: wijmo.grid.cellInfoOrderedCollection

Code Example:

var collection = new wijmo.grid.cellInfoOrderedCollection(gridView);

cellInfoOrderedCollection Methods

The wijmo.wijgrid.cellInfoOrderedCollection object includes the following methods:

indexOf

The indexOf method returns the zero-based index of specified collection item.

Usage:

indexOf(cellInfo) (note: The search is done by value, not by reference).
indexOf(cellIndex, rowIndex)

Parameters:

cellInfo: The cellInfo object whose index will be returned.
cellIndex: The zero-based cellIndex component of the cellInfo object. This parameter returns the component's index.
rowIndex: The zero-based rowIndex component of the cellInfo object. This parameter returns the component's index.

Returns: indexOf returns the zero-based index of the specified object, or -1 if the specified object is not a member of the collection.

Return Type: Number

Code Example:

var index = collection.indexOf(0, 0);

item

The item method gets an item at the specified index. This method returns the wijmo.grid.cellInfo object at the specified index.

Parameter:

index: The zero-based index of the item to get.

Return Type: wijmo.grid.cellInfo

Code Example:

var cellInfoObj = collection.item(0);

length

The length method gets the total number of the items in the collection.

Returning Type: Number

Code Example:

var len = collection.length();

cellInfoRange Options

The wijmo.wijgrid.cellInfoRange object includes the following options:

cellInfoRange

Creates an object that specifies a range of cells determined by two cells.

Remarks: Parameters include:

topLeft: Object that represents the top left cell of the range.
bottomRight: Object that represents the bottom right cell of the range.

Returning Type: wijmo.wijgrid.cellInfoRange

Code Example:

var range = $.wijmo.wijgrid.cellInfoRange(new $.wijmo.wijgrid.cellInfo(0, 0), new $.wijmo.wijgrid.cellInfo(0, 0));

bottomRight

Gets the object that represents the bottom right cell of the range.

Returning Type: $.wijmo.wijgrid.cellInfo

Code Example:

var cellInfoObj = range.bottomRight();

isEqual

Compares the current range with a specified range and indicates whether they are identical.

Remarks:

Parameters include:

range: Range to compare.

Returns true if the ranges are identical, otherwise false.

Returning Type: Boolean.

Code Example:

var isEqual = range1.isEqual(range2);

topLeft

Gets the object that represents the top left cell of the range.

Returning Type: $.wijmo.wijgrid.cellInfo

Code Example:

var cellInfoObj = range.topLeft();

wijmo.grid.selection class

constructor

The wijmo.grid.selection function creates an object that represents selection in the grid. You do not need to create instances of this class.

Parameter:

gridview: The grid

Returns: Returns an object that represents selection in the grid.

Returning Type: wijmo.grid.selection

Code Example:

var selection = new wijmo.grid.selection(gridView);

selection Methods

The wijmo.grid.selection object includes the following methods:

addColumns

addColumns adds a column range to the current selection.

Usage:

addColumns(0)
addColumns(0, 2)

The result depends upon the chosen selection mode in the grid. For example, if the current mode doesn't allow multiple selection then the previous selection will be removed.

Parameters include:

start: The index of the first column to select.
end: The index of the last column to select. This parameter is optional.

Return Type: void

Code Example:

selectionObj.addColumns(0);

addRange

addRange adds a cell range to the current selection.

Usage:

addRange(cellRange)
addRange(x0, y0, x1, y1)

The result depends on the chosen selection mode in the grid. For example, if the current selection mode doesn't allow multiple selection then the previous selection will be removed.

Parameters:

cellRange: The cell range to select.
x0: The x-coordinate that represents the top left cell of the range.
y0: The y-coordinate that represents the top left cell of the range.
x1: The x-coordinate that represents the bottom right cell of the range.
y1: The y-coordinate that represents the bottom right cell of the range.

Return Type: void

Code Example:

selectionObj.addRange(0, 0, 1, 1);

addRows

addRows adds a row range to the current selection.

Usage:

addRows(0)
addRows(0, 2)

The result depends upon the chosen selection mode in the grid. For example, if the current selection mode doesn't allow multiple selection then the previous selection will be removed.

Parameters:

start: The index of the first row to select.
end: The index of the last row to select. This is an optional parameter.

Return Type: void

Code Example:

selectionObj.addRows(0);

beginUpdate

This method begins the update. Any changes won't take effect until endUpdate() is called.

Return Type: void

Code Example:

selectionObj.beginUpdate();

clear

This method clears the selection.

Return Type: void

Code Example:

selectionObj.clear();

endUpdate

When endUpdate is called, the pending changes are executed and the corresponding events are raised.

Return Type: void

Code Example:

selectionObj.endUpdate();

removeColumns

removeColumns removes a range of columns from the current selection.

Usage:

removeColumns(0)
removeColumns(0, 2)

The result depends upon the chosen selection mode in the grid.

Parameters:

start: The index of the first column to remove.
end: The index of the last column to remove. This is an optional parameter.

Return Type: void

Code Example:

selectionObj.removeColumns(0);

removeRange

This method removes a range of cells from the current selection.

Usage:

removeRange(cellRange)
removeRange(x0, y0, x1, y1)

The result depends upon the chosen selection mode in the grid.

Parameters include:

cellRange: Cell range to select.
x0: The x-coordinate that represents the top left cell of the range.
y0: The y-coordinate that represents the top left cell of the range.
x1: The x-coordinate that represents the bottom right cell of the range.
y1: The y-coordinate that represents the bottom right cell of the range.

Return Type: void

Code Example:

selectionObj.removeRange(0, 0, 1, 1);

removeRows

The removeRows method removes a range of rows from the current selection.

Usage:

removeRows(0)
removeRows(0, 2)

The result depends upon the chosen selection mode in the grid.

Parameters include:

start: The index of the first row to remove.
end: The index of the last row to remove. This parameter is optional.

Return Type: void

Code Example:

selectionObj.removeRows(0);

selectAll

This method selects all the cells in a grid, depending on the selection mode chosen in the grid. If the selection mode is set to "singleCell", then only the top left cell will be selected.

Returning Type: void

Code Example:

selectionObj.selectAll();

selectedCells

Gets a read-only collection of the selected cells.

Remarks: Returns cellInfoOrderedCollection.

Returning Type: wijmo.wijgrid.cellInfoOrderedCollection

Code Example:

In the following example taken from the wijgrid Selection sample, every time the selection in a grid is changed, the markup gets the current selection, clears all cells in the selection log table, and adds the selection to the selection log table.

functiononSelectionChanged() { 
    varsc = $("#demo").wijgrid("selection").selectedCells(); 
    varlog = $("#demoLogTable"); 
    
     log.find("td").removeClass("ui-state-highlight").html("<span>&nbsp</span>"); 

     for(vari = 0, len = sc.length(); i < len; i++) { 
        varcellInfo= sc.item(i); 
        varlogCell = $(log[0].tBodies[0].rows[cellInfo.rowIndex()].cells[cellInfo.cellIndex()]); 
        logCell.addClass("ui-state-highlight").text(cellInfo.value().toString()); 
      } 
}

c1basefield Options

The wijmo.c1basefield widget includes the following options:

allowMoving

A value indicating whether the column can be moved.

Type: Boolean

Default: true

Code Example:

$("#element").wijgrid({ columns: [ { allowMoving: true } ] });

allowSizing

A value indicating whether the column can be sized.

Type: Boolean

Default: true

Code Example:

$("#element").wijgrid({ columns: [ { allowSizing: true } ] });

cellFormatter

Function used for changing the content, style, and attributes of column cells.

Remarks: Important: cellFormatter should not alter the content of the header and filter row cells container. Parameters include:

afterDefaultCallback: callback function which is invoked after applying default formatting.
column: options of the formatted column.
$container: jQuery object that represents cell container to format.
dataRow: associated data. The dataRow parameter is type Object.
formattedValue: formatted value of the cell.
row: information about associated row.
row.$rows: jQuery object that represents rows to format.
row.data: associated data.
row.dataRowIndex: data row index.
row.dataItemIndex: data item index.
row.type: type of the row, one of the $.wijmo.wijgrid.rowType values.
row.virtualDataItemIndex: virtual data item index.

Returns true if container content has been changed and wijgrid should not apply the default formatting to the cell.

Type: Function

Default: undefined

Code Example:

cellFormatter: function (args) {
                    if (args.column.dataType == 'number') {
                        args.formattedValue = args.formattedValue + "h";
                    }
                }

The sample above shows the cellFormatter function used to check the dataType and assign a postfix letter "h" to the cell value if it is a number.

The complete sample is below:

$(“#gridview”).wijgrid({
                allowSorting:true,
                columns: [{ headerText: "Id", dataType: "string" },
                { headerText: "Quantity", dataType: "number", dataFormatString: "d", cellFormatter: function (args) {
                    if (args.column.dataType == 'number') {
                        args.formattedValue = args.formattedValue + "h";
                    }
                }
                },
                { headerText: "Name", dataType: "string"}]
});

dataKey

A value indicating the key of the data field associated with a column. If an array of hashes is used as a datasource for wijgrid, this should be string value, otherwise this should be an integer determining an index of the field in the datasource.

Type: String or Number

Default: undefined

Code Example:

$("#element").wijgrid({ columns: [ { dataKey: "ProductID" } ] });

ensurePxWidth

Determines whether to use number type column width as the real width of the column.

Type: Boolean

Default: undefined

Code Example:

$("#element").wijgrid({ columns: [ { ensurePxWidth: true } ] });

footerText

Gets or sets the footer text. The text may include a placeholder: "{0}" is replaced with the aggregate.

Remarks: If the value is undefined the footer text will be determined automatically depending on the type of the datasource:

DOM table - text in the header cell.

Type: String

Default: undefined

Code Example:

Code example: $("#element").wijgrid({ columns: [ { footerText: "footer" } ] });

headerText

Gets or sets the header text.

Remarks: If the value is undefined the header text will be determined automatically depending on the type of the datasource:

DOM table - text in the header cell.
Array of hashes - dataKey (name of the field associated with column).
Two-dimensional array - dataKey (index of the field associated with column).

Type: String

Default: undefined (the existing column header will be used).

Code Example:

$("#element").wijgrid({ columns: [ { headerText: "column0" } ] });

visible

A value indicating whether the column is visible.

Type: Boolean

Default: true

Code Example:

$("#element").wijgrid({ columns: [ { visible: true } ] });

width

Determines the width of the column.

Type: Number or String

Default: undefined

Remarks:

The option could either be a number or string.
Use number to specify width in pixel. Use string to specify width in percentage.
By default, wijgrid emulates the table element behavior when using number as width. This means wijgrid may not have the exact width specified.
If exact width is needed, please set ensureColumnsPxWidth option of wijgrid to true.

Code Example:

$("#element").wijgrid({ columns: [ { width: 150 } ] });

OR

$("#element").wijgrid({ columns: [ { width: "10%" } ]});

c1field Options

The wijmo.c1field : wijmo.c1basefield widget provides the base widget for columns in the wijgrid. This widget includes the following options:

aggregate

Causes the grid to calculate aggregate values on the column and place them in the column footer cell or group header and footer rows.

Remarks: If the showFooter option is disabled or grid does not contain any groups, setting the "aggregate" option has no effect. Possible values are: "none", "count", "sum", "average", "min", "max", "std", "stdPop", "var", "varPop" and "custom".

Possible values:

"none": no aggregate is calculated or displayed.
"count": count of non-empty values.
"sum": sum of numerical values.
"average": average of the numerical values.
"min": minimum value (numerical, string, or date).
"max": maximum value (numerical, string, or date).
"std": standard deviation (using formula for Sample, n-1).
"stdPop": standard deviation (using formula for Population, n).
"var": variance (using formula for Sample, n-1).
"varPop": variance (using formula for Population, n).
"custom": custom value (causing grid to throw "groupaggregate" event).

Type: String

Default: "none"

Code Example:

$("#element").wijgrid({ columns: [{ aggregate: "none" }] });

allowSort

A value indicating whether column can be sorted.

Type: Boolean

Default: true

Code Example:

$("#element").wijgrid({ columns: [{ allowSort: true }] });

dataType

Column data type. Used to determine the rules for sorting, grouping, aggregate calculation, and so on.

Remarks: Possible values are: "string", "number", "datetime", "currency", and "boolean".

"string": if using built-in parser any values are acceptable; " " considered as an empty string, nullString as null.
"number": if using built-in parser only numeric values are acceptable, also " ", "" and nullString which are considered as null. Any other value throws an exception.
"datetime": if using built-in parser only date-time values are acceptable, also " ", "" and nullString which are considered as null. Any other value throws an exception.
"currency": if using built-in parser only numeric and currency values are acceptable, also " ", "" and nullString which are considered as null. Any other value throws an exception.
"boolean": if using built-in parser only "true" and "false" (case-insensitive) values are acceptable, also " ", "" and nullString which are considered as null. Any other value throws an exception.

Type: String

Default: "string"

Code Example:

$("#element").wijgrid({ columns: [{ dataType: "string" }] });

dataParser

Data converter that is able to translate values from a string representation to column data type and back.

Remarks:

The dataParser is an object which must contains the following methods:

parseDOM(value, culture, format, nullString): converts given DOM element into the typed value.
parse(value, culture, format, nullString): converts the value into typed value.
toStr(value, culture, format, nullString): converts the value into its string representation.

Type: Object

Default: undefined (widget built-in parser for supported datatypes will be used).

Code Example:

var myBoolParser = {
  parseDOM: function (value, culture, format, nullString) {
    return this.parse(value.innerHTML, culture, format, nullString);
  },
  parse: function (value, culture, format, nullString) {
    if (typeof (value) === "boolean") return value;
    if (!value || (value === " ") || (value === nullString)) {
      return null;
    }
    switch (value.toLowerCase()) {
      case "on": return true;
      case "off": return false;
    }
    return NaN;
  },
  toStr: function (value, culture, format, nullString) {
    if (value === null) return nullString;
    return (value) ? "on" : "off";
  }
}
$("#element").wijgrid({ columns: [ { dataType: "boolean", dataParser: myBoolParser } ] });

dataFormatString

A pattern used for formatting and parsing column values.

Type: String

Default: undefined

Remarks: The default value is undefined ("n" pattern will be used for "number" dataType, "d" for "datetime", "c" for "currency").

The following condensed explanations were taken from https://github.com/jquery/globalize. Please see this link and jquery.glob.js for a full explanation and additional values.

Number:

The four main types of number formatting are:

n - number
d - decimal digits
p - percentage
c – currency

Each of these format tokens may be followed by a number, which determines how many decimal places to display except in the case of a decimal, where it means the minimum number of digits to display. The way negative numbers are represented in each culture can vary.

Here are some dataFormatString values and the rendered results for a sample value "123.45". Note that format will vary by culture.

dataFormatString value	Result
"n"	123.45
"n0"	123
"d"	123
"d3"	012
"c"	$123.45
"c0"	$123
"p0"	12%
"p4"	12.3450%

DateTime:

DateTime formatting varies by culture. Here is a list of possible formats:

Format	Meaning	"en-US"
f	Long Date, Short Time	dddd, MMMM dd, yyyy h:mm tt
F	Long Date, Long Time	dddd, MMMM dd, yyyy h:mm:ss tt
t	Short Time	h:mm tt
T	Long Time	h:mm:ss tt
d	Short Date	M/d/yyyy
D	Long Date	dddd, MMMM dd, yyyy
Y	Month/Year	MMMM, yyyy
M	Month/Day	MMMM dd

In addition to these standard formats, there is the "S" format. This is a sortable format that is identical in every culture: "yyyy'-'MM'-'dd'T'HH':'mm':'ss". See https://github.com/jquery/globalize for additional custom formatting strings.

Here are some examples:

dataFormatString value	Result
'd'	2/20/2013
'D'	Monday, February 20, 2013

Currency:

Globalize has a default currency symbol for each locale. This is used when formatting a currency value such as:

dataFormatString value	Result
"c"	$1,234.56

Sample: See the Data types sample.

Code Example:

$(document).ready(function () { 
  $("#demo").wijgrid( { 
     allowSorting: true, 
     columns: [ 
        { dataType: "currency" }, 
        { dataType: "number" }, 
        { dataType: "number", dataFormatString: "p0" }, 
        ] 
    }); 
});

In this example, the UnitPrice column is formatted as currency, the Quantity column is a number, and the Discount column is a percentage with zero decimal places shown.

filterOperator

An operations set for filtering. Must be either one of the embedded operators or custom filter operator. Operator names are case insensitive.

Remarks: Embedded filter operators include:

"NoFilter": no filter.
"Contains": applicable to "string" data type.
"NotContain": applicable to "string" data type.
"BeginsWith": applicable to "string" data type.
"EndsWith": applicable to "string" data type.
"Equals": applicable to "string", "number", "datetime", "currency" and "boolean" data types.
"NotEqual": applicable to "string", "number", "datetime", "currency" and "boolean" data types.
"Greater": applicable to "string", "number", "datetime", "currency" and "boolean" data types.
"Less": applicable to "string", "number", "datetime", "currency" and "boolean" data types.
"GreaterOrEqual": applicable to "string", "number", "datetime", "currency" and "boolean" data types.
"LessOrEqual": applicable to "string", "number", "datetime", "currency" and "boolean" data types.
"IsEmpty": applicable to "string".
"NotIsEmpty": applicable to "string".
"IsNull": applicable to "string", "number", "datetime", "currency" and "boolean" data types.
"NotIsNull": applicable to "string", "number", "datetime", "currency" and "boolean" data types.

Full option value is:

[filterOperartor1, ..., filterOperatorN]

where each filter item is an object of the following kind:

{ name: <operatorName>, condition: "or"|"and" }

where:

name: filter operator name.
condition: logical condition to other operators, "or" is by default.

Example:

filterOperator: [ { name: "Equals" }, { name: "NotEqual", condition: "and" } ]

It is possible to use shorthand notation, the following statements are equivalent:

filterOperator: [ { name: "Equals" }, { name: "BeginsWith" } ]
filterOperator: [ "Equals", "BeginsWith" ]

In the case of a single operator option name may contain only filter operator name, the following statements are equivalent:

filterOperator: [ { name: "Equals" } ]
filterOperator: [ "Equals" ]
filterOperator: "Equals"

Note: wijgrid built-in filter editors do not support multiple filter operators.

Type: String

Default: "nofilter"

Code Example:

$("#element").wijgrid({ columns: [ { filterOperator: "nofilter" } ] });

filterValue

A value set for filtering. Full option value is:

[filterValue1, ..., filterValueN]

where each item is a filter value for the corresponding filter operator.

Example:

filterValue: [0, "a", "b"]

Built-in filter operators support array of values as an argument.

Example:

filterOperator: ["Equals", "BeginsWith"]
filterValue: [[0, 1, 2], "a"]

As a result of filtering all the records having 0, 1, 2, or starting with "a" will be fetched.

Shorthand notation allows omitting square brackets, the following statements are equivalent:

filterValue: ["a"]
filterValue: [["a"]]
filterValue: "a"

Note: wijgrid built-in filter editors do not support multiple filter values.

Type: depends on column data type.

Default: undefined

Code Example:

$("#element").wijgrid({ columns: [ { filterValue: "abc" } ] });

groupInfo

Using to customize the appearance and position of groups. See the "GroupInfo object" section below for more details.

Type: Object

Default:

{
    groupSingleRow: true,
    collapsedImageClass: "ui-icon-triangle-1-e",
    expandedImageClass: "ui-icon-triangle-1-se",
    position: "none",
    outlineMode: "startExpanded",
    headerText: undefined,
    footerText: undefined
}

Code Example:

$("#element").wijgrid({ columns: [{ groupInfo: { position: "header" }}] });

readOnly

A value indicating whether the cells in the column can be edited.

Type: Boolean

Default: false

Code Example:

$("#element").wijgrid({ columns: [ { readOnly: false } ] });

rowMerge

Determines whether rows are merged.

Remarks: Possible values are: "none", "free", and "restricted".

"none": no row merging.
"free": allows row with identical text to merge.
"restricted": keeps rows with identical text from merging if rows in the previous column are merged.

Type: String

Default: "none"

Code Example:

$("#element").wijgrid({ columns: [{ rowMerge: "none" }] });

sortDirection

Determines the sort direction.

Remarks: Possible values are: "none", "ascending", "descending".

"none": no sorting.
"ascending": sort from smallest to largest.
"descending": sort from largest to smallest.

Type: String

Default: "none"

Code Example:

$("#element").wijgrid({ columns: [{ sortDirection: "none" }] });

showFilter

A value indicating whether filter editor will be shown in the filter row.

Type: Boolean

Default: true

Code Example:

$("#element").wijgrid({ columns: [ { showFilter: true } ] });

valueRequired

A value indicating whether null value is allowed during editing.

Type: Boolean

Default: false

Code Example:

$("#element").wijgrid({ columns: [ { valueRequired: false } ] });

c1band Options

The wijmo.c1band : wijmo.c1boundfield widget provides band settings for columns in the datagrid. This widget includes the following option:

columns

Gets an array of objects representing the the band columns. The default value is an empty array.

Type: Array

Default: empty Array

$("element").wijgrid({
         columns: [
                {
                    headerText: "Band" ,
                    columns: [
                           { headerText: "ID" },
                           { headerText: "Name" }
                        ]
                 }
           ]
});

GroupInfo Options

The GroupInfo object is used to customize the appearance and position of groups. This class includes the following options:

groupSingleRow

A value indicating whether groupings containing a single row are grouped.

Type: Boolean

Code Example:

$("#element").wijgrid({ columns: [{ groupInfo: { groupSingleRow: true }}] });

collapsedImageClass

Determines the CSS used to show collapsed nodes on the grid.

Type: String

Code Example:

$("#element").wijgrid({ columns: [{ groupInfo: { collapsedImageClass: "myClass" }}] });

expandedImageClass

Determines the CSS used to show expanded nodes on the grid.

Type: String

Code Example:

$("#element").wijgrid({ columns: [{ groupInfo: { expandedImageClass: "myClass" }}] });

position

Determines whether the grid should insert group header and/or group footer rows for this column.

Remarks: Possible values include:

"none": disables grouping for the column.
"header": inserts header rows.
"footer": inserts footer rows.
"headerAndFooter": inserts header and footer rows.

Type: String

Code Example:

$("#element").wijgrid({ columns: [{ groupInfo: { position: "header" }}] });

outlineMode

Determines whether the user will be able to collapse and expand the groups by clicking on the group headers, and also determines whether groups will be initially collapsed or expanded.

Remarks: Possible values include:

"none": disables collapsing and expanding.
"startCollapsed": groups are initially collapsed.
"startExpanded": groups are initially expanded.

Type: String

Code Example:

$("#element").wijgrid({ columns: [{ groupInfo: { outlineMode: "startExpanded" }}] });

headerText

Determines the text that is displayed in the group header rows.

Remarks: The text may include up to three placeholders:

"{0}" is replaced with the value being grouped on.
"{1}" is replaced with the group's column header.
"{2}" is replaced with the aggregate.

Type: String

Code Example:

$("#element").wijgrid({ columns: [{ groupInfo: { headerText: "{1}: {0}" }}] });

footerText

Determines the text that is displayed in the group footer rows.

Remarks: The text may include up to three placeholders:

"{0}" is replaced with the value being grouped on.
"{1}" is replaced with the group's column header.
"{2}" is replaced with the aggregate.

Type: String

Code Example:

$("#element").wijgrid({ columns: [{ groupInfo: { footerText: "{1}: {0}" }}] });

Grid

Contents

User Guide

Overview

Markup and Scripting

Quick Start

Concepts

Adaptive for Mobile Use

Binding Wijgrid with Knockout

Loading Data Dynamically

Loading Remote Data

Updating Data in a Wijgrid

API

Enumerations

renderState

rowType

Options

allowColMoving

allowColSizing

allowEditing

allowKeyboardNavigation

allowPaging

allowSorting

allowVirtualScrolling

alwaysParseData

cellStyleFormatter

columns

columnsAutogenerationMode

culture

customFilterOperators

data

ensureColumnsPxWidth

filterOperatorsSortMode

groupAreaCaption

groupIndent

highlightCurrentCell

loadingText

nullString

pageIndex

pageSize

pagerSettings

readAttributesFromData

rowStyleFormatter

scrollMode

selectionMode

showFilter

showFooter

showGroupArea

showRowHeader

showSelectionOnRender

staticColumnIndex

staticRowIndex

totalRows

Events

afterCellEdit

afterCellUpdate

ajaxError

beforeCellEdit

beforeCellUpdate

cellClicked

columnDragged

columnDragging

columnDropped

columnDropping

columnGrouped

columnGrouping

columnResized

columnResizing

columnUngrouped

columnUngrouping

currentCellChanging

currentCellChanged

dataLoaded

dataLoading

filterOperatorsListShowing

filtering

filtered

groupAggregate

groupText

invalidCellValue