This is an old revision of the document!
Table of Contents
~~ODT~~
Events
The action to take on an event is set as a property of the grid, e.g.
See also jqGrid Methods
var lastSel; jQuery("#gridid").jqGrid({ ... onSelectRow: function(id){ if(id && id!==lastSel){ jQuery('#gridid').restoreRow(lastSel); lastSel=id; } jQuery('#gridid').editRow(id, true); }, ... });
The above example specifies the action to take when a row is selected. The events that you can use to perform some additional action are listed here, in alphabetic order:
As of version 3.6.3 to every event is passed the reference (this) to the grid. This means that inside every event you can use $(this) which refers to the grid. Using the above example both are equivalent
var lastSel; jQuery("#gridid").jqGrid({ ... onSelectRow: function(id){ if(id && id!==lastSel){ jQuery(this).restoreRow(lastSel); lastSel=id; } jQuery(this).editRow(id, true); }, ... });
List of Events
| Event | Parameters | Description |
|---|---|---|
| afterInsertRow | rowid rowdata rowelem | 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 |
| beforeProcessing | data, status, xhr | 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 |
| beforeRequest | none | 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 |
| beforeSelectRow | rowid, e | 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. |
| gridComplete | none | 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. |
| loadBeforeSend | xhr, settings | 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. |
| loadComplete | data | This event is executed immediately after every server request. data Data from the response depending on datatype grid parameter |
| loadError | xhr, status, error | 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. |
| onCellSelect | rowid, iCol, cellcontent, e | 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). |
| ondblClickRow | rowid, iRow, iCol, e | 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 |
| onHeaderClick | gridstate | Fire after clicking to hide or show grid (hidegrid:true); gridstate is the state of the grid - can have two values - visible or hidden |
| onPaging | pgButton | 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 |
| onRightClickRow | rowid, iRow, iCol, e | 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 |
| onSelectAll | aRowids, status | 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. |
| onSelectRow | rowid, status, e | Raised immediately after row was clicked. rowid is the id of the row, status is the status of the selection, e is the event object. Can be used when multiselect is set to true. true if the row is selected, false if the row is deselected. |
| onSortCol | index, iCol, sortorder | 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 |
| rowattr | rowData, currentObj, rowId | rowData is array with the cell data. currObj is the current row represented in the source like json or xml. rowId is the id of the row. This event is called when the new table row is inserted. It can be used to set additional style and class attributes of the row dynamically. The event should return a object something like this {“style” : “somestyle”, “class”: “someclass”}. Note that you can set any attribute to the row. It is important to note that the event does fire only when a new row is inserted - this mean that it can not be used with methods which updated the row like setRowData. |
| resizeStart | event, index | Event which is called when we start resize a column. event is the event object, index is the index of the column in colModel. |
| resizeStop | newwidth, index | 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. |
| serializeGridData | postData | 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. |
Additional Events specific to Cell Editing, subGrid are found in their respective topics.
List of triggered events (new in v4.3.2)
| Event | Parameters | Return value | Description |
|---|---|---|---|
| jqGridResizeStart | … | none | … |
| jqGridResizeStop | … | none | … |
| jqGridRowAttr | … | … | … |
| jqGridAfterInsertRow | … | none | … |
| jqGridGridComplete | none | none | … |
| jqGridAfterGridComplete | none | none | … |
| jqGridBeforeRequest | none | … | … |
| jqGridLoadComplete | … | none | … |
| jqGridAfterLoadComplete | … | none | … |
| jqGridSortCol | … | … | … |
| jqGridSelectAll | … | none | … |
| jqGridBeforeSelectRow | … | … | … |
| jqGridCellSelect | … | none | … |
| jqGridDblClickRow | … | … | … |
| jqGridRightClickRow | … | … | … |
| jqGridHeaderClick | … | none | … |
| jqGridSelectRow | … | none | … |
| jqGridShowHideCol | … | none | … |
| jqGridRemapColumns | … | none | … |
| jqGridKeyLeft | … | none | … |
| jqGridKeyRight | … | none | … |
| jqGridKeyEnter | … | none | … |
| jqGridKeySpace | … | none | … |
| jqGridToolbarBeforeSearch | none | … | … |
| reloadGrid | … | none | … |
| jqGridToolbarAfterSearch | none | none | … |
| jqGridToolbarBeforeClear | none | … | … |
| jqGridToolbarAfterClear | none | none | … |
| jqGridFilterBeforeShow | … | … | … |
| jqGridFilterAfterShow | … | none | … |
| jqGridFilterInitialize | … | none | … |
| jqGridFilterSearch | none | … | … |
| jqGridFilterReset | none | … | … |
| jqGridAddEditBeforeCheckValues | … | … | … |
| jqGridAddEditClickSubmit | … | … | … |
| jqGridAddEditBeforeSubmit | … | … | … |
| jqGridAddEditErrorTextFormat | … | … | … |
| jqGridAddEditAfterSubmit | … | … | … |
| jqGridAddEditAfterComplete | … | none | … |
| jqGridAddEditBeforeInitData | form, oper | … | This event is fired before the dataInit function. form is the form as a jQuery object oper is the operation type, either “add” or “edit” |
| jqGridAddEditBeforeShowForm | … | none | … |
| jqGridAddEditAfterShowForm | … | none | … |
| jqGridAddEditInitializeForm | … | none | … |
| jqGridAddEditClickPgButtons | … | none | … |
| jqGridAddEditAfterClickPgButtons | … | none | … |
| jqGridInlineEditRow | … | none | … |
| jqGridInlineAfterSaveRow | … | none | … |
| jqGridInlineSuccessSaveRow | … | … | … |
| jqGridInlineErrorSaveRow | … | none | … |
| jqGridInlineAfterRestoreRow | … | none | … |
| jqGridBeforeEditCell | … | none | … |
| jqGridAfterEditCell | … | none | … |
| jqGridSelectCell | … | none | … |
| jqGridBeforeSaveCell | … | … | … |
| jqGridBeforeSubmitCell | … | … | … |
| jqGridAfterSubmitCell | … | … | … |
| jqGridAfterSaveCell | … | none | … |
| jqGridErrorCell | … | none | … |
| jqGridAfterRestoreCell | … | none | … |
| jqGridSubGridBeforeExpand | … | … | … |
| jqGridSubGridRowExpanded | … | none | … |
| jqGridSubGridRowColapsed | … | … | … |
| jqGridGroupingClickGroup | … | none | … |
| jqGridImportComplete | … | none | … |
Return values from triggered events
Some from events in the above list should or have to return events. One should take in the consideration that one can register multiple event handles. The event handle should use result property of the event object to know the value returned from the previously invoked event handler. Depend on the type of returned value one should combine the results which one plan to return with the results returned by previous handler.
For example one implements jqGridBeforeSelectRow event handler which can return boolean true/false or “stop” string. The event will be called on click inside of the grid. jqGrid trigger jqGridBeforeSelectRow event before making selection of the clicked row. If the returned value is false or “stop”, jqGrid will don't make selection. So it should be clear that jqGridBeforeSelectRow event handler can return false if one decide to suppress row selection, but one couldn't just return true if the selection should be permitted. It will force selection even if previously invoked event handler returns false. So one have to test result property of e parameter. If it's undefined then there are no other event handler which was invoked previously. On the other side if the value e.result is false or “stop” then the previously invoked event handler decide to suppress selection. In the case one have to return the value e.result (false) instead of true. It means that we don't want to force the selection. We just don't protest the selection and we want to follow the decision of previously invoked event handler about the selection. The corresponding code could be the following:
$("gridid").bind("jqGridBeforeSelectRow", function (e, rowid, orgClickEvent) { ... // if we want to return true, we should test e.result additionally return e.result === undefined ? true : e.result; });
Alternatively one can test explicitly for for false or “stop”:
$("gridid").bind("jqGridBeforeSelectRow", function (e, rowid, orgClickEvent) { ... // if we want to return true, we should test e.result additionally return e.result === false || e.result === "stop" ? false : true; });
Execution Order
Below is the execution order of the events when a ajax request is made
- beforeRequest
- loadBeforeSend
- serializeGridData
- loadError (if a error from the request occur - the event from steps 5 till 7 do not execute. If there is no error the event 4. does not execute and we continue to with the step 5.)
- beforeProcessing
- gridComplete
- loadComplete
Discussion
All “before” methods should prevent further execution of any process by resulting in “false”. I cant prevent reloading grid if i dont need to.
Hi,
I want to get one particular column data in all pages. I am using.. _$('#tblUsers').jqGrid('getCol', 'Names', true);_
But this is giving only current page Names.I need all pages names. i didn't find any code for this. Please help me how to do this.
Hi, I have a mutliselection jqgrid with 1000 rows . I am showing 100 per each page. I want to get all selected rows in all pages. I am using.. _$(”#tblUsers”).jqGrid('getGridParam', 'selarrrow');_ But this is giving only current page selected rows.I need all pages selected rows. i didn't find any code for this. Please help me how to do this.
Hi! Does your grid loads all 1000 rows in one request, or it makes a request when switching a page?
Hi, What do you think about adding afterDeleteRow on a future version? For example, when deleting rows from a standard Add/Edit/Delete table, we may want to take a special action if the table is now empty, or we may need to update information that was dependant on the deleted row. Does that make sense?
I would like to use jQuery UI icons as action buttons in the last column of my grid. I have a column formatter making a div and a load of spans with ui-state-default, ui-icon classes etc.
Thing is, when the user selects a row, my icons get highlighted too.
I was wondering if there is any way I could hook into an event so that I can write my own selection routine?
I want to apply ui-state-highlight on a per-cell basis so that I can miss out my “Actions” cell. That is I _do_ want the row to be selected, I just want to control how it looks.
It's just that standard buttons I'm using look kinda rubbish compared with all the jQuery UI stuff that surrounds them.
The event “onCellSelect” states that it is disabled when using cell editing. I'm currently using it flawlessly and I am using cell edit in my grid.
hey, can i separate the serializeGridData and loadError and just put them in a function and call them evrytime the jqgrid needs to call them? so that my other jqgrid program can use them also?… is it posibble?
I use ColdFusion and my JSON response from ColdFusion back to the grid needs some simple manipulation done to it before it will work with jqGrid. I guess I'm hoping for an event between events 3 and 4…
Execution order of jqGrid Events… 1. beforeRequest 2. loadBeforeSend 3. serializeGridData
Here I need to remove some leading characters from my JSON rows response. Example: / / {“rows”:[{“cell”:[””,10000228637555,”ACSN”,”444657#002”,””,”OPEN”,”GFHGVKJLM”],”ID”:10000228637555},{“cell”:[etc… I need to remove the 2 leading forwards slashes. The option to remove them in ColdFusion BEFORE sending them back is not a option in my case. I need to do it on the jqGrid client side. Does anyone know if this is possible???
4. loadError 5. gridComplete 6. loadComplete
Gordon,
I use ColdFusion as well. I've tapped into an existing API I wrote for a mobile version of our site that is powered by Backbone.js that has a response resembling: { paging:{ … }, data:{ … }, cached:false}.
The data I need to present in my grid is location in response.data. I used the following code to get my data.
,jsonReader : {
repeatitems: false ,id: "asset_id" ,root: function (obj) { for(var i in obj.data.rows) { // MANIPULATON HERE } return obj.data.rows; }}
The above function allows you to manipulate the response anyway you need to.
Can I access other functions outside the scope of the event function (from within the event function)?
This section needs an update to include the changes to the event system since jqGrid 4.3.2
Currently the onSelectRow event seems to be firing on right click as well, however the beforeSelectRow does not seem to fire in this case. :( so my attempted workaround of:
beforeSelectRow: function (rowId, e) { var isLeftClick = false; var clickType = event.which; if (clickType == 1) { isLeftClick = true; } return isLeftClick; }is unsuccessful. Any suggestions?
Lisa, the onSelectRow handler can also receive the event object for you to decide which button was clicked. Try something like this:
onSelectRow: function (rowId, status, e) { if (!e || e.which === 1) { / / left click, perform actions here } }Hope that helps