Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
wiki:methods [2010/08/27 16:06] tony |
wiki:methods [2018/02/02 20:53] (current) admin |
||
|---|---|---|---|
| Line 1: | Line 1: | ||
| - | ~~ODT~~ | ||
| ====== Methods ====== | ====== Methods ====== | ||
| This chapter describes the basic methods of jqGrid. Some methods require that additional modules should be loaded. \\ | 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. | As of version 3.6 jqGrid uses new API which is compatible with jQuery UI library. See below. | ||
| - | See also [[wiki:events|jqGrid Events]]. | + | See also [[wiki:events|jqGrid Events]] |
| ===== Grid Related Methods ===== | ===== Grid Related Methods ===== | ||
| Line 55: | Line 54: | ||
| </code> | </code> | ||
| <note important> | <note important> | ||
| - | It is important to note that the existing users cannot change their code. You are free to use both conventions. \\ | + | 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. | 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. | ||
| </note> | </note> | ||
| Line 65: | Line 64: | ||
| <head> | <head> | ||
| <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> | <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> | ||
| + | <meta http-equiv="X-UA-Compatible" content="IE=edge" /> | ||
| <title>My First Grid</title> | <title>My First Grid</title> | ||
| | | ||
| Line 95: | Line 95: | ||
| |<color green>addJSONData</color>|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 \\ <color blue> var mygrid = jQuery("#"+grid_id)[0];\\ var myjsongrid = eval("("+jsonresponse.responseText+")"); \\ mygrid.addJSONData(myjsongrid); \\ myjsongrid = null; \\ jsonresponse =null; </color> \\ will populate the data to the grid. And, of course, the data in myjsongrid can be manipulated before being passed to addJSONData.| | |<color green>addJSONData</color>|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 \\ <color blue> var mygrid = jQuery("#"+grid_id)[0];\\ var myjsongrid = eval("("+jsonresponse.responseText+")"); \\ mygrid.addJSONData(myjsongrid); \\ myjsongrid = null; \\ jsonresponse =null; </color> \\ 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. | | |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. | | ||
| - | |<color green>addXMLData</color>|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 \\ <color blue> var mygrid = jQuery("#"+grid_id)[0]; \\ mygrid.addXmlData(xmlresponse.responseXML); </color>\\ will populate the data into the grid. And, of course, the data in xmlresponse can be manipulated before being passed to addXmlData.| | + | |<color green>addXmlData</color>|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 \\ <color blue> var mygrid = jQuery("#"+grid_id)[0]; \\ mygrid.addXmlData(xmlresponse.responseXML); </color>\\ 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.| | |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.| | |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| | |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.\\ <color red>Do not use this method when you editing the row or cell. This will return the cell content and not the actuall value of the input element </color>| | + | |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.\\ <color red>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 </color>| |
| |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| | |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. | | |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]].| | |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.| | |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.| | ||
| - | |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.\\ <color red>Do not use this method when you editing the row or cell. This will return the cell content and not the actuall value of the input element </color> \\ If the rowid is not set the method return all the data from the grid in array| | + | |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.\\ <color red>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.) </color> \\ 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.| | |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.| | |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.| | |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.| | |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 | | |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 | | ||
| Line 113: | Line 118: | ||
| |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'.| | |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.| | |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 (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| | + | |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 \\ <color red>Do not use this method when you editing the row or cell. This will set content and and overwrite the input elements </color> \\| | + | |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 \\ <color red>Do not use this method when you are editing the row or cell. This will set the content and overwrite the input elements.</color> \\| |
| |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.| | |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.| | |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| | + | |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| | ||
| |<color green>updateColumns</color>|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: \\ <color blue> var mygrid=jQuery("#grid_id")[0];\\ mygrid.updateColumns();</color>| | |<color green>updateColumns</color>|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: \\ <color blue> var mygrid=jQuery("#grid_id")[0];\\ mygrid.updateColumns();</color>| | ||
| Line 161: | Line 167: | ||
| |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.| | |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.| | |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.| | ||
| + | |||
