jqGrid学习笔记(一) Formatters

预定义格式化

格式化在单独的模块中定义，该模块名为jquery.fmatter.js. 该模块包含整在整个jquery.jqGrid.js 文件中。

以下是英文档案的预设格式选项:

$.jgrid.regional["en"] = {
  ...
  formatter : {
        integer : {thousandsSeparator: ",", defaultValue: '0'},
        number : {decimalSeparator:".", thousandsSeparator: ",", decimalPlaces: 2, defaultValue: '0.00'},
        currency : {decimalSeparator:".", thousandsSeparator: ",", decimalPlaces: 2, prefix: "", suffix:"", defaultValue: '0.00'},
        date : {
            dayNames:   [
                "Sun", "Mon", "Tue", "Wed", "Thr", "Fri", "Sat",
                "Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"
            ],
            monthNames: [
                "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec",
                "January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"
            ],
            AmPm : ["am","pm","AM","PM"],
            S: function (j) {return j < 11 || j > 13 ? ['st', 'nd', 'rd', 'th'][Math.min((j - 1) % 10, 3)] : 'th';},
            srcformat: 'Y-m-d',
            newformat: 'n/j/Y',
            parseRe : /[#%\\\/:_;.,\t\s-]/,
            masks : {
                // see http://php.net/manual/en/function.date.php for PHP format used in jqGrid
                // and see http://docs.jquery.com/UI/Datepicker/formatDate
                // and https://github.com/jquery/globalize#dates for alternative formats used frequently
                // one can find on https://github.com/jquery/globalize/tree/master/lib/cultures many
                // information about date, time, numbers and currency formats used in different countries
                // one should just convert the information in PHP format
                ISO8601Long:"Y-m-d H:i:s",
                ISO8601Short:"Y-m-d",
                // short date:
                //    n - Numeric representation of a month, without leading zeros
                //    j - Day of the month without leading zeros
                //    Y - A full numeric representation of a year, 4 digits
                // example: 3/1/2012 which means 1 March 2012
                ShortDate: "n/j/Y", // in jQuery UI Datepicker: "M/d/yyyy"
                // long date:
                //    l - A full textual representation of the day of the week
                //    F - A full textual representation of a month
                //    d - Day of the month, 2 digits with leading zeros
                //    Y - A full numeric representation of a year, 4 digits
                LongDate: "l, F d, Y", // in jQuery UI Datepicker: "dddd, MMMM dd, yyyy"
                // long date with long time:
                //    l - A full textual representation of the day of the week
                //    F - A full textual representation of a month
                //    d - Day of the month, 2 digits with leading zeros
                //    Y - A full numeric representation of a year, 4 digits
                //    g - 12-hour format of an hour without leading zeros
                //    i - Minutes with leading zeros
                //    s - Seconds, with leading zeros
                //    A - Uppercase Ante meridiem and Post meridiem (AM or PM)
                FullDateTime: "l, F d, Y g:i:s A", // in jQuery UI Datepicker: "dddd, MMMM dd, yyyy h:mm:ss tt"
                // month day:
                //    F - A full textual representation of a month
                //    d - Day of the month, 2 digits with leading zeros
                MonthDay: "F d", // in jQuery UI Datepicker: "MMMM dd"
                // short time (without seconds)
                //    g - 12-hour format of an hour without leading zeros
                //    i - Minutes with leading zeros
                //    A - Uppercase Ante meridiem and Post meridiem (AM or PM)
                ShortTime: "g:i A", // in jQuery UI Datepicker: "h:mm tt"
                // long time (with seconds)
                //    g - 12-hour format of an hour without leading zeros
                //    i - Minutes with leading zeros
                //    s - Seconds, with leading zeros
                //    A - Uppercase Ante meridiem and Post meridiem (AM or PM)
                LongTime: "g:i:s A", // in jQuery UI Datepicker: "h:mm:ss tt"
                SortableDateTime: "Y-m-d\\TH:i:s",
                UniversalSortableDateTime: "Y-m-d H:i:sO",
                // month with year
                //    Y - A full numeric representation of a year, 4 digits
                //    F - A full textual representation of a month
                YearMonth: "F, Y" // in jQuery UI Datepicker: "MMMM, yyyy"
            },
            reformatAfterEdit : false,
            userLocalTime : false
        },
        baseLinkUrl: '',
        showAction: '',
        target: '',
        checkbox : {disabled:true},
        idName : 'id'
    },
...
}

For example.

jQuery("#grid_id").jqGrid({
...
  colModel : [
  ...
     {name:'myname', ... formatter:'number', ...},
  ...
  ],
...
});

列特定选项

可以为特定列定义格式化选项，覆盖语言文件中的默认值。通过使用colModel中的formatoptions选项来实现的. For example:

jQuery("#grid_id").jqGrid({
...
   colModel : [
   ...
      {name:'myname', ... formatter:'currency', formatoptions:{decimalSeparator:".", thousandsSeparator: ",", decimalPlaces: 2, prefix: "$ "} } ,
   ...
   ],
...
});

预定义的格式类型

下面是预定义格式类型的列表

integer

• thousandsSeparator - 千位符
• defaultValue 默认值.

如果传入的数字不是整数，带有小数位数的数字，decimalPlaces 属性应该设置为0:

...
colModel : [
...
   {name:'myname', ... formatter:'integer', formatoptions:{thousandsSeparator: " ", deaultValue: "0", decimalPlaces : 0} } ,
...
],
...

"1234.12" => "1 234"
" "       => "0"
"123.65"  => "124"

number

• thousandsSeparator - 千位符.
• decimalSeparator 小数的分隔符.
• decimalPlaces 保留小数的位数
• defaultValue 默认值.

...
colModel : [
...
   { name:'myname', ...,
    formatter:'number',
    formatoptions:{
      thousandsSeparator: " ",
      decimalSeparator: ".",
      decimalPlaces : 1,
      deaultValue: "0.0"
    }
  } ,
...
],
...

currency

• thousandsSeparator - 千位符.
• decimalSeparator 小数的分隔符.
• decimalPlaces 保留小数的位数
• prefix - 前缀字符
• suffix - 后缀字符
• defaultValue 默认值.

...
colModel : [
...
   { name:'myname', ...,
    formatter:'currency',
    formatoptions:{
      thousandsSeparator: ",",
      decimalSeparator: ".",
      decimalPlaces : 2,
      prefix : "$ ",
      suffix : ""
      deaultValue: "$ 0.00"
    }
  } ,
...
],
...

date

• srcformat 源格式，即应该转换的日期格式
• newformat 新的输出格式
• parseRe 一个解析日期字符串的表达式.
• reformatAfterEdit (default false) 日期是否应该在编辑后重新格式化 - i.e 用户更改日期后保存到grid中。因为在editiong模块中使用日期没有格式化.
• userLocalTime (default false) 在插入grid时，强制将本地时间偏移计算到日期中.

...
colModel : [
...
   { name:'myname', ...,
    formatter:'date',
    formatoptions:{
      srcformat: "Y-m-d",
      newformat: "ShortDate" // we use here option mask which is = n/j/Y
    }
  } ,
...
],
...

"2017-03-01" = > 3/1/2017

...
colModel : [
...
   { name:'myname', ...,
    formatter:'date',
    formatoptions:{
      srcformat: "ISO8601Long",
      newformat: "m/d/Y H:i"
    }
  } ,
...
],
...

如果当前时间是+ 2 GMT，结果是：

"2017-03-01 11:19:22Z" = > 03/01/2017 13:19

结果等同于：

...
colModel : [
...
   { name:'myname', ...,
    formatter:'date',
    formatoptions:{
      srcformat: "Y-m-d H:i:s",
      newformat: "m/d/Y H:i",
      userLocalTime : true
    }
  } ,
...
],
...

"2017-03-01 11:19:22" = > 03/01/2017 13:19

email

...
colModel : [
...
   { name:'myname', ...,
    formatter:'date',
    formatoptions:{
      srcformat: "Y-m-d H:i:s",
      newformat: "m/d/Y H:i",
      userLocalTime : true
    }
  } ,
...
],
...

john.smith@yahoo.com => <a href="mailto:john.smith@yahoo.com">john.smith@yahoo.com</a>

link

• target - 定义在何处打开链接的文档.默认是空值。

target属性的可能值为：

• _blank 在新窗口或tab中打开
• _self 在被当季的同一个frame中打开（这个是默认值）
• _parent 在父框架中打开
• _top 在窗口的整个主体中打开
• framename 在指定的框架中打开

...
colModel : [
...
   { name:'myname', ...,
   formatter:'link',
   formatoptions : {
     target : "_blank"
   }
  } ,
...
],
...

http://www.guriddo.net => <a href="http://www.guriddo.net" target="_blank">http://www.guriddo.net</a>

showLink

• baseLinkUrl 使用的链接
• showAction 是在baseLinkUrl后添加的附加值
• addParam 附加参数，可以添加到idName属性之后.
• target -指定在何处打开链接
• idName 在baseLinkUrl后添加的第一个参数，默认值是id

...
colModel : [
...
   { name:'myname', ...,
   formatter:'showLink',
   formatoptions : {
     baseLinkUrl : 'http://myserver.com/'
     showaction: 'editrecord.php'
     addParam : '&action=edit',
     idName : 'id', // this is default
     target : '_blank'
   }
  } ,
...
],
...

如果单元格内容是Edit Record，且行id=10，则

Edit Record => <a href="http://myserver.com/editrecord.php?id=10&action=edit" target="_blank">Edit Record</a>

checkbox

• disabled - 默认值是true，此选项确定是否可以更改checkbox的值。如果设置为false，checkbox的值可以更改。

...
colModel : [
...
   { name:'myname', ...,
   formatter:'checkbox',
   formatoptions : {
     disabled : false
   }
  } ,
...
],
...

true => <input checked="checked" value="true" offval="no" type="checkbox">

特殊格式化

select

• value 定义key的映射到grid的值。这个属性可以是字符串或对象
• delimiter 当Vaule是字符串时使用的分隔符，用来分开不同的key:value。默认是“;”
• separator 当Value是字符串时使用的分隔符，用来分开key和value。默认是":"
• decodeValue 当Value是字符创时使用。此选项为true时，将对字符串进行解码，以防它被编码。当对字符串进行编码并使用editing时，推荐使用此设置。

Note：如果没有设置formatoptions,则尝试从editoptions对象获取相同的值

<script>
jQuery("#grid_id").jqGrid({
...
   colModel : [ {name:'myname', formatter:'select', formatoptions : {value:"1:One;2:Two"}} ... ]
...
});
</script>

源数据可以包含key(“1”或“2”)，但是value(“1”或“2”)将显示在grid中。

对象的定义如下：

<script>
jQuery("#grid_id").jqGrid({
...
  colModel : [
    {
      name:'myname',
      formatter:'select',
      formatoptions : {
        value: { "1":"One","2":"Two" }
      }
    }
    ... ]
...
});
</script>

格式化支持在editoptions中设置多选，如果设置了该选项，就会显示一个由逗号分隔的多个值：

<script>
jQuery("#grid_id").jqGrid({
...
  colModel : [
    {
      name:'myname',
      edittype : 'select',
      formatter:'select',
      editoptions : {
        value: { "1":"One","2":"Two"},
        multiple : true
      }
    }
    ... ]
...
});
</script>

actions

这是一个特殊的特性，我们在其中准备了一个e函数，他在每一行上添加可编辑的按钮。为此，需要再colModel中定义附加列（通常在第一列或最后一列）并设置他的格式化操作。

$("#jqGrid").jqGrid({
  ...
  colModel: [
    {
      label: "Edit Actions",
      name: "actions",
      width: 100,
      formatter: "actions",
      formatoptions: {
        keys: true,
        editOptions: {},
        delOptions: {}
      }       
    },
    ...
  ]
  ...
});

 

 

 此格式化在悬停按钮时使用语言文件中的nav属性来获取一些文本，并使用通用的styleUI属性来获取所需的图标。

默认参数：

formatoptions: {
  keys : false, //如果设置为true，则当用户按ESC键取消编辑不保存；当用户按回车时，保存编辑；如果当前编辑字段是textarea，按回车键时不发生保存
  editbutton:true, //启用或禁用编辑按钮
  delbutton:true, //启用或禁用删除按钮
  editformbutton: false, //启用或禁用表单模式编辑按钮，而不是inline下的编辑
  onEdit : null, //在成功进入编辑状态时触发。行id作为参数传给这个函数
  onSuccess : false, //在保存数据到服务器的请求成功后立即调用。这个函数传递从服务器返回的数据。取决于服务器返回的数据，这个函数将返回true或false。通知用户是否成功。
  url : "", //数据应该保存的url，可以用clientArray进行本地保存
  extraparam : {}, //可以添加到服务器的其他用户参数
  afterSave : null,  //数据保存到服务器后调用此函数。传递的参数是rowid和服务器请求的response。当url被设置为clientArray时也会调用该事件
  onError : null, //在数据保存到服务器后调用。传入的参数是rowid和来自服务器响应的response和status。但url被设置为clientArray时也会调用该事件。要么在ajax错误时调用，要么在onSuccess事件返回false时调用该事件
  afterRestore : null, //在恢复行之后调用（esc键或取消编辑按钮）。传入参数为rowid
  restoreAfterError: null,
  mtype: 'POST',  //发布数据的方法类型(GET或POST)
  editOptions: {}, //如果editformbutton设置为true，则使用有效的editGridRow选项
  delOptions: {}  //有效的editGridRow选项
}       

 

Note：如果编辑按钮在字段处于编辑模式后备激活，我们将自动添加两个附加按钮--保存行和取消编辑。无法禁用这些按钮.

自定义格式化

指定列定义自己的formatter。通常是一个函数，返回一个字符串

一种是定义一个函数，然后在formatter中直接显示函数的名字

<script>
jQuery("#grid_id").jqGrid({
...
   colModel: [
      ...
      {
        name:'price',
        index:'price',
        formatter:currencyFmatter
      },
      ...
   ]
...
});

function currencyFmatter (cellvalue, options, rowObject)
{
   // do something here
   return new_format_value
}
</script>

另一种直接在formatter中直接设置函数和参数

<script>
jQuery("#grid_id").jqGrid({
...
   colModel: [
      ...
      {
        name:'price',
        index:'price',
        formatter: function(cellvalue, options, rowObject) {
          // do something here
          return new_format_value
        }
      },
      ...
   ]
...
});
</script>

• cellvalue - 要格式化的值
• options - 包含这些元素{ rowId: rid, colModel: cm, gid : gridId, pos : column_position, styleUI : guiStyle , isExported : boolval, exporttype : type_when_export}
• rowId - 行id,
• colModel 从jqGrid的colModel数组中获取的这个列的属性的对象,
• gid grid的id,
• pos colModel中列的位置,
• styleUI style对象,
• isExported 仅在导出发生时才传递的参数，允许在导出操作时进行自定义格式化。本例子中的参数为true，仅在导出到CSV、EXCEL或PDF时有效,
• exporttype 一个字符串，只有isExported为true时才可用。表示导出的类型：csv，pdf或excel
  
• rowObject- 用datatype选项确定格式表示的行数据。如果我们有数据类型:xml/xmlstring - rowObject是xml节点，根据xmlReader提供的规则提供。如果数据类型是：json/jsonstring - rowObject为对象，根据jsonReader的规则提供

Unformatting

在使用自定义formatter函数时，可以在使用编辑或getRowData和getCell方法时取回原始值

Example : 显示图片和编辑图片的路径

<script>
jQuery("#grid_id").jqGrid({
...
   colModel: [
      ...
      {
        name:'price',
        index:'price',  
        editable: true,
        formatter:imageFormat,
        unformat:imageUnFormat
      },
      ...
   ]
...
});

function imageFormat( cellvalue, options, rowObject ){
    return '<img src="'+cellvalue+'" />';
}
function imageUnFormat( cellvalue, options, cell){
    return $('img', cell).attr('src');
}
</script>

unformat 函数的参数：

• cellvalue - 未格式化的值（纯文本）
• options -包含以下元素
  options : { rowId: rid, colModel: cm} rowId - 行id colModel jqGrid的colModel数组中获取的colModel。
• cellobject - 一个jQuery单元格对象。可用于单元格元素获取不同的内容-通过示例jQuery(cellobject).html()可用于获取html内容，而不是文本

<script>
jQuery("#grid_id").jqGrid({
...
   colModel: [
      ...
      {
        name:'price',
        index:'price',
        editable: true,
        formatter:currencyFmatter,
        unformat:unformatCurrency
      },
      ...
   ]
...
});

function currencyFmatter (cellvalue, options, rowObject)
{
   return "$"+cellvalue;
}
function  unformatCurrency (cellvalue, options)
{
   return cellvalue.replace("$","");
}
</script>

如果在grid中插入或更新的值为123.00，则在grid中显示的值为$123.00,当我们使用getRowData()或getCell()方法或任何编辑模块时，本列的值将是123.00

定义公共格式化函数

如果在代码中多次使用某些自定义formatter/unformatter，则可以一次性定义格式化函数并将其使用到代码中。

<script type="text/javascript">
jQuery.extend($.fn.fmatter , {
    currencyFmatter : function(cellvalue, options, rowdata) {
    return "$"+cellvalue;
}
});
jQuery.extend($.fn.fmatter.currencyFmatter , {
    unformat : function(cellvalue, options) {
    return cellvalue.replace("$","");
}
});
</script>

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