New callbacks and jQuery events - free-jqgrid/jqGrid GitHub Wiki

Starting with version 4.3.2 jqGrid supports jQuery events additionally to callbacks. In opposite to callbacks one can register more as one event handler, which is very important for writing jqGrid plugins or to use jqGrid in large project. One can register some event, like jqGridSelectRow to do some actions common for the whole project and one can still use onSelectRow callback or more jqGridSelectRow event handlers for individual action for specific grid. Moreover one can register events before the grid will be created. In other words all events on the basis <table> element will be hold during converting it to grid.

On the other side jqGrid still have many callback which has no corresponding jQuery events. For example Add/Edit dialogs support both callbacks and events, but View and Delete forms not.

All new callbacks and events of free jqGrid 4.8 fry to hold one new design goal. There have one parameter, which contains named properties. Such design:

• allows more easy to extend every callback with new additional information
• reduce warnings about "unused parameters"
• simplify the usage by including optional information about the execution context like column name or column index

We try to hold common names for the properties of the callbacks/events where

• this is like before the DOM of the grid
• cm is the element of colModel. The options exist if the callback/event have relation to specific column
• name or cmName is the same as cm.name
• iCol is the index of cm in colModel
• iRow is row index - 1-based index of row related for the callback/event
• rowid is the rowid
• mode the string which contains information about the searching/editing mode: "add", "edit", "addForm", "editForm" and so on
• item will be used in callbacks/events editing local editing. It represent the item from data array which have relation to the callback/event.
• id will be used in callbacks/events editing local editing. It contains rowid without idPrefix.
• newValue, oldValue, newItem, oldItem are the cell values and the items modified during local editing.

Not all properties will be set in all callbacks, but we try to hold the common name conversion of the properties.

Another common problem in old versions of jqGrid (till 4.7): the callbacks called after events could be not called if the event returns false or "stop". It's common design problem described in details here. The problem is fixed in jqGrid 4.7 only for beforeSelectRow callback and jqGridBeforeSelectRow event. Free jqGrid 3.8 provide common solution of the problem for all existing events/callbacks.

Free jqGrid creates common internal methods $.jgrid.fullBoolFeedback, $.jgrid.feedback, $.jgrid.serializeFeedback which will be permanently used in the code of free jqGrid to make unify way for making callbacks/events. Additional methods will be added in the future.

The following new callbacks/events are supported now in free jqGrid 3.8

• treeGridBeforeExpandRow callback, jqGridTreeGridBeforeExpandRow event. There will be called at the beginning of expandRow method.
• treeGridAfterExpandRow callback, jqGridTreeGridAfterExpandRow event. There will be called at the end of expandRow method.
• treeGridBeforeCollapseRow callback, jqGridTreeGridBeforeCollapseRow event. There will be called at the beginning of collapseRow method.
• treeGridAfterCollapseRow callback, jqGridTreeGridAfterCollapseRow event. There will be called at the end of collapseRow method.
• treeGridBeforeExpandNode callback, jqGridTreeGridBeforeExpandNode event. There will be called at the beginning of expandNode method.
• treeGridAfterExpandNode callback, jqGridTreeGridAfterExpandNode event. There will be called at the end of expandNode method.
• treeGridBeforeCollapseNode callback, jqGridTreeGridBeforeCollapseNode event. There will be called at the beginning of collapseNode method.
• treeGridAfterCollapseNode callback, jqGridTreeGridAfterCollapseNode event. There will be called at the end of collapseNode method.

TreeGrid hold the information about grid nodes locally in data array. All above callback get the only parameter in the callback/event (if one don't calculate the first Event parameter of every jQuery event). The parameter is object with two properties: rowid and item, there the item represent the element of data which corresponds the current row/node.

The main problems of onPaging callback in jqGrid 4.5-4.7:

• the moment of calling is very early
• the callback get almost no information in the parameter which could help to decide whether to return false to prevent the paging request or not. The callback have to get manually all the information using the internal knowledge of jqGrid structures. The case when both top and the bottom pagers are used is the mostly difficult. The implementations of callbacks could take in consideration not all cases and so there can contains hidden errors.
• the documentation of onPaging callback says that the pgButton parameter will be "first", "last", "prev", "next" in case on clicking on the pager buttons. On the other side many latest versions of jqGrid (till 4.7) use id of the button as the value of pgButton parameter. So the value can be something like

One can read more details about the existing problem in the answer or more old one: this, this, this and other.

Free jqGrid change the value of the pgButton parameter to documented values "first", "last", "prev", "next", "records" and "user". It's clear that it can produce small compatibility issue, but one have to fix the existing bug in the usage of wrong values of pgButton parameter.

Additionally free jqGrid adds the second object parameter, which we can name for example as options, to onPaging callback, which contains all information which can be needed by the callback. The object options contains the following properties:

• newPage - new value of the page which is requested to be displayed.
• currentPage - the value of page parameter converted to integer.
• lastPage - the value of lastpage parameter converted to integer. It's the value of last page of data known by jqGrid. In case of grid with remote datatype ("json" or "xml") the real value of the last page can be change and have now another value.
• currentRowNum - the value of rowNum parameter converted to integer. It contains the number of rows per page.
• newRowNum - the new value of the number of rows per page.

There is one common problem in the usage of dataUrl property of editing or searching (the property of editoptions or searchoptions). There is no callback/event till the version 4.7 of jqGrid, which will be called after the corresponding <select> is filled. It's a problem if one want to initialize some plugin (like multiselect or select2 plugins for example) with the data loaded in the <select>. One have to use the tricks and to use buildSelect only to know the moment of receiving the server response from dataUrl.

Free jqGrid 4.8 solve the problem by introducing of new callback selectFilled, which can be defined inside of editoptions or searchoptions. One can use jqGridSelectFilled event for the same goal. The callback/event get one options parameters which have the following properties:

• elem - DOM element of the <select> which is full filled with the data now
• options - contains editoptions or searchoptions
• cm - the item of colModel where the select is defined
• cmName - the name of the column (cm.name)
• iCol - the index of cm inside of colModel

To be conform with other ways of filling, the event jqGridSelectFilled and the callback selectFilled will be called at the end of filling <select> event if one uses values property of editoptions or searchoptions instead of dataUrl property.