TIWCGJQGridOptions Properties

If True, automatically adjusts the Height of the Grid to accomodate the height all the rows + headers and footers

This option allow to set global ajax settings for the grid when we request data. Note that with this option is possible to overwrite all current ajax setting in the grid including the error, complete and beforeSend events.

This option allow to set global ajax settings for the select element when the select is obtained via dataUrl option in editoptions or searchoptions objects

The class that is used for alternate rows. You can construct your own class and replace this value. This option is valid only if altRows options is set to true

Set a zebra-striped grid

When set to true encodes (html encode) the incoming (from server) and posted data (from editing modules). By example < will be converted to &lt;

If true, automatically calculates rownum

When set to true, the grid width is recalculated automatically to the width of the parent element. This is done only initially when the grid is created. In order to resize the grid when the parent element changes width you should apply custom code and use a setGridWidth method for this purpose

Defines the Caption layer for the grid. This caption appears above the Header layer. If the string is empty the caption does not appear.

Enables (disables) cell editing. When this option is set to true, onSelectRow event can not be used, and hovering is disabled (when mouseover on the rows). See Cell Editing for more details.

This option determines the padding + border width of the cell. Usually this should not be changed, but if custom changes to td element are made in the grid css file this will need to be changed. The initial value of 5 means paddingLef?2+paddingRight?2+borderLeft?1=5

Determines where the contents of the cell are saved: 'remote' or 'clientArray'. See Cell Editing for more details

the url where the cell is to be saved. See Cell Editing for more details

Collection which describes the parameters of the columns.This is the most important part of the grid. For a full description of all valid values see colModel API.

An array in which we place the names of the columns. This is the text that appears in the head of the grid (Header layer). The names are separated with commas. Note that the number of element in this array should be equal of the number elements in the colModel array.

Show or Hide the column headers

The string of data when datatype parameter is set to xmlstring or jsonstring

Defines what type of information to expect to represent data in the grid. Valid options are xml - we expect xml data; xmlstring - we expect xml data as string; json - we expect JSON data; jsonstring - we expect JSON data as string; local - we expect data defined at client side (array data); javascript - we expect javascript as data; function - custom defined function for retrieving data. See colModel API and Retrieving Data

This option should be set to true if a event or a plugin is attached to the table cell. The option uses jQuery empty for the the row and all its children elements. This have of course speed overhead, but prevent memory leaks

Applicable only when we use datatype : local. Deselects currently-selected row(s) when a sort is applied.

Determines the language direction in grid. The default is “ltr” (Left To Right language). When set to “rtl” (Right To Left) the grid automatically do the needed. It is important to note that in one page we can have two (or more) grids where the one can have direction “ltr” while the other can have direction “rtl”. This option work only in FireFox 3.x versions and Internet Explorer versions >=6. Currently Safai and Google Chrome does not support fully direction “rtl”. Also the same apply to Opera browsers. The most common problem in FireFox is that the default settings of the browser does not support RTL. In order change this see HOW TO section in this chapter .

Defines the url for inline and form editing.

Display the information when the returned (or the current) number of records is zero. This option is valid only if viewrecords option is set to true.

when true, the treeGrid is expanded and/or collapsed when we click on the text of the expanded column, not only on the image

indicates which column (name from colModel) should be used to expand the tree grid. If not set the first one is used. Valid only when treeGrid option is set to true.

Represents property ExportUrl.

If set to true this will place a footer table with one row below the gird records and above the pager. The number of columns equal of these from colModel

If set to true, and resizing the width of a column, the adjacent column (to the right) will resize so that the overall grid width is maintained (e.g., reducing the width of column 2 by 30px will increase the size of column 3 by 30px). In this case there is no horizontal scrolbar. Note: this option is not compatible with shrinkToFit option - i.e if shrinkToFit is set to false, forceFit is ignored.

Represents property Grid.

Determines the current state of the grid (i.e. when used with hiddengrid, hidegrid and caption options). Can have either of two states: 'visible' or 'hidden'

In the previous versions of jqGrid including 3.4.X,reading a relatively big data sets (Rows >=100 ) caused speed problems. The reason for this was that as every cell was inserted into the grid we applied about 5-6 jQuery calls to it. Now this problem is resolved; we now insert the entry row at once with a jQuery append. The result is impressive - about 3-5 times faster. What will be the result if we insert all the data at once? Yes, this can be done with a help of gridview option when set to true. The result is a grid that is 5 to 10 times faster. Of course when this option is set to true we have some limitations. If set to true we can not use treeGrid, subGrid, or afterInsertRow event. If you do not use these three options in the grid you can set this option to true and enjoy the speed.

