【JQGRID DOCUMENTATION】.学习笔记.6.Editing:Common Rules

1 公共编辑属性

要在grid中显示数据的一个关键原因是能简单快速地编辑它。jgGrid提供三种编辑方式：

1. cell editing：编辑指定cell
2. inline editing：编辑同一行的几个cells
3. form editing：在grid外面创建一个form来编辑

2 安装

在Download Manager中，每个编辑模块有它自己的描述，但是他们都使用了必选的公共模块，它就是grid.common.js。

3 选项和描述

所有的编辑模块，为了执行编辑，都在colModel中使用公共属性。下面的几个属性：

• editable
• edittype
• editoptions
• editrules
• formoptions（只在form editing有效）

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

3.1 editable

这个选项是布尔型，它定义字段是否可以编辑。默认是false。隐藏字段不可编辑。在in-line和cell编辑组件，为了编辑它，可以使用showCol方法显示这些字段。而在form editing模块中，需要使用editrules选项。

3.2 edittype

Edittype选项定义了可编辑字段的类型。可用的值有：text,textarea,select,checkbox,password,button,image,file,custom。默认值时text。

3.2.1 text

当 edittype是text时，jqGrid构建一个类型为text的input标签

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

这时，在editoptions中，可以为这个字段设置所有可用的属性

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

附加了这些设置后，jqGrid会为它添加id和name属性

3.2.2 textarea

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

在editoptions中，我们可以添加附加的属性，一般会设置box的尺寸

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

这样的话，jqGrid会为它添加id和name属性

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

3.2.3 checkbox

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

editoptions用来定义选中或未选中的值。第一个值被选中

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

这样会构建一个

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

定义一个checkbox：当值是true时，checkbox被选中。这个值会作为参数传递给editurl。如果在editoptions中，没有设置value属性，jqGrid为了构建checkbox，会搜索以下值（false|0|no|off|undefined）。如果cell中没有包含这些值中的一个，value属性会变成cell的内容，offval会设为off。例如cell的内容是true时：

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

jqGrid会添加id和name属性

3.2.4 select

</select>

要构建这个元素，偶们有三个可能的变量：

3.2.4.1 将editoptions的值作为string

Editoptions的值必须包含一组value:label pairs

</select>

3.2.4.2 将editoptions的值作为object

Editoptions的value必须包含一个name:value属性的数组。

</select>

3.2.4.3 设置editoptions的dataUrl参数

Editoptions dataUrl参数只有在edittype: select时可用。dataUrl参数代表得到选项的地址。当选项设置后，元素会以AJAX请求来的值填充。

也可以使用多选，

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

3.2.5 password

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

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

jqGrid会添加id和name属性

3.2.6 button

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

为了附加这些设置，jqGrid会添加id和name属性

3.2.7 image

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

为了附加这些设置，jqGrid会添加id和name属性

3.2.8 file

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

为了附加这些设置，jqGrid会添加id和name属性

3.2.9 custom

编辑类型允许定义一个自定义的可编辑元素。此时，需要提供一组功能：以个是创建元素的，一个是为了发送数据到服务器，get和set表单中的值。

功能应该被定义为custom_element和custom_value。

当自定义元素被创建，我们自动添加下面的附加任务：

