jqGrid通用编辑规则

一个将数据显示在grid中主要的原因是为了快速容易的编辑它，jqGrid支持3种编辑方法

1. jqGrid单元格编辑配置，事件及方法:：编辑表格中的单元格
2. jqGrid行编辑配置：同时编辑一行中的多个单元格
3. jqGrid表单编辑配置：在grid外部的表单中编辑数据行

安装

在下载管理中每个模块有它自己的要求，但是不管哪个模块，都要勾选通用模块（common module）。下载地址：http://www.trirand.com/blog/?page_id=6 开发者可以从src目录中找到grid.common.js源文件。

选项和描述

　　所有编辑模块需要在colModel中配置通用编辑属性以便启用编辑，下面列出的属性是需要详细介绍的

• editable
• edittype
• editoptions
• editrules
• formoptions（仅在表单编辑模式有效）

通用配置语法如下

－收缩JavaScript代码

jQuery("#grid_id").jqGrid({ ... colModel: [ ... {name:'price', ..., editable:true, edittype:'text', editoptions:{...}, editrules:{...}, formoptions:{...} }, ... ] ... }); 

　　对于特定的选项和事件请参阅对应的模块。对每个模块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标签

－收缩HTML代码　　运行代码　　[如果运行无效果，请自行将源代码保存为html文件运行]

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

使用 editoptions ，可以定义此字段对应输入控件需要的属性，例如

－收缩JavaScript代码

... editoptions: {size:10, maxlength: 15}

输入控件HTML结构如下

－收缩JavaScript代码

<input type="text" size="10" maxlength="15" />

jqGrid会自动给此配置添加id和name属性。

textarea

edittype设置为textarea，jqGrid将会构造一个textarea标签

－收缩JavaScript代码

<textarea></textarea>

使用 editoptions ，可以定义此字段对应输入控件需要的属性，例如（注意添加rows）

－收缩JavaScript代码

... editoptions: {rows:"2",cols:"10"} 

对应的HTML结构

－收缩JavaScript代码

<textarea type="textarea" rows="2" cols="10"></textarea>

jqGrid会自动给此配置添加id和name属性。

checkbox

edittype设置为checkbox，jqGrid将会构造一个type为checkbox的input标签

－收缩HTML代码　　运行代码　　[如果运行无效果，请自行将源代码保存为html文件运行]

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

使用 editoptions ，主要用于定义勾选或者未勾选时的值，例如

－收缩JavaScript代码

...editoptions: { value:"Yes:No" }

输入控件HTML结构如下

－收缩HTML代码　　运行代码　　[如果运行无效果，请自行将源代码保存为html文件运行]

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

当value为yes，checkbox被勾选，否则未勾选。值将会作为参数传递到jqGrid配置的editurl中。

editoptions中如果未设置value属性，jqGrid将会查找如下的值（false|0|no|off|undefined）以便构造checkbox。如果单元格内容都不包含这些值，那么属性值变为单元格的内容offval属性值设置为off。

示例，单元格内容为true

－收缩HTML代码　　运行代码　　[如果运行无效果，请自行将源代码保存为html文件运行]

<input type="checkbox" value="true" offval="off" checked.../>

jqGrid会自动给此配置添加id和name属性。

select

edittype设置为select，jqGrid将会构造一个如下所示的select标签

－收缩HTML代码　　运行代码　　[如果运行无效果，请自行将源代码保存为html文件运行]

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

editoptions: { value: “FE:FedEx; IN:InTime; TN:TNT” }

上面的代码将会得到如下html代码

－收缩HTML代码　　运行代码　　[如果运行无效果，请自行将源代码保存为html文件运行]

<select> 
<option value='FE'> FedEx </option> 
<option value='IN'> InTime </option> 
<option value='TN'> TNT </option> 
</select>

最后一组“值:标”不要以分号(;)结束

2. editoptions配置中的 value为对象

value配置需要包含json键值对对象，如下所示

－收缩JavaScript代码

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

对应的HTML结构

－收缩HTML代码　　运行代码　　[如果运行无效果，请自行将源代码保存为html文件运行]

<select> 
<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代码，如下所示

－收缩HTML代码　　运行代码　　[如果运行无效果，请自行将源代码保存为html文件运行]

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

上面三种方法配置的select元素，jqGrid会自动给元素添加id和name属性。

也可以设置select对象为多选的，需要设置size和multiple2个属性，如下所示

－收缩JavaScript代码

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

password

edittype设置为password，jqGrid将会构造一个type为password的input标签

－收缩HTML代码　　运行代码　　[如果运行无效果，请自行将源代码保存为html文件运行]

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

使用 editoptions ，可以定义此字段对应输入控件需要的属性，例如

－收缩JavaScript代码

... editoptions: {size:10, maxlength: 8}

输入控件HTML结构如下

－收缩HTML代码　　运行代码　　[如果运行无效果，请自行将源代码保存为html文件运行]

<input type="password" size="10" maxlength="8" />

jqGrid会自动给此配置添加id和name属性。

button

edittype设置为text，jqGrid将会构造一个type为button的input标签

－收缩HTML代码　　运行代码　　[如果运行无效果，请自行将源代码保存为html文件运行]

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

使用 editoptions ，可以定义此字段对应输入控件需要的属性，例如

－收缩HTML代码　　运行代码　　[如果运行无效果，请自行将源代码保存为html文件运行]