Enables grouping in grid. Please refer grouping page.

The groupingView option is actually a object and consist a lot of other options

If the option is set to true the title attribute is added to the column headers

The height of the grid. Can be set as number (in this case we mean pixels) or as percentage (only 100% is acceped) or value of auto is acceptable.

If set to true the grid initially is hidden. The data is not loaded (no request is sent) and only the caption layer is shown. When the show/hide button is clicked the first time to show grid, the request is sent to the server, the data is loaded, and grid is shown. From this point we have a regular grid. This option has effect only if the caption property is not empty and the hidegrid property (see below) is set to true.

Enables or disables the show/hide grid button, which appears on the right side of the Caption layer. Takes effect only if the caption property is not an empty string.

When set to false the mouse hovering is disabled in the grid data rows.

When set this string is added as prefix to the id of the row when it is build

By default the local searching is case sensitive. To make the local search and sorting not case sensitive set this options to true

Represents property InlineEditing.

structure of the expected json data. For a full description and default setting, see Retrieving Data JSON Data

Readonly property. Determines the total number of pages returned from the request. Used by Provider to set last page.

If this flag is set to true, the grid loads the data from the server only once (using the appropriate datatype). After the first request the datatype parameter is automatically changed to local and all further manipulations are done on the client side. The functions of the pager (if present) are disabled.

The text which appear when requesting and sorting data. This parameter is located in language file

his option controls what to do when an ajax operation is in progress. disable - disables the jqGrid progress indicator. This way you can use your own indicator. enable (default) - enables “Loading” message in the center of the grid. block - enables the “Loading” message and blocks all actions in the grid until the ajax request is finished. Note that this disables paging, sorting and all actions on toolbar, if any.

Region or country

Defines the type of request to make (“POST” or “GET”)

This option works only when multiselect = true. When multiselect is set to true, clicking anywhere on a row selects that row; when multiboxonly is also set to true, the multiselection is done only when the checkbox is clicked (Yahoo style). Clicking in any other row (suppose the checkbox is not clicked) deselects all rows and the current row is selected.

This parameter have sense only multiselect option is set to true. Defines the key which will be pressed when we make multiselection. The possible values are: shiftKey - the user should press Shift Key altKey - the user should press Alt Key ctrlKey - the user should press Ctrl Key

If this flag is set to true a multi selection of rows is enabled. A new column at left side is added. Can be used with any datatype option.

Determines the width of the multiselect column if multiselect is set to true.

If set to true enables the multisorting. The options work if the datatype is local. In case when the data is obtained from the server the sidx parameter contain the order clause. It is a comma separated string in format field1 asc, field2 desc …, fieldN. Note that the last field does not not have asc or desc. It should be obtained from sord parameter When the option is true the behavior is a s follow. The first click of the header field sort the field depending on the firstsortoption parameter in colModel or sortorder grid parameter. The next click sort it in reverse order. The third click removes the sorting from this field.

Called when the height of the grid is adjusted

applies only to a cell that is editable; this event fires after the edited cell is edited - i.e. after the element is inserted into the DOM

This event fires after every inserted row. rowid is the id of the inserted row rowdata is an array of the data to be inserted into the row. This is array of type name: value, where the name is a name from colModel rowelem is the element from the response. If the data is xml this is the xml element of the row; if the data is json this is array containing all the data for the row Note: this event does not fire if gridview option is set to true

applies only to a cell that is editable; this event fires after calling the method restoreCell or the user press ESC leaving the changes

applies only to a cell that is editable; this event fires after the cell has been successfully saved. This is the ideal place to change other content.

applies only to a cell that is editable; this event Fires after the cell and other data is posted to the server Should return array of type [success(boolean),message] when return [true,””] all is ok and the cellcontent is saved [false,”Error message”] then a dialog appears with the “Error message” and the cell content is not saved. servereresponse is the response from the server. To use this we should use serverresponse.responseText to obtain the text message from the server.

applies only to a cell that is editable; this event fires before editing the cell.

This event fire before proccesing the data from the server. Note that the data is formatted depended on the value of the datatype parameter - i.e if the datatype is 'json' for example the data is JavaScript object