1. 添加”customelement”的class
2. 用colModel中的name，添加属性名
3. 为每个编辑模块添加相应的规则

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(); } elseif(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>

3.3 editoptions

Editoptions属性是一个数组，包含编辑列的信息。下面是最常用的选项：

Property	Type	Description
value	mixed	当edittype为checkbox时，value是{value:”Yes:No”} 当edittype为select时，value可是一字符串:{value:”1: one;2: Two”}，对象:{value:{1:”one”;2:”Two”}}，函数:必须格式必须是string或object。
dataUrl	string	只有在edittype:select时这个选项才可用，这个URL是为select元素加载AJAX数据。AJAX请求只有在元素创建时被调用一次。在inline或cell编辑模块中，每次编辑新行或新cell，都会调用。在form编辑模式只有一次。
buildSelect	function	这个选项只有dataUrl参数设置时才有用。当多个相应不能构建select元素，你可以使用自己的函数，构建select。函数应该返回一个包含select和option的字符串。
dataInit	function	我们传递元素对象到这个函数。它只有在元素创建时调用一次。例如 editoptions: { dataInit : function (elem) { $(elem).autocomplete(); } } 事件只有在元素被创建时被调用一次。在inline或cell编辑模块中，在每次编辑新行或新cell时都会调用。在form编辑模块中，如果recreateForm选项设为false，它只调用一次。
dataEvents	array	列出应用在data element上的事件：使用$(“#id”).bind(type,[data],fn)来绑定事件到数据元素。应该被这样描述： 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	这个选项可以是字符串或函数。它只有在form编辑模块使用editGridRow方法作为add的方式时才可用。如果用在select控件上，必须提供text，它会使用text而不是key。当使用函数时，应该返回一个值
NullIfEmpty	boolean	如果设为true，字段中的数据为空时，返回服务器’null’
custom_element	function	只有在edittype选项为custom时可用。这个函数用来创建元素，它必须返回一个新的DOM元素。传递给该函数的参数，是colModel中的value和选项。
custom_value	function	只有在edittype选项设为custom时可用。 在元素被编辑后，函数会返回该元素的值，post给服务器。传递给该函数的参数，是元素对象和get参数（inline和cell编辑模块中）。 在form编辑模块，这个函数有一些不同的行为。有第三个参数——value。当自定义元素的values post给服务器，第二个参数是’get’。这种情况下，函数会返回一个value。如果没有值返回，是error
other options	mixed	你可以设置任何可用的属性给可编辑元素。例如，如果元素的edittype:text，我们可以设置size，maxlength。

3.4 editrules

这个选项用来为可编辑元素，在colModel中添加附加的属性。它总是用来在提交服务器前，验证用户输入的值。

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

下面是可用选项的列表：

Option	Type	Description
edithidden	boolean	这个选项只有在form editing模块才有效。默认隐藏字段不能被编辑。如果grid中的隐藏字段edithidden设为true，当添加或编辑方法被调用时，字段可以被编辑
required	boolean	(true or false)如果设为true，会检查该值，如果是空的，一条错误消息会显示
number	boolean	(true or false)如果设为true，会检查该值，如果不是一个数字，一条错误消息会显示
integer	boolean	(true or false)如果设为true，会检查该值，如果不是一个integer，一条错误消息会显示
minValue	number(integer)	如果设置，会检查该值，如果值小于，一条错误消息
maxValue	number(integer)	如果设置，会检查该值，如果值大于，一条错误消息
email	boolean	如果设为true，会检查该值，如果不是可用e-mail，一条错误消息
url	boolean	如果设为true，会检查该值，如果不是可用url，一条错误消息
date	boolean	如果设为true，会以datefmt选项的格式得到日期（如果没有设置，则用ISO date格式），会检查该值，如果不是可用date，一条错误消息
time	boolean	如果设为true，会检查该值，如果不是可用time，一条错误消息会显示。当前只支持hh:mm格式，并且以am/pm结尾
custom	boolean	如果设为true，允许通过一个自定义函数，定义检查规则
custom_func	function	只有在custom设为true时可用。colModel中要检查的value会作为参数传递给这个函数。函数必须返回以下参数的数组：第一个参数——true or false。这个值为true，意味着检查通过。第二个参数是在第一个参数为false时，播放给用户的错误消息。经典的格式如下 [false,”Please enter valid value”]

3.4.1 自定义检查例子

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>

3.5 formoptions

这个选项只有在form editing模块可用。这个选项的目的，是在表单中记录元素，并在编辑元素前面或后面添加一些信息。必须用在colModel数组中。

jQuery("#grid_id").jqGrid({
...
colModel: [
...
{name:'price', ..., formoptions:{elmprefix:'(*)', rowpos:1, colpos:2....}, editable:true },
...
]
...
});
</script>

如果计划在colModel中使用rowpos和colpos属性，它会记录所有带有这个属性的正在编辑的字段

Option	Type	Description
elmprefix	string	如果设置了，一个text或html内容会出现在input元素前
elmsuffix	string	如果设置了，一个text或html内容会出现在input元素后
label	string	如果设置了，它会替换colName数组中，显示在表单label中的name
rowpos	number	指明表单中元素的行位置。从1开始
colpos	number	指明表单中，元素的列位置。从1开始

两个元素可以有相同的行位置，但不同的列位置。这样会在表单的同一行放置两个元素。