... editoptions: {value:'MyButton'}

对应的HTML结构

－收缩HTML代码　　运行代码　　[如果运行无效果，请自行将源代码保存为html文件运行]

<input type="button" value="MyButton" />

jqGrid会自动给此配置添加id和name属性。

image

edittype设置为image，jqGrid将会构造一个type为image的input标签

－收缩HTML代码　　运行代码　　[如果运行无效果，请自行将源代码保存为html文件运行]

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

使用 editoptions ，可以定义此字段对应输入控件需要的属性，例如

－收缩JavaScript代码

... editoptions: {src:'path_to_my_image'}

输入控件HTML结构如下

－收缩HTML代码　　运行代码　　[如果运行无效果，请自行将源代码保存为html文件运行]

<input type="image" src="path_to_my_image" />

jqGrid会自动给此配置添加id和name属性。

file

edittype设置为file，jqGrid将会构造一个type为filet的input标签

－收缩HTML代码　　运行代码　　[如果运行无效果，请自行将源代码保存为html文件运行]

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

使用 editoptions ，可以定义此字段对应输入控件需要的属性，例如

－收缩JavaScript代码

... editoptions: {alt:'Alt text'}

输入控件HTML结构如下

－收缩HTML代码　　运行代码　　[如果运行无效果，请自行将源代码保存为html文件运行]

<input type="file" alt="Alt text"... />

jqGrid会自动给此配置添加id和name属性。如果创建了这个元素（一般使用表单编辑模式），表单不会为了上传文件增加ENCTYPE=“multipart/form-data"，需要倒入另外的插件来完成上传- Ajax File Upload 插件就是一个很不错的选择

custom

这个编辑类型允许自定义可编辑的元素。edittype设置为custom后，再editoptions中需要配置2个函数，一个创建元素，另外一个负责在表单中设置和获取值，以便提交到服务器。这2个方法需要被定义为custom_element 和 custom_value. 看下面的editoptions获取更多信息。

当自定义元素创建后jqGrid会自动执行下面附加的任务

1. 添加 'customelement'样式
2. 添加name属性，对应colModel中定义的name值
3. 按照使用的编辑类型对应的id生成规则，给元素添加id

如上面示例所示的创建edittype为text，设置edittype为custom对应的代码

－收缩JavaScript代码

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} },
     //...
   ]
//...
});

editoptions

editoptions配置为JSON键值对对象包含编辑列的相关信息。edittype设置为什么，对应的editoptions可以设置为什么，这个需要知道，下面列出的每个配置对edittype设置的元素不一定都有效。colModel中的editoptions使用配置语法如下，为JSON键值对

<scr

－收缩JavaScript代码

jQuery("#grid_id").jqGrid({
//...
   colModel: [ 
     //...
      {name:'price', ..., editoptions:{name1:value1...}, editable:true },
      //...
   ]
//...
});

下面为一些比较常用的选项

配置名称	类型	描述
value	mixed	edittype为checkbox时，为一个字符串包含2个值，用英文状态下的冒号（:）分开。例如{value:“Yes:No”}，冒号前的值决定复选框是否选中 edittype为select时，可以为字符串，对象或者函数。 1）为字符串，需要包含一组 “值:标签”用分号（;）分隔开，字符串结尾不能为分号（;）。 2）为对象，则为json键值对对象，如editoptions:{value:“1:One;2:Two”} 3）定义为函数，则函数需要返回上面2种格式的数据。 edittype为其他类型时，value为输入元素的值。
dataUrl	string	仅对editype:select有效。dataUrl表示从 配置的url中获取select元素的html代码。当配置了dataUrl，通过ajax获取html代码对元素进行填充，返回的html需要是一个有效的select元素html代码，例如 －收缩HTML代码　　运行代码　　[如果运行无效果，请自行将源代码保存为html文件运行] <select> <option value='1'>One</option> <option value='2'>Two</option> ... </select> ajax请求仅在元素被创建后调用一次。在行编辑或者单元格编辑模块下，编辑新行或者新单元格都会被调用，表单编辑模块仅调用一次。
buildSelect	function	仅当dataUrl设置有效，配置这个可以使用自定义函数来创建select。函数需要返回字有效的select html字符串，如dataUrl描述的一样。函数参数为服务器响应内容
dataInit	function	定义了函数，函数参数为创建的元素对象。元素创建后调用一次。例如 －收缩JavaScript代码 …editoptions: { dataInit : function (elem) { $(elem).autocomplete(); } }  行编辑或者单元格编辑模式每次都会被调用当编辑新行或者单元格时，表单编辑模式下，recreateForm设置为false，仅调用一次，recreateForm设置为true则每次都会调用。. 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) 注意：一些插件需要用到元素在DOM中位置，而这个事件在元素插入到DOM前已经触发。要实现这个动作，可以使用setTimeout函数来延时执行。特别对jQuery UI datepicker（1.7.x+版本）有效
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代码

jQuery("#grid_id").jqGrid({
...
   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)	最大值，如果内容大于这个配置值，将会显示错误信息。
email	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代码

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 },
      //...
   ]
//...
});

formoptions

仅在表单编辑有效。目的是记录表中的元素并且附加一些信息在编辑元素的前面或者后面。语法如下

－收缩JavaScript代码

jQuery("#grid_id").jqGrid({
//...
   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个元素在表单中共处一行。