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

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

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

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:

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