====== 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:
<code javascript>
<script>
jQuery("#grid_id").jqGrid({
...
   colModel: [ 
      ... 
      {name:'price', ..., editable:true, edittype:'text', editoptions:{...}, editrules:{...}, formoptions:{...} },
      ...
   ]
...
});
</script>
</code>
For all other specific options and events refer to the appropriate module.

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

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

<code html>
<input type="text" ...../>
</code>

In //editoptions// we can set all the possible attributes for this field. For example,

<code javascript>
... editoptions: {size:10, maxlength: 15}
</code>

will cause jqGrid to construct the following input

<code html>
<input type="text" size="10" maxlength="15" />
</code>
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

<code html>
<input type="textarea" .../>
</code>

In //editoptions// we can add additional attributes to this type. Typically, these govern the size of the box:

<code javascript>
... editoptions: {rows:"2",cols:"10"}
</code>

<code html>
<input type="textarea" rows="2" cols="10".../>
</code>


To these attributes jqGrid adds id and name attributes .

=== checkbox ===


When edittype is 'checkbox', jqGrid constructs a input tag as follows:

<code html>
<input type="checkbox" .../>
</code>

//editoptions// is used to define the checked and unchecked values. The first value is checked. For example

<code javascript>
...editoptions: { value:"Yes:No" }
</code>

This will construct
<code html>
<input type="checkbox" value="Yes" offval="No".../>
</code>

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
<code html>
<input type="checkbox" value="true" offval="off" checked.../>
</code>


To these attributes jqGrid adds id and name attributes.

=== select ===
When edittype is 'select', jqGrid constructs a input tag as follows:
<code html>
<select> 
<option value='val1'> Value1 </option> 
<option value='val2'> Value2 </option> 
... 
<option value='valn'> ValueN </option> 
</select>
</code>

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
<code html>
<select> 
<option value='FE'> FedEx </option> 
<option value='IN'> InTime </option> 
<option value='TN'> TNT </option> 
</select>
</code>

<note>Note the last element in the string - it should not end with ;</note>

**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:
<code javascript>
...
colModel : [
      ...
    {name:'myname', edittype:'select', editoptions:{value:{1:'One',2:'Two'}} },
      ...
]
...
</code>

This will construct an HTML select 
<code html>
<select> 
<option value='1'>One</option> 
<option value='2'>Two</option> 
</select>
</code>


**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:
<code html>
<select> 
<option value='1'>One</option> 
<option value='2'>Two</option> 
...
</select>
</code>



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

<code html>
...editoptions: {multiple:true, size:3... }
</code>

=== password ===

When edittype is 'password', jqGrid constructs a input tag of type text:

<code html>
<input type="password" ...../>
</code>

In //editoptions// we can set all the possible attributes for this field. For example,

<code javascript>
... editoptions: {size:10, maxlength: 8}
</code>

will cause jqGrid to construct the following input

<code html>
<input type="password" size="10" maxlength="8" />
</code>
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:

<code html>
<input type="button" ...../>
</code>

In //editoptions// we can set all the possible attributes for this field. For example,

<code javascript>
... editoptions: {value:'MyButton'}
</code>

will cause jqGrid to construct the following input

<code html>
<input type="button" value="MyButton" />
</code>
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:

<code html>
<input type="image" ...../>
</code>

In //editoptions// we can set all the possible attributes for this field. For example,

<code javascript>
... editoptions: {src:'path_to_my_image'}
</code>

will cause jqGrid to construct the following input

<code html>
<input type="image" src="path_to_my_image" />
</code>
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:

<code html>
<input type="file" ...../>
</code>

In //editoptions// we can set all the possible attributes for this field. For example,

<code javascript>
... editoptions: {alt:'Alt text'}
</code>

will cause jqGrid to construct the following input

<code html>
<input type="file" alt="Alt text"... />
</code>
In addition to the these settings, jqGrid adds the id and name attribute.
<note important>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.</note>

=== 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:
<code javascript>
<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>
</code>


==== 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:
<code javascript>
<script>
jQuery("#grid_id").jqGrid({
...
   colModel: [ 
      ... 
      {name:'price', ..., editoptions:{name1:value1...}, editable:true },
      ...
   ]
...
});
</script>
</code>

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 . <del>In the form edit module only once</del>.|
|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 . \\ <del><color red>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)</color></del>|
|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:

<code javascript>
<script>
jQuery("#grid_id").jqGrid({
...
   colModel: [ 
      ... 
      {name:'price', ..., editrules:{edithidden:true, required:true....}, editable:true },
      ...
   ]
...
});
</script>
</code>

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

=== Custom Checking example===
<code javascript>
<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>
</code>


==== 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:
<code javascript>
<script>
jQuery("#grid_id").jqGrid({
...
   colModel: [ 
      ... 
      {name:'price', ..., formoptions:{elmprefix:'(*)', rowpos:1, colpos:2....}, editable:true },
      ...
   ]
...
});
</script>
</code>

<note>If you plan to use this object in collModel with rowpos and colpos properties it is recommended that all editing fields use these properties.</note>

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 |

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