【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有效）

1 < script > 2 jQuery( " #grid_id " ).jqGrid({ 3 ... 4 colModel: [ 5 ... 6 {name: ' price ' , ..., editable: true , edittype: ' text ' , editoptions:{...}, editrules:{...}, formoptions:{...} }, 7 ... 8 ] 9 ... 10 }); 11 </ 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标签

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

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

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

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

3.2.2 textarea

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

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

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

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

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

3.2.3 checkbox

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

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

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

这样会构建一个

1 < 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时：

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

jqGrid会添加id和name属性

3.2.4 select

1 < select > 2 < option value ='val1' > Value1 </ option > 3 < option value ='val2' > Value2 </ option > 4 ... 5 < option value ='valn' > ValueN </ option > 6 </ select >

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

3.2.4.1 将editoptions的值作为string

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

1 editoptions: { value: “FE:FedEx; IN:InTime; TN:TNT” } 2 will construct 3 < select > 4 < option value ='FE' > FedEx </ option > 5 < option value ='IN' > InTime </ option > 6 < option value ='TN' > TNT </ option > 7 </ select >

3.2.4.2 将editoptions的值作为object

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

1 ... 2 colModel : [ 3 ... 4 {name:'myname', edittype:'select', editoptions:{value:{1:'One',2:'Two'}} }, 5 ... 6 ] 7 ... 8 This will construct an HTML select 9 < select > 10 < option value ='1' > One </ option > 11 < option value ='2' > Two </ option > 12 </ select >

3.2.4.3 设置editoptions的dataUrl参数

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

也可以使用多选，

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

3.2.5 password

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

1 ... editoptions: {size:10, maxlength: 8} 2 3 < input type ="password" size ="10" maxlength ="8" />

jqGrid会添加id和name属性

3.2.6 button

1 < input type ="button" ..... /> 2 3 ... editoptions: {value:'MyButton'} 4 5 < input type ="button" value ="MyButton" />

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

3.2.7 image

1 < input type ="image" ..... /> 2 3 ... editoptions: {src:'path_to_my_image'} 4 5 < input type ="image" src ="path_to_my_image" />

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

3.2.8 file

1 < input type ="file" ..... /> 2 3 ... editoptions: {alt:'Alt text'} 4 5 < 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. 为每个编辑模块添加相应的规则

1 < script > 2 function myelem (value, options) { 3 var el = document.createElement( " input " ); 4 el.type = " text " ; 5 el.value = value; 6 return el; 7 } 8 9 function myvalue(elem, operation, value) { 10 if (operation === ' get ' ) { 11 return $(elem).val(); 12 } else if (operation === ' set ' ) { 13 $( ' input ' ,elem).val(value); 14 } 15 } 16 jQuery( " #grid_id " ).jqGrid({ 17 ... 18 colModel: [ 19 ... 20 {name: ' price ' , ..., editable: true , edittype: ' custom ' , editoptions:{custom_element: myelem, custom_value:myvalue} }, 21 ... 22 ] 23 ... 24 }); 25 </ 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中添加附加的属性。它总是用来在提交服务器前，验证用户输入的值。

1 < script > 2 jQuery( " #grid_id " ).jqGrid({ 3 ... 4 colModel: [ 5 ... 6 {name: ' price ' , ..., editrules:{edithidden: true , required: true ....}, editable: true }, 7 ... 8 ] 9 ... 10 }); 11 </ 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 自定义检查例子

1 < script > 2 function mypricecheck(value, colname) { 3 if (value < 0 || value > 20 ) 4 return [ false , " Please enter value between 0 and 20 " ]; 5 else 6 return [ true , "" ]; 7 } 8 jQuery( " #grid_id " ).jqGrid({ 9 ... 10 colModel: [ 11 ... 12 {name: ' price ' , ..., editrules:{custom: true , custom_func:mypricecheck....}, editable: true }, 13 ... 14 ] 15 ... 16 }); 17 </ script >

3.5 formoptions

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

1 < script > 2 jQuery( " #grid_id " ).jqGrid({ 3 ... 4 colModel: [ 5 ... 6 {name: ' price ' , ..., formoptions:{elmprefix: ' (*) ' , rowpos: 1 , colpos: 2 ....}, editable: true }, 7 ... 8 ] 9 ... 10 }); 11 </ 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开始

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