Table of Contents
Common Editing Properties
One of the key reasons for displaying data in a grid is to edit it, quickly and easily. jqGrid supports editing data in three ways:
- cell editing: edit specific cells in a gird
- inline editing: edit several cells in the same row
- form editing: create a form to edit outside of the grid
Installation
Every editing module has its own description in the Download Manager, but all of them uses the common module which should be selected (marked ) if you plan to use the editing. For more information refer to Download.
For Developers - this is the grid.common.js in the src directory.
Options and Description
All editing modules uses a common properties in colModel in order to perform editing. Below is the list of these properties with detailed description:
- editable
- edittype
- editoptions
- editrules
- formoptions (valid only in form editing)
The common syntax of using these options is:
<script> jQuery("#grid_id").jqGrid({ ... colModel: [ ... {name:'price', ..., editable:true, edittype:'text', editoptions:{...}, editrules:{...}, formoptions:{...} }, ... ] ... }); </script>
For all other specific options and events refer to the appropriate module.
editable
The editable option is a boolean and can have a value of true or false. The option defines whether this field is editable (or not). Default is false. To make a field editable, set this option to true: editable:true.
We should mention that hidden fields are not editable; instead that they have been marked as editable. In the in-line and cell editing modules you should show these fields (using the showCol method) in order to edit it. In the form editing module you should use the editrules option (see below)
edittype
Edittype option defines the type of of the editable field. Possible values: 'text', 'textarea', 'select', 'checkbox', 'password', 'button', 'image', 'file' and 'custom'. The default value is 'text'.
text
When edittype is 'text', jqGrid constructs a input tag of type text:
<input type="text" ...../>
In editoptions we can set all the possible attributes for this field. For example,
... editoptions: {size:10, maxlength: 15}
will cause jqGrid to construct the following input
<input type="text" size="10" maxlength="15" />
In addition to the these settings, jqGrid adds the id and name attribute.
textarea
When edittype is 'textarea', jqGrid constructs a input tag of type textarea
<input type="textarea" .../>
In editoptions we can add additional attributes to this type. Typically, these govern the size of the box:
... editoptions: {rows:"2",cols:"10"}
<input type="textarea" rows="2" cols="10".../>
To these attributes jqGrid adds id and name attributes .
checkbox
When edittype is 'checkbox', jqGrid constructs a input tag as follows:
<input type="checkbox" .../>
editoptions is used to define the checked and unchecked values. The first value is checked. For example
...editoptions: { value:"Yes:No" }
This will construct
<input type="checkbox" value="Yes" offval="No".../>
defines a checkbox; when the value is Yes, the checkbox becomes checked, otherwise it is unchecked. This value is passed as a parameter to the editurl.
If in editoptions, the value property is not set, jqGrid searches for the following values (false|0|no|off|undefined) in order to construct the checkbox. If the cell content does not contain one of these values, then the value attribute becomes the cell content and offval is set to off.
Example if the cell content is true, then
<input type="checkbox" value="true" offval="off" checked.../>
To these attributes jqGrid adds id and name attributes.
select
When edittype is 'select', jqGrid constructs a input tag as follows:
<select> <option value='val1'> Value1 </option> <option value='val2'> Value2 </option> ... <option value='valn'> ValueN </option> </select>
To construct this element we have three possible variants:
1. Setting the editoptions value as string The editoptions value must contain a set of value:label pairs with the value separated from the label with a colon (:) and ended with(;). Whichever you use, something like the following
editoptions: { value: “FE:FedEx; IN:InTime; TN:TNT” }
will construct
<select> <option value='FE'> FedEx </option> <option value='IN'> InTime </option> <option value='TN'> TNT </option> </select>
2. Setting the editoptions value as object
In this case the editoptions value must contain an array {} with name:value properties separated by a comma. Below is an example:
... colModel : [ ... {name:'myname', edittype:'select', editoptions:{value:{1:'One',2:'Two'}} }, ... ] ...
This will construct an HTML select
<select> <option value='1'>One</option> <option value='2'>Two</option> </select>
3. Setting the editoptions dataUrl parameter
The editoptions dataUrl parameter is valid only for element of edittype:select. The dataUrl parameter represent the url from where the html select element should be get.
When this option is set, the element will be filled with values from the AJAX request. The data should be a valid HTML select element with the desired options - something like:
<select> <option value='1'>One</option> <option value='2'>Two</option> ... </select>
To this element, jqGrid adds the id and name attributes as above.
Multiple selection of options in a select box is also possible. A size attribute may be added as well
...editoptions: {multiple:true, size:3... }
password
When edittype is 'password', jqGrid constructs a input tag of type text:
<input type="password" ...../>
In editoptions we can set all the possible attributes for this field. For example,
... editoptions: {size:10, maxlength: 8}
will cause jqGrid to construct the following input
<input type="password" size="10" maxlength="8" />
In addition to the these settings, jqGrid adds the id and name attribute.
button
When edittype is 'button', jqGrid constructs a input tag of type text:
<input type="button" ...../>
In editoptions we can set all the possible attributes for this field. For example,
... editoptions: {value:'MyButton'}
will cause jqGrid to construct the following input
<input type="button" value="MyButton" />
In addition to the these settings, jqGrid adds the id and name attribute.
image
When edittype is 'image', jqGrid constructs a input tag of type text:
<input type="image" ...../>
In editoptions we can set all the possible attributes for this field. For example,
... editoptions: {src:'path_to_my_image'}
will cause jqGrid to construct the following input
<input type="image" src="path_to_my_image" />
In addition to the these settings, jqGrid adds the id and name attribute.
file
When edittype is 'file', jqGrid constructs a input tag of type text:
<input type="file" ...../>
In editoptions we can set all the possible attributes for this field. For example,
... editoptions: {alt:'Alt text'}
will cause jqGrid to construct the following input
<input type="file" alt="Alt text"... />
In addition to the these settings, jqGrid adds the id and name attribute.
custom
This edit type allows definition of a custom editable element. When the edit type is set to custom we should provide a set of two functions, one which creates the element, and one that gets and sets the value from in form in order to be posted to the server.
The functions that should be defined are custom_element and custom_value. See the editoptions below for more details
When the custom element is created we automatically do the following additinal tasks:
- add a class 'customelement'
- add attribute name with name from colModel
- add id according to the rules for every edited module.
The example above will create element input type text:
<script> function myelem (value, options) { var el = document.createElement("input"); el.type="text"; el.value = value; return el; } function myvalue(elem, operation, value) { if(operation === 'get') { return $(elem).val(); } else if(operation === 'set') { $('input',elem).val(value); } } jQuery("#grid_id").jqGrid({ ... colModel: [ ... {name:'price', ..., editable:true, edittype:'custom', editoptions:{custom_element: myelem, custom_value:myvalue} }, ... ] ... }); </script>
editoptions
The editoptions property is an array which contains information about the editing column. It is important to note that in the editoptions array you may set any valid attribute for the chosen edittype.
The editoptions property is used in the colModel array and the syntax is:
<script> jQuery("#grid_id").jqGrid({ ... colModel: [ ... {name:'price', ..., editoptions:{name1:value1...}, editable:true }, ... ] ... }); </script>
i.e. in name:value pair. Below is the list of the most commonly used options:
Property | Type | Description |
---|---|---|
value | mixed | When set for edittype checkbox this value should be a string with two possible values separated with a colon (:) - Example editoptions:{value:“Yes:No”} where the first value determines the checked property. When set for edittype select value can be a string, object or function. If the option is a string it must contain a set of value:label pairs with the value separated from the label with a colon (:) and ended with(;). The string should not ended with a (;)- editoptions:{value:“1:One;2:Two”}. If set as object it should be defined as pair name:value - editoptions:{value:{1:'One';2:'Two'}} When defined as function - the function should return either formated string or object. In all other cases this is the value of the input element if defined. |
dataUrl | string | This option is valid only for elements of type select - i.e., edittype:select and should be the URL to get the AJAX data for the select element. The data is obtained via an AJAX call and should be a valid HTML select element with the desired options <select><option value='1'>One</option>…</select>. You can use option group. The AJAX request is called only once when the element is created. In the inline edit or the cell edit module or form edit module it is called every time when you edit a new row or cell or lunch the form . |
buildSelect | function | This option is relevant only if the dataUrl parameter is set. When the server response can not build the select element, you can use your own function to build the select. The function should return a string containing the select and options value(s) as described in dataUrl option. Parameter passed to this function is the server response |
dataInit | function | We pass the element object to this function, if defined. This function is called only once when the element is created. Example : …editoptions: { dataInit : function (elem) { $(elem).autocomplete(); } } The event is called only once when the element is created. In the inline edit or the cell edit module it is called every time when you edit a new row or cell. In the form edit module only once if the recreateForm option is set to false, or every time if the same option is set to true . |
dataEvents | array | list of events to apply to the data element; uses $(“#id”).bind(type, [data], fn) to bind events to data element. Should be described like this: … editoptions: { dataEvents: [ { type: 'click', data: { i: 7 }, fn: function(e) { console.log(e.data.i); } }, { type: 'keypress', fn: function(e) { console.log('keypress'); } } ] } |
defaultValue | mixed | The option can be string or function. This option is valid only in Form Editing module when used with editGridRow method in add mode. If defined the input element is set with this value if only element is empty. If used in selects the text should be provided and not the key. Also when a function is used the function should return value. |
NullIfEmpty | boolean | If set to true a string 'null' is send to the server when the data in that field is empty |
custom_element | function | Used only if the edittype option is set to 'custom'. This function is used to create the element. The function should return the new DOM element. Parameters passed to this function are the value and the editoptions from colModel |
custom_value | function | Used only if the edittype option is set to 'custom'. This function should return the value from the element after the editing in order to post it to the server. Parameter passed to this function is the element object and the operation type In inline and cell editing modules this parameters is always a string value - 'get'. See below for the other type. In form editing this function has a different behavior. In this case we pass additional third parameter - the value. When a values of the custom element is posted to the server the second parameter has a value 'get'. In this case the function should return a value. If no values is returned in this case a error is raised. In case the data is read from the grid in order to set it in the form the operation parameter has a value 'set' and the grid value is passed as a third parameter. This way we can modify the grid value before it is displayed in the form. See the example above. |
other options | mixed | In this case you can set any other valid attribute for the editable element. For example, if the element is edittype:'text', we can set size, maxlength, etc. attributes. Refer to the valid attributes for the element |
editrules
This option add additional properties to the editable element and should be used in colModel. Mostly it is used to validate the user input before submitting the value(s) to the server. Syntax:
<script> jQuery("#grid_id").jqGrid({ ... colModel: [ ... {name:'price', ..., editrules:{edithidden:true, required:true....}, editable:true }, ... ] ... }); </script>
Below is the list of available options:
Option | Type | Description |
---|---|---|
edithidden | boolean | This option is valid only in form editing module. By default the hidden fields are not editable. If the field is hidden in the grid and edithidden is set to true, the field can be edited when add or edit methods are called. |
required | boolean | (true or false) if set to true, the value will be checked and if empty, an error message will be displayed. |
number | boolean | (true or false) if set to true, the value will be checked and if this is not a number, an error message will be displayed. |
integer | boolean | (true or false) if set to true, the value will be checked and if this is not a integer, an error message will be displayed. |
minValue | number(integer) | if set, the value will be checked and if the value is less than this, an error message will be displayed. |
maxValue | number(integer) | if set, the value will be checked and if the value is more than this, an error message will be displayed. |
boolean | if set to true, the value will be checked and if this is not valid e-mail, an error message will be displayed | |
url | boolean | if set to true, the value will be checked and if this is not valid url, an error message will be displayed |
date | boolean | if set to true a value from datefmt option is get (if not set ISO date is used) and the value will be checked and if this is not valid date, an error message will be displayed |
time | boolean | if set to true, the value will be checked and if this is not valid time, an error message will be displayed. Currently we support only hh:mm format and optional am/pm at the end |
custom | boolean | if set to true allow definition of the custom checking rules via a custom function. See below |
custom_func | function | this function should be used when a custom option is set to true. Parameters passed to this function are the value, which should be checked and the name - the property from colModel. The function should return array with the following parameters: first parameter - true or false. The value of true mean that the checking is successful false otherwise; the second parameter have sense only if the first value is false and represent the error message which will be displayed to the user. Typically this can look like this [false,“Please enter valid value”] |
Custom Checking example
<script> function mypricecheck(value, colname) { if (value < 0 || value >20) return [false,"Please enter value between 0 and 20"]; else return [true,""]; } jQuery("#grid_id").jqGrid({ ... colModel: [ ... {name:'price', ..., editrules:{custom:true, custom_func:mypricecheck....}, editable:true }, ... ] ... }); </script>
formoptions
This option is valid only in form editing. The purpose of these options is to reorder the elements in the form and to add some information before and after the editing element. Should be used in colModel array. Syntax:
<script> jQuery("#grid_id").jqGrid({ ... colModel: [ ... {name:'price', ..., formoptions:{elmprefix:'(*)', rowpos:1, colpos:2....}, editable:true }, ... ] ... }); </script>
Below is a list of available options
Option | Type | Description |
---|---|---|
elmprefix | string | if set, a text or html content appears before the input element |
elmsuffix | string | if set, a text or html content appears after the input element |
label | string | if set, this replace the name from colNames array that appears as label in the form. |
rowpos | number | determines the row position of the element (again with the text-label) in the form; the count begins from 1 |
colpos | number | determines the column position of the element (again with thelabel) in the form beginning from 1 |
Discussion
Here's an example of using editoptions dataEvents to change another form element based on an onChange event in a <select>. In this case, the form contains Job_Name and Job_Number fields. The value of the Job_Number field is set using the value of the selected Job_Name option.
this - in $('input#Job_Number').val(this.value); - refers to the DOM element associated with the onChange event, the Job_Name <select>, in this case.
The dataUrl returns plain text HTML ”<select><option value=999>Some Job Name</option>…</select>” that jqGrid uses to create the select.
Notice the use of the readonly attribute on the Job_Number field.
I am trying to have an edit form with two selection lists that are connected, similar to the above example. The first list is a group of main categories and the second is a list of subcategories relating to the main category. When the user chooses the main category, the list of subcategories should update so the user only sees relevant sub-categories.
Using the above technique from David Hansen, I can get the first list to update the second list whenever the user changes the first list. However, I need to populate the second list with an initial set of values, in case the user does not change the first list (for example, if they only want to change the subcategory, not the category).
Is there a hook I can use generate a change event from the first selection list? The code to generate the event itself is easy, but I am just having trouble figuring out how to get it called after the form is created.
did u solved u r issue regarding as you specified here .can u tell me the solution plzz…at least link were u got the information
thk u in advance
Bill, this maybe help you..
http://oviedos.com.mx/index.php/blog/show/JqGrid-Como-agregar-un-onchange-onclick-en-un-input.html
I'm trying to code my grid with the same functionality as Bill but the link above is not working. Do any of you know of the updated link or another link where I can get information on linking two select boxes in the grid?
Thanks in advanced!
jennifer did u solved u r issue regarding as you specified here .can u tell me the solution plzz…at least link were u got the information
thk u in advance
Is there documentation/specification about server responses on success/error. I was not able to find in here, also examples have just php snippet about how to read data.
can some one help me????, i am new in jqgrid
i need to use autocomplete in edit row mode when i am in a cell, i need to select a item in the list of autocomplete and put some values that came with the row in the autocomplete options inside the row that i am editing, i try to set the values in this form
jQuery('#list').setRowData(rowid,{C_trtmnto:row[0], pdgree:row[2], orgen:row[3]}); but this don´t work
the autocomplete row came like this: 1 | 'cesar' | 'sales' | 'door'
How can i do this????
my col model is
{name: 'nm_fmlias', width : 60, editable: true, sortable : true, formoptions: {elmprefix:”(*) ” }, editrules : {required:true}, editoptions: {size:80,maxlength:250, dataInit:function(el){
Hello, the way I do this (I confess I had to get help to develop it, I did not figure it out on my own) is this:
the inportant parts are, of course, the “select” and “change” events
hope this helps,
Reg
Is there way to have multiple checkboxes? I see that there's an option “multiple” for select box but users prefer checkboxes which are more user friendly.
I have an issue with using the custom functions and the next/prev buttons on an edit form. when I edit a record I see the id as a label as expected. When I use the next/prev button the values for Votes and Title change but it keeps the same Id value. They are different for each row. Any ideas?
colModel: [
Thanks, Paul
function customLabel(value, options) {
}
function customLabelValue(elem) {
}
I figured out a way to fix my previous issue. If some one knows of a better way please post it.
In the edit dialog options I did this:
After a lot of searching and finding nothing, I finally came up with a solution to a problem with edittype:select option. Whilst the form edit will correctly show the select options and their display values, the grid itself displays whatever you send to it as its data item;
i.e. supposing you have a dynamic loaded data grid with a column set as edittype:'select'with editoptions:{value:{1:'One',2:'Two'}}. If the data you actually put in the column = 1, then 1 gets displayed in the grid, but the correct selector will display in edit mode. To display 'One' you need to send 'One' into the display data for the grid. This is kind of counter intuitive, cus it means that for all your coded data items you need to retrieve the code's name value instead of the code itself which usually means joining one or more tables. So in short you need to send the option label, not the option value.
At the very least, this ought to be mentioned in the docs.
It could be great that the “editrules” options that validates data: [number, integer, minValue, maxValue, email, date, …] validate the data only if the “required” option is set to true, and don't do the validation of the data if is set to false.
This allow data validation for empty fields that are not required.
Good thought and worth discussing; I would prefer to see the validation fire only if the field is not empty, and the required routine control whether or not it is acceptable to have it empty. Perhaps that is what it is doing now.
Reg
Mmmm, I like that approach more than mine .
That it's not difficult to implement, isn't?
I don't think it would be hard; I am assuming that that is the way jqGrid operates now, but it has been some time since I have worked with these features and I tend to forget a lot. Maybe Tony can jump in here and clarify for us?
Reg
Hello Reg, Setting required to false will do what you want
Tony
I test these options with jqGrid 3.8 and they do the validation also with the field empty.
[Added] Hey!! There are miliseconds of differences between our responses! :D
Then my bad; sorry about that. I figured Tony had it working so that validation rules were kept separate from required rules.
Hope you can figure out something that works for you.
Reg
Seems like the validation of not required fields is IE-only issue. After some debugging and digging into the source code I found the cause: it's in the method $.jgrid.isEmpty (and in IE in the first place, of course).
The method implementation checks value for white spaces using
val.match(/^\s+$/)
. And empty cell contains a non-breakable space which is not considered as a white space by IE for some unknown reason. So the workaround was a custom validation function which essentially checked value using/^[\s\u00a0]+$/.test(val)
Hi
I'm new to jqGrid and i'm stuck width one (probably stupid) problem.
I have 2 select's in my form, both multiple. My idea is to populate the first one width some data, like all countries in the world and the user picks one or more countries from it and passes the values to the second one. The data is saved and all selected values are saved with the user ID in a relational table.
Now, how can i populate the second select, when editing, with data from the relational table??? i need the user ID but to filter results per user but i don´t know how to send it.
I have this:
{
}
P.S: sorry for my english, it's hard to explain what i need in this language…
What I really need is to include the datetime plugin: editable:true, edittype:'custom', editoptions:{custom_element: myelem, custom_value:myvalue}
Is there any possibility to get this done? Kind regards, Steffen (working with jQuery and Javascript for about 4 weeks and I get stuck sometimes…)
hi,
i would like to call a custom js function when clicking on the “add row” icon on the bottom of the grid. how could i do this? i bet its pretty simple?
thanks in ahead!
Hello, in form editing, error message will be display for an empty required field. If I have more than 1 required fields, only the error message for the 1st required field will be displayed. The error message for the 2nd required field will be displayed after keying in the 1 required field.
Is there any way that I can display the error messages for all empty required fields, instead of one by one?
Thanks!
Hi Tony. I am trying to set up a custom field to integrate KCfinder. What I am trying to do is to add a readonly input text field that when clicked it opens up the CKfinder window. My myelem() function looks like this:
function myelem(value,options){ return $('<input type=“text” readonly=“readonly” value=”'+value+'” onclick=“openKCFinder(this)” style=“width:200px;cursor:pointer” /><br><div id=“kcfinder_div”></div>');}';
However, for some reason the JQgrid is overriding my text field and hidden DIV bc when I view the source I got this:
<input id=“photo” class=“customelement” type=“text” style=“width: 200px; cursor: pointer;” onclick=“openKCFinder(this)” value=”” readonly=“readonly” name=“photo”> <br id=“photo” class=“customelement” name=“photo”> <div id=“photo” class=“customelement” name=“photo”></div>
So input element, div and even the <br> tag has been renamed to the field's name I gave. Is there any way to solve it?
Thank you Gabriel
Hi,
When using
colModel : [ … {name:“tags”,index:“tags”,editable:true,width:“250”,edittype:“select”, editoptions: {multiple:true,size:6,value:{tag1:“tag1”,tag2:“tag2”,tag3:“tag3”,tag4:“tag4”,tag5:“tag5”}}} … ]
After the grid has been loaded (json) and the user selects a row and click edit, the multi-select in the form edit dialog does not pre-select the values in the row. This only happens on the first load of the edit dialog. Subsequent loads the select box gets populated correctly.
Is there a work around for this or is this a feature or bug.
Regards
Hi!
How I can differentiate wether the dataInit event is fired in the “add” form or in the “edit” form?
This question is answered here: http://stackoverflow.com/questions/6973896/jqgrid-differentiate-in-datainit-add-and-edit-forms/6974432#6974432
Hola amigos,
Cual es la funcion que permite usar combobox relacionados en el form editting??
colModel:[
{ name:'subcat',
Wouldn't it be logical to include a colspan, rowspan parameter? If there is already a colpos and rowpos! Now one can design multirow/multicolumn editforms, but can't really make an advantage out of the fact that some input boxes are smaller than others.
how to load 2 dropdowns dynamically in sjg:gridcolumn .i got 1 dropdown but iam trying second dropdown data is not populating in that ..
Hi guys!
I maybe have found a bug.
when using editrules {custom: true, custom_func: myFunc} in the original documentation says
Parameters passed to this function are the value, which should be checked and the name - the property from colModel.
but really myFunc pass value and column title from colNames (label from colModel).
part of my colNames colNames:[ … 'this is collname', … ],
part of my colModel colModel :[ … {name:'vin', index:'vin', width:120, editable:true, edittype:'text', editrules:{custom: true, custom_func:myFunc}}, … ],
myFunc function myFunc(value, colname) {
}
proof screenshot
Version Information:
1. For some reason closeAfterEdit and closeAfterAdd did not work for me. The form is still open after the form is submiited, can someone tell me why? here is part of my grid definition:
$(”#mytable”).jqGrid('navGrid', '#mytablepager', { cloneToTop: true }, { edit: true, add:true, del:true, search: true }, { edit option closeAfterEdit:true, closeOnEscape: true, beforeShowForm: function(form) { $('#tr_Active', form).show(); } }, { add option
2. how do i define the grid so it display a particular textbox only when editing hide it when adding a new entry?
Thank you
hi, Edittype:file uploads only one file at a time is there any option so that we can upload multiple files at a time?
i find a bug: when i set a checkbox field by searchoptions,formatoptions,editoptions with a same value:[Y:N], the field is always checked! but,when i only set editoptions to the field, then it's worked!
Potential Bug: Checkbox values are not added to the params map within the Grails framework. For instance, if you have a grid with 5 rows and one of the fields/columns is a checkbox type and the values (0-4) are (true, false, true, true, false) where true=checked and false=not checked, then what gets sent to the backend during submit is an array of size 3 (index 0, 1, and 2) all with values of true AND the indexes do not correspond to the correct row.
Sorry that I cannot include sample code and I'm also sorry that this may not be the standard way of capturing grid values during submission, but the legacy system I am refactoring dictates this, for now.
Please advise. Thanks in advance.