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

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.

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.

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 false. To make a field editable, set this to true: editable:true.
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'.

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.

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 .

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 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 .

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

• Setting 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>

• Seting editoptions value as object

In this case the editoptions value must contain array {} with name value property. Below is example:

...
colModel : [
      ...
    {name:'myname', edittype:'select', editoptions:{value:{1:'One',2:'Two'}} },
      ...
]
...

This will construct select

<select> 
<option value='1'>One</option> 
<option value='2'>Two</option> 
</select>

• Setting 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. Also the size attribute can be added too

...editoptions: {multiple:true, size:3... }

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.

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.

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.

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.

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 the value from the form in order to be posted to the server.
The 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.

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) {
  return $(elem).val();
}
jQuery("#grid_id").jqGrid({
...
   colModel: [ 
      ... 
      {name:'price', ..., editable:true, edittype:'custom', editoptions:{custom_element: myelem, custom_value:myvalue} },
      ...
   ]
...
});
</script>

The editoptions property is an array which contains important information about the editing column. It is important to note that in the editoptions array you can set any valid attribute for the chosen edittype.
The editoptions property is used in 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 most commonly used options:

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:

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

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