This event fire before requesting any data. Also does not fire if datatype is function. If the event return false the request is not made to the server

applies only to a cell that is editable; this event fires before calling the method restoreCell or the user press ESC leaving the changes

applies only to a cell that is editable; this event fires before validation of values if any. This event can return the new value which value can replace the edited one beforeSaveCell : function(rowid,celname,value,iRow,iCol) { if( some_condition ) { return “new value”; } } The value will be replaced with “new value”

This event fire when the user click on the row, but before select them. rowid is the id of the row. e is the event object This event should return boolean true or false. If the event return true the selection is done. If the event return false the row is not selected and any other action if defined does not occur.

applies only to a cell that is editable; this event fires before submit the cell content to the server (valid only if cellsubmit : 'remote'). Can return new array that will be posted to the server. beforeSubmitCell : function(rowid,celname,value,iRow,iCol) { if( some_condition ) { return {name1:value1,name2:value2} } else { return {} } } The returned array will be added to the cellurl posted data.

Called before collpase of the tree node

Called before expand of the tree node

Fires when we click on particular cell in the grid. rowid is the id of the row iCol is the index of the cell, cellcontent is the content of the cell, e is the event object element where we click. (Note that this available when we not use cell editing module and is disabled when using cell editing).

Trigger when RowNum dropdown change.

Raised immediately after row was double clicked. rowid is the id of the row, iRow is the index of the row (do not mix this with the rowid), iCol is the index of the cell. e is the event object

fires if there is a server error; servereresponse is the response from the server. To use this we should apply serverresponse.responseText to obtain the text message from the server. status is the status of the error. If not set a modal dialog apper.

applies only to a cell that is editable; this event allows formatting the cell content before editing, and returns the formatted value

This fires after all the data is loaded into the grid and all other processes are complete. Also the event fires independent from the datatype parameter and after sorting paging and etc.

Triggered when the user clicks on a group.

Fire after clicking to hide or show grid (hidegrid:true); gridstate is the state of the grid - can have two values - visible or hidden

Called only once before populating the data

If this event is assigned, it's called by the grid, when user cancels an insert

If this event is assigned, it's called by the grid, when user hit Down on Last Row, or Insert Key

A pre-callback to modify the XMLHttpRequest object (xhr) before it is sent. Use this to set custom headers etc. Returning false will cancel the request.

This event is executed immediately after every server request. data Data from the response depending on datatype grid parameter

A function to be called if the request fails. The function gets passed three arguments: The XMLHttpRequest object (xhr), a string describing the type of error (status) that occurred and an optional exception object (error), if one occurred.

This event fires after click on [page button] and before populating the data. Also works when the user enters a new page number in the page input box (and presses [Enter]) and when the number of requested records is changed via the select box. To this event we pass only one parameter pgButton See pager. If this event return 'stop' the processing is stopped and you can define your own custom paging

Event which is called when we start resize a column. event is the event object, index is the index of the column in colModel.

Event which is called after the column is resized. newwidth is the is the new width of the column , index is the index of the column in colModel.

Raised immediately after row was right clicked. rowid is the id of the row, iRow is the index of the row (do not mix this with the rowid), iCol is the index of the cell. e is the event object. Note - this event does not work in Opera browsers, since Opera does not support oncontextmenu event

