====== Methods ======
This chapter describes the basic methods of jqGrid. Some methods require that additional modules should be loaded. \\
As of version 3.6 jqGrid uses new API which is compatible with jQuery UI library. See below.
See also [[wiki:events|jqGrid Events]]
===== Grid Related Methods =====
Calling Convention:
Where:
* //grid_id// is the id of the already constructed jqGrid.
* //jqGridMethod// is a method applied to this jqGrid.
* //parameter1,...parameterN// - a list of parameters
Where a method is not designed to return a requested value, then what is returned is the jqGrid object and a set of such methods can be chained, e.g.,
or using the new API
Where:
* //grid_id// is the id of the already constructed grid.
* //jqGrid// is a jqGrid instance.
* //method// is jqGrid existing method. Note that the method should be enclosed in ''
* //parameter1,...parameterN// - a list of parameters
Having this our example will look like this:
The old and new APIs are enabled by default so that existing users do not have to change their code. You are free to use both conventions. \\
The reason for creating this API is to overcome and name-space conflicts with other plugins and make using jqGrid more natural in the code. In order to use only this new API see the configuration below.
=== Configuring jqGrid to use only the new API ===
This should be done in the installation procedure following these steps:
My First Grid
...
Note the callling of
This line should be after the language file and before the jqGrid JS file
Method names in green require special calling procedures. See the individual method descriptions for example usage.
^Method^Parameters^Returns^Description^
|addJSONData|data|none|Populates a grid with the passed data (an array).This method should be used this way - Example: Suppose we have data from a particular webservice (jsonresponse), then \\ var mygrid = jQuery("#"+grid_id)[0];\\ var myjsongrid = eval("("+jsonresponse.responseText+")"); \\ mygrid.addJSONData(myjsongrid); \\ myjsongrid = null; \\ jsonresponse =null; \\ will populate the data to the grid. And, of course, the data in myjsongrid can be manipulated before being passed to addJSONData.|
|addRowData|rowid,\\ data, \\ position, \\ srcrowid| true on success, \\ false otherwise | Inserts a new row with id = //rowid// containing the data in //data// (an object) at the //position// specified (first in the table, last in the table or before or after the row specified in //srcrowid//). The syntax of the data object is: {name1:value1,name2: value2…} where name is the name of the column as described in the colModel and the value is the value. \\ This method can insert multiple rows at once. In this case the data parameter should be array defined as \\ [{name1:value1,name2: value2…}, {name1:value1,name2: value2…} ] and the first option rowid should contain the name from data object which should act as id of the row. It is not necessary that the name of the rowid in this case should be a part from colModel. |
|addXmlData|data|none|Populates a grid with the passed data. This method should be used this way - Example: \\ Suppose we have data from a particular webservice (xmlresponse), then \\ var mygrid = jQuery("#"+grid_id)[0]; \\ mygrid.addXmlData(xmlresponse.responseXML); \\ will populate the data into the grid. And, of course, the data in xmlresponse can be manipulated before being passed to addXmlData.|
|bindKeys|{ \\ onEnter: null, \\ onSpace: null, \\ onLeftKey: null, onRightKey: null, \\ scrollingRows : true \\ }| jqGrid object | When called the method make it so that it is possible to select a row with Up and Down keys - i.e we scroll the grid data with keys. It is possible to invoke additional events when the row is selected and a key like enter, space, left or right are pressed. To these events a selected id of the row is passed as parameter.|
|clearGridData|clearfooter|jqGrid object| Clears the currently loaded data from grid. If the clearfooter parameter is set to true, the method clears the data placed on the footer row.|
|delRowData|rowid|true on success, \\ false otherwise|Deletes the row with the id = //rowid//. This operation does not delete data from the server.|
|editRow|rowid,\\ keys\\ | none? |Edits the row specified by **rowid**. **keys** is a boolean value, indicating if to use the Enter key to accept the value ane Esc to cancel the edit, or not.|
|footerData|action,\\ data, \\ format|jqGrid object|This method gets or sets data on footer. See footerrow in [[options]] array.\\ //action// - can be 'get' or 'set'. The default is get. 'get' returns an object of type name:value, where the name is a name from colModel. This will return data from the footer. The other two options have no effect in this case. \\ 'set' takes a //data// array (object) and places the values in the footer. The object should be in name:value pair, where the name is the name from colModel\\ //format// - default is true. This instruct the method to use the formatter (if set in colModel) when new values are set. A value of false will disable the using of formatter|
|getCell|rowid, \\ iCol|cell content| Returns the content of the cell specified by id = //rowid// and column = //iCol//. iCol can be either the column index or the name specified in colModel.\\ Do not use this method when you are editing the row or cell. This will return the cell content and not the actuall value of the input element |
|getCol|colname, returntype, mathoperation|array[] or value| This method returns an array with the values from the column. //colname// can be either a number that represents the index of the column or a name from colModel. returntype determines the type of the returned array. When set to false (default) the array contain only the values. \\ When set to true the array contain a set of objects. The object is defined as {id:rowid, value:cellvalue} where the rowid is the id of the row and cellvalue is the value of the cell. For example, such output can be [{id:1,value:1},{id:2,value:2}...] \\ The valid options for mathoperation are - 'sum, 'avg', 'count'. If this parameter is set and is valid, the returned value is a scalar representing the operation applied to the all values in the column. If the parameter is not valid the returned value is empty array|
|getDataIDs|none|array[]|This method returns an array of the id's in the current grid view. It returns an empty array if no data is available. |
|getGridParam|name|mixed value|Returns the value of the requested parameter. //name// is the name from the options array. If the name is not set, the entry options are returned. For available options, see [[options]].|
|getInd|rowid,\\ rowcontent| mixed| This method returns the index of the row in the grid table specified by id= //rowid// when //rowcontent// set to false (default). If rowcontent is set to true, it returns the entry row object. If the rowid can not be found, the function returns false.|
|getLocalRow|rowid| row object | Return the row data from the local array stored in data parameter when the datatype is local|
|getRowData |rowid or none|array{}|Returns an array with data of the requested id = //rowid.// The returned array is of type name:value, where the name is a name from colModel and the value from the associated column in that row. It returns an empty array if the rowid can not be found.\\ 1. Do not use this method when you are editing the row or cell. This will return the cell content and not the actuall value of the input element.2.the performance of this method becomes an issue. Do not use this method in the body of "for" and "when". (When calling this method, it will calculates the row datas one time.) \\ If the rowid is not set the method return all the data from the grid in array|
|hideCol|colname\\ or\\ [colnames]|jqGrid object|Given a single colname, it hides the column with that name. Given an array of colnames ["name1","name2"], it hides the columns with those names, 'name1' and 'name2', in the example. The names in colname or colnames must all be valid names from the colModel. \\ NB: The width of the grid is not changed.|
|remapColumns|permutation, updateCells, keepHeader|none|Reorder the grid columns based on the permutation array. The indexes of the //permutation// array are the current order, the values are the new order. By example if the array has values [1,0,2] after calling this method the first column will be reordered as second. //updateCells// if set to true will reorder the cell data. //keepHeader// if set to true will reorder the data above the header cells.|
|resetSelection|none|jqGrid object|Resets (unselects) the selected row(s). Also works in multiselect mode.|
|restoreRow|rowid|none?|Restores the data to original values before the editing of the row specified by **rowid**.|
|saveRow|rowid,\\ callback,\\ url,\\ extraparams\\ |none?|Saves the row specified by **rowid**, after it has been opened for editing mode by the editRow method. **callback** is a function called after the save is complete. The function accepts an XMLHttpRequest object with the response from the server. **url** is the URL used to submit the values. If specified, this value overrides the value specified by the [[options|editurl]] option. **extraparas** are additional parameters passed to the server. Data is posted in the form id=rowid&name=value..., where the name is the "name" from [[colmodel_options|colModel]].|
|setCaption|caption|jqGrid object|Sets a new caption of the grid. If the Caption layer was hidden, it is shown.|
|setCell|rowid,\\ colname, \\ data, \\ class, \\ properties, \\ forceup|jqGrid object|This method can change the content of particular cell and can set class or style properties. Where: \\ //rowid// the id of the row, \\ //colname// the name of the column (this parameter can be a number (the index of the column) beginning from 0 \\ //data// the content that can be put into the cell. If empty string the content will not be changed \\ //class// if class is string then we add a class to the cell using addClass; if class is an array we set the new css properties via css \\ //properties// sets the attribute properies of the cell, \\ //forceup// If the parameter is set to true we perform update of the cell instead that the value is empty |
|setGridParam|object|jqGrid object|Sets a particular parameter. Note - for some parameters to take effect a trigger("reloadGrid") should be executed. Note that with this method we can override events. The name (in the name:value pair) is the name from options array. For a particular options, see [[options]].|
|setGridHeight|new_height|jqGrid object|Sets the new height of the grid dynamically. Note that the height is set only to the grid cells and not to the grid. //new_height// can be in pixels, percentage, or 'auto'.|
|setGridWidth|new_width,\\ shrink|jqGrid object|Sets a new width to the grid dynamically. The parameters are: \\ //new_width// is the new width in pixels.\\ //shrink (true or false)// has the same behavior as shrinkToFit - see [[options]]. If this parameter is not set we take the value of shrinkToFit.|
|setLabel| colname, \\ data, \\ class, \\ properties|jqGrid object|Sets a new label in the header for the specified column; can also set attributes and classes . The parameters are: \\ //colname// the name of the column from colModel(this parameter can be a number (the index of the column) beginning from 0 \\ //data// the content that can be put into the label. If empty string the content will not be changed \\ //class// if class is string then we add a class to the label using addClass; if class is an array we set the new css properties via css \\ //properties// sets the attribute properies of the label|
|setRowData|rowid,\\ data, \\ cssprop|true on success, \\ false otherwise|Updates the values (using the //data// array) in the row with //rowid//. The syntax of data array is: {name1:value1,name2: value2…} where the name is the name of the column as described in the colModel and the value is the new value. \\ If the cssprop parameter is string we use addClass to add classes to the row. If the parameter is object we use css to add css properties. Note that we can set properties and classes without data, in this case we should set data to false \\ Do not use this method when you are editing the row or cell. This will set the content and overwrite the input elements. \\|
|setSelection|rowid,\\ onselectrow|jqGrid object|Toggles a selection of the row with id = //rowid//; if //onselectrow// is true (the default) then the event onSelectRow is launched, otherwise it is not.|
|showCol|colname|jqGrid object|Shows a column with a given //colname//. If the colname is a string we show only the specified column. If colname is array of type ["name1","name2"] then the columns with names 'name1' and 'name2' will be shown at the same time The names in colname must be valid names from colModel. The width does not change.|
|trigger("reloadGrid")|none|none| Reloads the grid with the current settings. This means that a new request is send to the server if datatype is xml or json. This method should be applied to an already-constructed grid. Pay attention that this method does not change HEADER information, that means that any changes to colModel would not be affected. You should use gridUnload to reload new configuration with different colModel. IT'S WORK ONLY IF loadonce: false !!! |
|unbindKeys| none | jqGrid object| unbind the events defined in bindKeys method|
|updateColumns|none|none|this synchronizes the width of the headers with the data. Useful when used with table drag and drop. This method should be used this way - Example: \\ var mygrid=jQuery("#grid_id")[0];\\ mygrid.updateColumns();|
===== Common functions and settings =====
These functions can be used anywhere in the project and are not related to the jqGrid object. This mean the the syntax is:
Where:
* //jgrid.jqGridFunction// is a function.
* //parameter1,...parameterN// - a list of parameters
\\
Note the namespace jgrid
\\
^Function/Option^Parameters^Returns^Description^
|ajaxOptions|empty object|none|This option allow to set global ajax settings for all ajax requests used in the grid. Note that with this option is possible to overwrite all current ajax setting for the particular module. Starting from version 3.6 we have a 3 level ajax settings. \\ The first level is specific for the module when we use ajax. \\ The second level is determined from this option, and the \\ third level can be passed as additional parameter for the particular method. The third level ajax setting has a higher priority. This means that we use this global rule for all ajax settings: \\ jQuery.extend(jQuery.ajax({method specific options}, ajaxOptions, ThirdLevelajaxSettinds)); \\ Additional to this we have a possibility to define on every ajax request serialize function which allow to convert the parameters passed to the server.|
|jqID|string|parsed string|Escapes the special string characters with two backslashes (\\) so that a single backslash will be put into the string and can be interpreted correct when used in jQuery selector.|
|jgrid.htmlDecode|string|decoded_string| The htmlDecode function decodes an HTML encoded string back into the original html code. |
|jgrid.htmlEncode|string|encoded_string| The htmlEncode function encodes an HTML string - opposite to htmlDecode |
|jgrid.format|string|formated_string| Simple string-templating. Accepts a string template as the first argument. The second is optional: If specified, it is used to replace placeholders in the first argument.\\ Example jQuery.jqgformat("Please enter a value between {0} and {1}.", 4, 8)\\ result : "Please enter a value between 4 and 8."|
|jgrid.getCellIndex|cell| index| This method is used to correct the bug in Internet Explorer versions <= 7 where CellIndex is calculated in Display Order and not in real one. //cell// is the cell content (i.e.) td element|
|jgrid.stringToDoc|xmlstring|xmlDoc| Convert //xmlstring// to dom document. Return //xmlDoc// - dom document.|
|jgrid.stripHtml|content|new_content|Function for stripping out HTML tags from a given content.|
|jgrid.parse|jsonString|object|This function parses a jsonString (JSON text) to produce an object or array.\\ To prevent JavaScript hijacking attacks, web application authors are encouraged to use this function. This returns a JSON representation of the variable.\\ Cyclic structures are detected and safely interrupted, but could not be further restored.\\ 1. The while(1); construct, located at the beginning of JSON text, \\ 2. Comments at the beginning and end of the text. \\ JSON data providers are encouraged to use one or both of these methods to prevent data execution. Such JSON response may then look like this \\ while(1);/*{[ \\ {"name":"safe value 1"}, \\ {"name":"safe value 2"}, ... \\ ]}*/ \\ jqGrid uses this function when obtaining a data with datatype:'json' |
===== Add on Grid Methods =====
To use these methods you will need to mark Custom checkbox when downloading the grid See [[download]]. For developers - these method are located in file grid.custom.js. These methods should be used as those described in Chapter 1 - i.e that are jqGrid methods.
^Method^Parameters^Returns^Description^
|filterGrid|grid_id,\\ params|HTML object|This method can be called to construct an custom search form for the grid and should be not applied to the grid but to a valid HTML element. \\ //grid_id// is the id of the grid to which the search will be applied. \\ //parms// is an array of parameters (see below). For more details refer to [[custom searching]]|
|filterToolbar|params|jqGrid object|This method is the same as filterGrid, except that the search input elements are placed in the grid just below the header elements. When the header elements are resized the input search elements are also resized according to the new width. Another difference to the filterGrid is that the filter toolbar uses definitions from colModel. For more information refer to [[Toolbar searching]]|
|getColProp|colname|array{}|Return an array of the properties of the given column name from colModel|
|GridDestroy|grid_id|true on success, \\ false otherwise|Destroys the entry grid with id= //grid_id// from the DOM (clears all the html associated with the grid and unbinds all events)|
|GridUnload|grid_id|true on success, \\ false otherwise|The only difference to previous method is that the grid is destroyed, but the table element and pager (if any) are left ready to be used again.|
|setGridState|state|jGrid object|Show or hide the grid depending and state parameter. When the state is set to 'visible' the grid will be shown. When the parameter is set to 'hidden' the grid will be hidden. Note that the method does not call onHeaderClick event and the caption of the grid is allway visible|
|setColProp|colname, \\ properties|jGrid object|Sets new properties in colModel. This method is ideal for dynamically changing properties of the column. Note that some properties - have no effect see [[colModel options]]. For example: \\ jQuery("#grid_id").setColProp('colname',{editoptions:{value:"True:False"}}); \\ will change the editoptions values.|
|sortGrid|colname, \\ reload|jqGrid object|Sorts the given colname and shows the appropriate sort icon. The same (without sorting icon) can be done using setGridParam({sortname:'myname'}).trigger('reloadGrid'). If the reload is set to true, the grid reloads with the current page and sortorder settings.|
|updateGridRows|data,\\ rowidname,\\ jsonreader|true on success, \\ false otherwise|This method update the existing data in the grid by given //rowidname//. \\ //data// is a array of data in format \\ [{name:value,name1:value1...}, {name:value,name2:value2...}] \\ where the name is the name from colModel and value is the actuall value. It is not neccessary that all columns are present in the data item object (the same as setRowData method)\\ //rowidname// (string) - is the name of the row which should acts as id If not set the name "id" is used. \\ //jsonreader// (boolean) default false. If set to true a jsonReader definition is used to set the data. Note that this work only if the item in jsonReader object 'repeatitems' is set to true.In this case the data should be not in pair name:value, but only values where the number of columns should be equal of those in colModel.|