jqGrid通用编辑规则
一个将数据显示在grid中主要的原因是为了快速容易的编辑它，jqGrid支持3种编辑方法
- jqGrid单元格编辑配置，事件及方法:：编辑表格中的单元格
- jqGrid行编辑配置：同时编辑一行中的多个单元格
- jqGrid表单编辑配置：在grid外部的表单中编辑数据行
安装
在下载管理中每个模块有它自己的要求，但是不管哪个模块，都要勾选通用模块（common module）。下载地址：http://www.trirand.com/blog/?page_id=6 开发者可以从src目录中找到grid.common.js源文件。
选项和描述
所有编辑模块需要在colModel中配置通用编辑属性以便启用编辑，下面列出的属性是需要详细介绍的
- editable
- edittype
- editoptions
- editrules
- formoptions（仅在表单编辑模式有效）
通用配置语法如下
JavaScript代码对于特定的选项和事件请参阅对应的模块。对每个模块jqGrid为每个可编辑的元素配置不同的name和id，参考对应的编辑模块看如何构造。
editable
布尔值，true或者false。定义此字段是否能编辑，默认为false不可编辑，要使字段可以编辑，设置为 editable:true。
需要注意的是隐藏字段（hidden fields）默认不能编辑；如果隐藏字段被标记为可编辑的，在行编辑和单元格编辑模块需要显示这些字段（使用showCol方法），才能进行编辑。在表单编辑模块中需要使用editrules选项（下面将介绍到）
edittype
定义可编辑字段的输入控件类型。可用值： 'text', 'textarea', 'select', 'checkbox', 'password', 'button', 'image', 'file' 和'custom'，默认值为'text'.
text
edittype设置为text，jqGrid将会构造一个type为text的input标签
使用 editoptions ，可以定义此字段对应输入控件需要的属性，例如
JavaScript代码输入控件HTML结构如下
JavaScript代码jqGrid会自动给此配置添加id和name属性。
textarea
edittype设置为textarea，jqGrid将会构造一个textarea标签
JavaScript代码使用 editoptions ，可以定义此字段对应输入控件需要的属性，例如（注意添加rows）
JavaScript代码对应的HTML结构
JavaScript代码jqGrid会自动给此配置添加id和name属性。
checkbox
edittype设置为checkbox，jqGrid将会构造一个type为checkbox的input标签
使用 editoptions ，主要用于定义勾选或者未勾选时的值，例如
JavaScript代码输入控件HTML结构如下
当value为yes，checkbox被勾选，否则未勾选。值将会作为参数传递到jqGrid配置的editurl中。
editoptions中如果未设置value属性，jqGrid将会查找如下的值（false|0|no|off|undefined）以便构造checkbox。如果单元格内容都不包含这些值，那么属性值变为单元格的内容offval属性值设置为off。
示例，单元格内容为true
jqGrid会自动给此配置添加id和name属性。
select
edittype设置为select，jqGrid将会构造一个如下所示的select标签
<option value='val1'> Value1 </option>
<option value='val2'> Value2 </option>
...
<option value='valn'> ValueN </option>
</select>
要配置select对象，有3个主要的类型
1. editoptions配置中的 value为字符 。editoptions 的value需要包含一组 “值:标签”用分号（;）分隔开，如下所示
JavaScript代码上面的代码将会得到如下html代码
<option value='FE'> FedEx </option>
<option value='IN'> InTime </option>
<option value='TN'> TNT </option>
</select>
最后一组“值:标”不要以分号(;)结束
2. editoptions配置中的 value为对象
value配置需要包含json键值对对象，如下所示
JavaScript代码
对应的HTML结构
<option value='1'>One</option>
<option value='2'>Two</option>
</select>
3. 设置 editoptions配置 dataUrl 参数。 editoptions 中的dataUrl配置仅对editype:select有效。dataUrl表示从 配置的url中获取select元素的html代码。当配置了dataUrl，通过ajax获取html代码对元素进行填充，返回的html需要是一个有效的select元素html代码，如下所示
<option value='1'>One</option>
<option value='2'>Two</option>
...
</select>
上面三种方法配置的select元素，jqGrid会自动给元素添加id和name属性。
也可以设置select对象为多选的，需要设置size和multiple2个属性，如下所示
JavaScript代码password
edittype设置为password，jqGrid将会构造一个type为password的input标签
使用 editoptions ，可以定义此字段对应输入控件需要的属性，例如
JavaScript代码输入控件HTML结构如下
jqGrid会自动给此配置添加id和name属性。
button
edittype设置为text，jqGrid将会构造一个type为button的input标签
使用 editoptions ，可以定义此字段对应输入控件需要的属性，例如
对应的HTML结构
jqGrid会自动给此配置添加id和name属性。
image
edittype设置为image，jqGrid将会构造一个type为image的input标签
使用 editoptions ，可以定义此字段对应输入控件需要的属性，例如
JavaScript代码输入控件HTML结构如下
jqGrid会自动给此配置添加id和name属性。
file
edittype设置为file，jqGrid将会构造一个type为filet的input标签
使用 editoptions ，可以定义此字段对应输入控件需要的属性，例如
JavaScript代码输入控件HTML结构如下
jqGrid会自动给此配置添加id和name属性。如果创建了这个元素（一般使用表单编辑模式），表单不会为了上传文件增加ENCTYPE=“multipart/form-data"，需要倒入另外的插件来完成上传- Ajax File Upload 插件就是一个很不错的选择
custom
这个编辑类型允许自定义可编辑的元素。edittype设置为custom后，再editoptions中需要配置2个函数，一个创建元素，另外一个负责在表单中设置和获取值，以便提交到服务器。这2个方法需要被定义为custom_element 和 custom_value. 看下面的editoptions获取更多信息。
当自定义元素创建后jqGrid会自动执行下面附加的任务
- 添加 'customelement'样式
- 添加name属性，对应colModel中定义的name值
- 按照使用的编辑类型对应的id生成规则，给元素添加id
如上面示例所示的创建edittype为text，设置edittype为custom对应的代码
JavaScript代码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} },
//...
]
//...
});
editoptions
editoptions配置为JSON键值对对象包含编辑列的相关信息。edittype设置为什么，对应的editoptions可以设置为什么，这个需要知道，下面列出的每个配置对edittype设置的元素不一定都有效。colModel中的editoptions使用配置语法如下，为JSON键值对
<scrJavaScript代码//...
colModel: [
//...
{name:'price', ..., editoptions:{name1:value1...}, editable:true },
//...
]
//...
});
下面为一些比较常用的选项
| 配置名称 | 类型 | 描述 |
|---|---|---|
| value | mixed |
|
| dataUrl | string | 仅对editype:select有效。dataUrl表示从 配置的url中获取select元素的html代码。当配置了dataUrl，通过ajax获取html代码对元素进行填充，返回的html需要是一个有效的select元素html代码，例如
<select>
<option value='1'>One</option> <option value='2'>Two</option> ... </select> |
| buildSelect | function | 仅当dataUrl设置有效，配置这个可以使用自定义函数来创建select。函数需要返回字有效的select html字符串，如dataUrl描述的一样。函数参数为服务器响应内容 |
| dataInit | function | 定义了函数，函数参数为创建的元素对象。元素创建后调用一次。例如
－收缩
JavaScript代码…editoptions: { dataInit : function (elem) {
$(elem).autocomplete(); } } 行编辑或者单元格编辑模式每次都会被调用当编辑新行或者单元格时，表单编辑模式下，recreateForm设置为false，仅调用一次，recreateForm设置为true则每次都会调用。. |
| dataEvents | array | 需要绑定到元素的事件列表，示例如下
－收缩
JavaScript代码… 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 | 值可以配置为string或者函数。此配置仅当在表单编辑模式，调用editGridRow方法添加数据时有效。输入元素的值被设置为配置值。如果是select元素，则提供的是显示的文本而非键（ If used in selects the text should be provided and not the key）。配置为function时需要返回内容值。 |
| NullIfEmpty | boolean | 配置为true，但字段内容为空时将会发送字符串 'null' 到服务器。 |
| custom_element | function | 仅对edittype 设置为'custom'有效。此方法用于创建元素，返回创建后的DOM元素对象。函数参数为editoptions配置的value，colModel配置的editoptions对象（Parameters passed to this function are the value and the editoptions from colModel）。【PS：感觉value有点多余，因为value原本就包含在editoptions里面，单独分离出来为了方便访问？还是我理解错了？） |
| custom_value | function | 仅对edittype 设置为'custom'有效。函数需要返回元素被编辑后的值，以便提交到服务器。或者设置输入元素的值。 函数第一个参数为元素对象，第二个参数为字符串类型的参数，对于行编辑和单元格编辑，内容为“get“。下面列出其他类型的值。 如果为表单编辑模式，这个函数有不同的行为。此函数有第三个参数，元素的值。 当要提交自定义元素的值时，第二个参数为”get”，因此函数需要返回元素的值。如果没有返回值将会抛出异常错误。 当从grid中读取数据设置表单，第二个参数为“set"，第三个参数为读取的内容，用于设置元素的值。这样在表单显示内容前，修改从grid读取的值，参考上面的示例 |
| other options | mixed | 可以设置编辑元素的所有可用DOM属性，例如，edittype为text，可以设置size，maxlength等属性 |
editrules
这个选择添加附加的属性到可编辑元素，在colModel中 配置。通常用于在提交内容到服务器前验证用户输入的信息。demo
JavaScript代码...
colModel: [
...
{name:'price', ..., editrules:{edithidden:true, required:true....}, editable:true },
...
]
...
});
下面为可用的选项
| 配置名称 | 类型 | 描述 |
|---|---|---|
| edithidden | boolean | 仅在表单编辑模块有效。默认隐藏字段无法编辑。设置为true时，隐藏字段在添加和修改方法被调用时呈现出来，可以编辑 |
| required | boolean | (true or false) 设置为true，不允许内容为空，为空将会显示一个错误信息。 |
| number | boolean | (true or false) 设置为true，输入内容只能为数字，否则将会显示一个错误信息。 |
| integer | boolean | (true or false)设 置为true，输入内容只能为整数，否则将会显示一个错误信息。 |
| minValue | number(integer) | 最小值，如果内容小于这个配置值，将会显示错误信息。 |
| maxValue | number(integer) | 最大值，如果内容大于这个配置值，将会显示错误信息。 |
| boolean | 设置为true，输入内容格式需要满足email格式要求，否则将会显示一个错误信息。 | |
| url | boolean | 设置为true，输入内容格式需要满足url格式要求，否则将会显示一个错误信息。 |
| date | boolean | 设置为true，输入内容格式需要满足日期格式要求（使用ISO格式，”Y-m-d“），否则将会显示一个错误信息。 |
| time | boolean | 设置为true，输入内容格式需要满足时间格式要求，否则将会显示一个错误信息。 目前仅支持”hh:mm“和后接可选的 am/pm 时间格式 |
| custom | boolean | 设置为true，允许使用自定义的验证方法，如下 |
| custom_func | function | custom设置为true时需要配置此函数。函数参数，输入控件的值，name名称（来自colModel）。 函数需要返回一个数组包含以下项目 第一项：true/false，指定验证是否成功 第二项：当第一项为false有效，显示给用户的错误信息。 格式如：[false,”Please enter valid value”] |
自定义验证示例
JavaScript代码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 },
//...
]
//...
});
formoptions
仅在表单编辑有效。目的是记录表中的元素并且附加一些信息在编辑元素的前面或者后面。语法如下
JavaScript代码//...
colModel: [
//...
{name:'price', ..., formoptions:{elmprefix:'(*)', rowpos:1, colpos:2....}, editable:true },
//...
]
//...
});
如果colModel中要使用rowpos和colpos配置，那么建议所有可编辑的字段使用这些配置
下面为可用的选项
| 配置名称 | 类型 | 描述 |
|---|---|---|
| elmprefix | string | 在输入元素前显示的内容（内容可以为html格式的字符串） |
| elmsuffix | string | 在输入元素后显示的内容（内容可以为html格式的字符串） |
| label | string | 替换jqGrid配置colNames数组中定义的标签作为表单输入项的标签说明内容 |
| rowpos | number | 定义元素所在行处于表单中位置，从1开始 |
| colpos | number | 定义元素所在列处于表单中位置，从1开始 |
2个元素可以有相同的行位置，但是不同的列位置，这样这2个元素在表单中共处一行。