This event fires when multiselect option is true and you click on the header checkbox. aRowids array of the selected rows (rowid's). status - boolean variable determining the status of the header check box - true if checked, false if not checked. Note that the aRowids alway contain the ids when header checkbox is checked or unchecked.

applies only to cells that are not editable; fires after the cell is selected

Raised immediately after row was clicked. rowid is the id of the row, status is the status of the selection. Can be used when multiselect is set to true. true if the row is selected, false if the row is deselected. This event is not triggered when CellEdit = True

If set this event can serialize the data passed to the ajax request when we save a cell. The function should return the serialized data. This event can be used when a custom data should be passed to the server - e.g - JSON string, XML string and etc. To this event is passed the data which will be posted to the server

If set this event can serialize the data passed to the ajax request. The function should return the serialized data. This event can be used when a custom data should be passed to the server - e.g - JSON string, XML string and etc. To this event we pass the postData array.

Raised immediately after sortable column was clicked and before sorting the data. index is the index name from colModel, iCol is the index of column, sortorder is the new sorting order - can be 'asc' or 'desc'. If this event return 'stop' the sort processing is stopped and you can define your own custom sorting

The event is raised just before expanding the grid. When set, this event should return true or false. If it returns false the subgrid row is not expanded and the subgrid is not opened.

This event is raised when the user clicks on the minus icon. The event should return true or false; when the returned value is false the row can not be collapsed.

This event is called when the expand button is clicked, if SubGrid = True We pass two parameters: arguments are: subgrid_id is a id of the div tag created within a table the row_id is the id of the row If we want to pass additional parameters to the url we can use the method getRowData(row_id) - which returns associative array in type name-value

Set the initial number of page when we make the request.This parameter is passed to the url for use by the server routine retrieving the data

Defines that we want to use a pager bar to navigate through the records. This must be a valid html element; in our example we gave the div the id of “pager”, but any name is acceptable. Note that the Navigation layer (the “pager” div) can be positioned anywhere you want, determined by your html; in our example we specified that the pager will appear after the Table Body layer. The valid calls can be (using our example) 'pager', '#pager', jQuery('#pager'). I recommend to use the second one. See Pager

Determines the position of the pager in the grid. By default the pager element when created is divided in 3 parts (one part for pager, one part for navigator buttons and one part for record information)

If False the Pager will be invisible

Determines if the Pager buttons should be shown if pager is available. Also valid only if pager is set correctly. The buttons are placed in the pager bar.

Determines if the input box, where the user can change the number of requested page, should be available. The input box appear in the pager bar.

Show information about current page status. The first value is the current loaded page. The second value is the total number of pages

Determines the position of the record information in the pager. Can be left, center, right

Readonly property. Determines the number of returned records in grid from the request

Represent information that can be shown in the pager. Also this option is valid if viewrecords option is set to true. This text appear only if the tottal number of recreds is greater then zero.In order to show or hide some information the items in {} mean the following: {0} the start position of the records depending on page number and number of requested records; {1} - the end position {2} - total records returned from the data

Assigns a class to columns that are resizable so that we can show a resize handle only for ones that are resizable

Allow to change the row html attributes (style, classes or tabindex).

Property return a object something like this {"style" : "somestyle", "class": "someclass"}

Important Note
Very useful to change the row appearance through style or by adding the css class.

Allow change the row html attributes (style, classes or tabindex), just like RowAttr, but with possibility to check the cell value.

The grid passes the following parameters to javascript function:

An array to construct a select box element in the pager in which we can change the number of the visible rows. When changed during the execution, this parameter replaces the rowNum parameter that is passed to the url. If the array is empty the element does not appear in the pager. Typical you can set this like [10,20,30]. If the rowNum parameter is set to 30 then the selected value in the select box is 30.

Sets how many records we want to view in the grid. This parameter is passed to the url for use by the server routine retrieving the data. Note that if you set this parameter to 10 (i.e. retrieve 10 records) and your server return 15 then only 10 records will be loaded

If this option is set to true, a new column at left of the grid is added. The purpose of this column is to count the number of available rows, beginning from 1. In this case colModel is extended automatically with new element with name - 'rn'. Also, be careful not to use the name 'rn' in colModel

Determines the width of the row number column if rownumbers option is set to true.

When set this parameter can instruct the server to load the total number of rows needed to work on. Note that rowNum determines the total records displayed in the grid, while rowTotal the total rows on which we operate. When this parameter is set we send a additional parameter to server named totalrows. You can check for this parameter and if it is available you can replace the rows parameter with this one. Mostly this parameter can be combined wit loadonce parameter set to true.

Creates dynamic scrolling grids. When enabled, the pager elements are disabled and we can use the vertical scrollbar to load data. When set to true the grid will always hold all the items from the start through to the latest point ever visited. When scroll is set to value (eg 1), the grid will just hold the visible lines. This allow us to load the data at portions whitout to care about the memory leaks. Additionally this we have optional extension to the server protocol: npage (see prmNames array). If you set the npage option in prmNames, then the grid will sometimes request more than one page at a time, if not it will just perform multiple gets.

Determines the width of the vertical scrollbar. Since different browsers interpret this width differently (and it is difficult to calculate it in all browsers) this can be changed.

When enabled, selecting a row with setSelection scrolls the grid so that the selected row is visible. This is especially useful when we have a verticall scrolling grid and we use form editing with navigation buttons (next or previous row). On navigating to a hidden row, the grid scrolls so the selected row becomes visible.

This control the timeout handler when scroll is set to 1.

If True, always select top row on every Grid Load

This option is read only. Contain the id of the last selected row. If you sort or apply a pagging this options is set to null

If Multiselect, contains the array of selected ids

This option describes the type of calculation of the initial width of each column against with the width of the grid. If the value is true and the value in width option is set then: Every column width is scaled according to the defined option width. Example: if we define two columns with a width of 80 and 120 pixels, but want the grid to have a 300 pixels - then the columns are recalculated as follow: 1- column = 300(new width)/200(sum of all width)*80(column width) = 120 and 2 column = 300/200*120 = 180. The grid width is 300px. If the value is false and the value in width option is set then: The width of the grid is the width set in option. The column width are not recalculated and have the values defined in colModel. If integer is set, the width is calculated according to it

When enabled this option allow column reordering with mouse. Since this option uses jQuery UI sortable widget, be a sure that this widget and the related to widget files are loaded in head tag. Also be a sure too that you mark the grid.jqueryui.js when you download the jqGrid.

The initial sorting name when we use datatypes xml or json (data returned from server). This parameter is added to the url. If set and the index (name) match the name from colModel then to this column by default is added a image sorting icon, according to the parameter sortorder (below). See prmNames.

The initial sorting order when we use datatypes xml or json (data returned from server).This parameter is added to the url - see prnNames. Two possible values - asc or desc.

If set to true this enables using a subgrid. If the subGrid is enabled a additional column at left side is added to the basic grid. This column contains a 'plus' image which indicate that the user can click on it to expand the row. By default all rows are collapsed. See Subgrid

This property, which describes the model of the subgrid, has an effect only if the subGrid property is set to true. It is an array in which we describe the column model for the subgrid data. For more info see Subgrid.

A set of additional options for the subgrid. For more information and default values see Subgrid.

This option has effect only if subGrid option is set to true. This option points to the file from which we get the data for the subgrid. jqGrid adds the id of the row to this url as parameter. If there is a need to pass additional parameters, use the params option in subGridModel. See Subgrid

subGridWidth integer Determines the width of the subGrid column if subgrid is enabled.

When enabled this option place a pager element at top of the grid below the caption (if available). If another pager is defined both can coexists and are refreshed in sync. The id of the new created pager is a combination of the gridid+“_toppager”.

Determines the initial datatype (see datatype option). Usually this should not be changed. During the reading process this option is equal to the datatype option.

Enables (disables) the tree grid format. For more details see Tree Grid

Deteremines the method used for the treeGrid. Can be nested or adjacency. See Tree Grid

This array set the icons used in the tree.

tree_root_level numeric Determines the level where the root element begins when treeGrid is enabled

The url of the file that holds the request

This list contain custom information from the request. Can be used at any time

When set to true we directly place the user data array userData at footer. The rules are as follow: If the userData array contain name which is equal to those of colModel then the value is placed in that column.If there are no such values nothing is palced. Note that if this option is used we use the current formatter options (if available) for that column

If true, jqGrid displays the beginning and ending record number in the grid, out of the total number of records in the query. This information is shown in the pager bar (bottom right by default)in this format: “View X to Y out of Z”. If this value is true, there are other parameters that can be adjusted, including 'emptyrecords' and 'recordtext'.

The purpose of this parameter is to define different look and behavior of sorting icons that appear near the header. This parameter is array with the following default options viewsortcols : [false,'vertical',true]. The first parameter determines if all icons should be viewed at the same time when all columns have sort property set to true. The default of false determines that only the icons of the current sorting column should be viewed. Setting this parameter to true causes all icons in all sortable columns to be viewed. The second parameter determines how icons should be placed - vertical means that the sorting icons are one under another. 'horizontal' means that the icons should be one near other. The third parameter determines the click functionality. If set to true the columns are sorted if the header is clicked. If set to false the columns are sorted only when the icons are clicked. Important note: When set a third parameter to false be a sure that the first parameter is set to true, otherwise you will loose the sorting.

If this option is not set, the width of the grid is a sum of the widths of the columns defined in the colModel (in pixels). If this option is set, the initial width of each column is set according to the value of shrinkToFit option

structure of the expected xml data. For a full description refer to Retrieving Data XML Data.