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:

  1. cell editing: edit specific cells in a gird
  2. inline editing: edit several cells in the same row
  3. 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:

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.

For every editable element jqGrid construct different name and id which are specific for every module. Refer to the appropriate module on how these are constructed

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>
Note the last element in the string - it should not end with ;

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.

When this element is created (usually in form editing) the form does not become ENCTYPE=“multipart/form-data” in order to upload the file. You should apply another plugin for this purpose - Ajax File Upload plugin works fine.

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:

  1. add a class 'customelement'
  2. add attribute name with name from colModel
  3. 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:

PropertyTypeDescription
valuemixedWhen 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.
dataUrlstringThis 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 . In the form edit module only once.
buildSelectfunctionThis 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
dataInitfunction 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 .
Note: Some plugins require the position of the element in the DOM and since this event is raised before inserting the element into the DOM you can use a setTimeout function to accomplish the desired action. This is especially valid for jQuery UI datepicker (1.7.x and up releases)
dataEventsarraylist 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'); } }
]
}
defaultValuemixed 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 optionsmixedIn 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:

OptionTypeDescription
edithiddenbooleanThis 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.
requiredboolean (true or false) if set to true, the value will be checked and if empty, an error message will be displayed.
numberboolean (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.
integerboolean(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.
minValuenumber(integer)if set, the value will be checked and if the value is less than this, an error message will be displayed.
maxValuenumber(integer)if set, the value will be checked and if the value is more than this, an error message will be displayed.
emailbooleanif set to true, the value will be checked and if this is not valid e-mail, an error message will be displayed
urlbooleanif set to true, the value will be checked and if this is not valid url, an error message will be displayed
dateboolean 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
timebooleanif 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
customboolean if set to true allow definition of the custom checking rules via a custom function. See below
custom_funcfunction 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>
If you plan to use this object in collModel with rowpos and colpos properties it is recommended that all editing fields use these properties.

Below is a list of available options

OptionTypeDescription
elmprefixstringif set, a text or html content appears before the input element
elmsuffixstringif set, a text or html content appears after the input element
labelstringif set, this replace the name from colNames array that appears as label in the form.
rowposnumberdetermines the row position of the element (again with the text-label) in the form; the count begins from 1
colposnumberdetermines the column position of the element (again with thelabel) in the form beginning from 1
Two elements can have equal row position, but different column position. This will place the two elements in one row on the form.