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

By default when to colModel is created all fields are marked as editable, where the field is represented as input of type text.
If we want to disable the editing of some field we should just set the property editable to false:

$grid->setColProperty('somefield',array("editable"=>false));

after the colModel is created with setColModel method.

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: 

<?php
....
$grid->setColModel(...);
$grid->setColProperty('somefield',array("editable"=>true, "edittype"=>"text", "editoptions"=>array(...), "editrules"=>array(...), "formoptions"=>array(...)));
...

$grid->renderGrid(...);
...
?>

The editable option is boolean and can have two values true or false. The option defines if this field is editable (or not). Default is true. To make a field non editable, set this to false: editable=>false.
We should mention that the hidden fields are not editable instead that they have been marked as editable. In in-line and cell editing modules you should show these fields (using showCol method) in order to edit it. In form editing module you should use editrules option (see below)

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"=>array("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"=>array("rows"=>3, "cols"=> 20).....

<input type="textarea" rows="3" cols="20".../>

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"=>array("value"=>"Yes:No" )...

This will construct

<input type="checkbox" value="Yes" offval="No".../>

defines a checkbox in which when the value is Yes the checkbox becomes checked, otherwise unchecked. This value is passed as parameter to the editurl.

If in the editoptions the value property is not set jqGrid search for the following values (false|0|no|off|undefined) in order to construct 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 two possible variants

  • Using the setSelect method
  • Setting editoptions dataUrl parameter

The method setSelect will be considered later (link)

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.
The corresponding script cam look like this:

...
$grid->setColProperty('somename',array('edittype'=>'select','editoptions'=>array('dataUrl'=>'some_url')));
...

Multiple selection of options in a select box is also possible. Also the size attribute can be added too

...
$grid->setColProperty('somename',array('edittype'=>'select','editoptions'=>array("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"=>array("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"=>array("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"=>array("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"=>array("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 allow definition of custom editable element. When edit type is set to custom we should provide a set of functions which should to create the element, and get the value from it in order to be posted to the server.
Functions that should be defined:

1. custom_element - 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.
2. custom_value - 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

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.

See example on how to construct custom element


editoptions property is array which contain important information about the editing column. It is important to note that in editoptins array you can set any valid attribute for the chosen edittype.

Below is the list of 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"=>array("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"=>array("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 the elements of type select - i.e., edittype:select and should represent the url for getting the data that should contain the select definition. The data is obtained via ajax call and should be a valid html select element with the desired options <select><option value='1'>One</option>…</select>. In this case you can use option group.
The ajax request is called only once when the element is created.
In inline edit or cell edit module it is called every time when you edit a new row or cell. In form edit module only once.

buildSelect

function

This option have sense only if the dataUrl parameter is set. In case where the server response can not build the select element you can use your on 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. This function should be created like this "editoptions"=>array("buildSelect"=>"js:function(response){...}",..)

dataInit

function

To this function, if defined, we pass the element object. This function is called only once when the element is created. The event is called only once when the element is created.
In inline edit or cell edit module it is called every time when you edit a new row or cell. In form edit module only once.

dataEvents

array

list of events to apply to the data element; uses jQuery bind like $(”#id”).bind(type, [data], fn) to bind events to data element.

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.

other options

mixed

In this case you can set any other valid attribute for the editable element. By Example if the element is edittype:'text' we can set size, maxlenght and etc. attributes. Refer to the valid attributes of of the element


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:

<?php
....
$grid->setColModel(...);
$grid->setColProperty('somefield',array("editable"=>true, "editrules"=>array("edithidden"=>true, "required"=>true...), ..));
...

$grid->renderGrid(...);
...
?>

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.

email

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”]

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: 

<?php
....
$grid->setColModel(...);
$grid->setColProperty('somefield',array("editable"=>true, "formoptions"=>array("elmprefix"=>"(*)", "rowpos"=>1, "colpos"=>2), ..));
...

$grid->renderGrid(...);
...
?>

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

Two elements can have equal row position, but different column position. This will place the two elements in one row on the form.