为Yahoo! UI Extensions Grid增加内置的可编辑器

为Yahoo! UI Extensions Grid增加内置的可编辑器

原文地址 文章日期：2006/9/10

对YUI-EXT GIRD功能需求最强烈的是内置可编辑的支持。市场上大多数收费的JAVASCRIPT GIRD，我看过的那些可编辑支持，并没有给我留下太深的印象。它给你一个基本的TEXT FIELD，一些CHECKBOXS或者是Select fields,这导致了你一边单击某个字段在编辑，另一边厢插入一个FORM到这个单元格之中，不知不觉地，会出现越来越多编辑过的“脚印footprint",尤其是IE，在很多行的情况下。 所以我决定不采用这种方法，而采用类似于Windows或JavaSwing的方式，设计yui-ext Gird的编辑器。为了这一起成为可能，你的反馈必不可少，尤其是你觉得缺少了某些功能，不妨反馈给我。

可编辑GIRD的例子

这是个正在ALPHA测试中的可编辑GIRD。单击某个单元格可编辑。试试这些：输入一个错误的日期；输入大于10的price；输入早于01/01/06的日期；空白CommonName字段；测试数字字段蒙板；双击每列之间的分隔符，可自动调整每列宽度，鼠标滚轮滚动Data picker。

Shade Mostly Shady Sun or Shade Mostly Sunny Sunny

注：如果您发现gird工作不正常，请刷新浏览器，已保证它不是缓冲的（尽管我已经叫它不缓存的了）。
如果还是不行，请在论坛里POST出现的问题，以便我能修复它，谢！

单元格之间的键盘控制

最初的GIRD支持可编辑字段的Tab/Shift Tab、回车、方向键的控制 ，类似MS Excel。这个范例中不仅支持单击，而且支持双击。

实时数据验证

下列的编辑器，当输入数据都会有实时的数据验证。默认情况下，非法的数据会有下划红线提示（像MSOffice），并有tooltip显示错误的原因。这些可用通过CSS改变。如单元格的数据包含非法的数据，编辑后（编辑器失去焦点，用户按下回车或用户按下方向键移动到其它的单元格）单元格会恢复原始值。

国际化支持和韧性配置

编辑器的原型（prototypes）定义了所有错误信息和配置选项，可根据你的需要来覆盖（override）默认的，尤其方便国际化的支持。有两种方式配置：1.设置编辑器的属性；2.传入一个配置对象到编辑器的构建函数。

 // 通过属性设置选项
 var editor = new YAHOO.ext.grid.NumberEditor();
 editor.allowBlank = false;
 editor.minValue = 10;
 editor.minText = "Nice try buddy, %0 is too small.";
 
 //通过配置对象设置选项
 var editor = new YAHOO.ext.grid.NumberEditor({allowBlank: false, minValue: 10, 
 minText: "Nice try buddy, %0 is too small."});
 
 //设置最大最小值，NumberEditors的西班牙文错误提示
 YAHOO.ext.grid.NumberEditor.prototype.minText = "La cantidad debe ser menos de %0";
 YAHOO.ext.grid.NumberEditor.prototype.maxText = "La cantidad debe ser más de %0";
 

预定义编辑器Predefined Editors

当前的编辑器已经实现的功能：

文本编辑器TextEditor 提供一个简单的文本编辑器，下列是配置选项：

• allowBlank - True if the cell is allowed to be empty.
• selectOnFocus - True to select the text when the editor is activated.
• blankText - The tooltip (error message) to display when the cell is empty and is not allowed to be.
• regex - A regular expression to match if the value is valid. If the regex.test(value) returns false, the value is considered invalid.
• regexText - The tooltip (error message) to display when regex does not match.
• validator - Any custom validation function you want called. The function must return true if the data is valid or an error message otherwise.
• validationDelay - The delay in milliseconds for validation. Each time the user types something the field is validated after a specified delay, setting this value allows you to customize that delay (for example, if your custom validation routine is slow).

数字编辑器 NumberEditor

• allowDecimals - True if the cell can have decimal values.
• decimalSeparator - Character(s) to allow as the decimal separator.
• decimalPrecision - Set the maximum decimal precision.
• decimalPrecisionFcn - Define the function to call to remove extra precision (ie. Math.floor, Math.round, Math.ceil or your own function).
• allowNegative - True if the cell allows negative values.
• selectOnFocus - True to select the text when the editor is activated.
• minValue - The minimum value the cell will allow.
• maxValue - The maximum value the cell will allow.
• minText - The tooltip to display when the value in the cell is below the minimum.
• maxText - The tooltip to display when the value in the cell is above the maximum.
• nanText - The tooltip to display when the value in the cell is not a valid number (for example, negatives are allowed and the value in the cell is just "-" with no numbers).
• allowBlank -同TextEditor。
• blankText -同TextEditor。
• validationDelay -同TextEditor。
• validator -同TextEditor。

日期编辑器 DataEditor

提供一个日期编辑器的字段，可选地提供一个DatePicker。如果你不想用内置的DatePicker,DateEditor提供一个方法(showCalendar)来覆盖override内置的DatePicker。相比YUI日历组件，这里我选用了自己的DataPicker,它非常容易地override Gird事件,并工作地很好。压缩后它只有5K大小，而YUI日历压缩后40k大小。使用DataPicker时，左/右改变月份，上下改变年份，鼠标滚轮快速地切换月份。DateEditor支持下列配置选项：

• format - The date format for the editor. The format is now identical to PHP date() and text is allowed. Credit for that goes to this fantastic date library. This format is for the editor only and doesn't affect the rendering of the cell when not in edit mode. Your rendering function can use any date format it wants.
• minValue - The minimum allowed date. Can be either a Javascript date object or a string date in the specified format.
• maxValue - The maximum allowed date. Can be either a Javascript date object or a string date in the specified format.
• minText - The tooltip to display when the date in the cell is before minValue.
• maxText - The tooltip to display when the date in the cell is after maxValue.
• invalidText - The text to display when the date in the field is invalid (for example: 02/31/06)
• disabledDays - An array of days to disable, 0 based. For example, [0, 6] disables Sunday and Saturday.
• disabledDaysText - The tooltip to display when the date in the cell (or DatePicker) falls on a disabled day.
• disabledDates - An array of "dates" to disable, as strings. These strings will be used to build a dynamic regular expression so they are very powerful. For example, ["03/08/2003", "09/16/2003"] would disable those dates, but ["03/08", "09/16"] would disable them for every year. If you are using short years, you will want to use ^ to tell the regular expression to only match the beginning like ["^03/08"]. To disable March of 2006: ["03/../2006"] or every March ["^03"]. In order to support regular expressions, if you are using a date format that has "." in it, you will have to escape the dot when restricting dates. For example: ["03.08.03"].
• disabledDatesText - The tooltip to display when the date in the cell (or DatePicker) falls on a disabled date.
• allowBlank -同TextEditor。
• blankText -同TextEditor。
• validationDelay -同TextEditor。
• validator -同TextEditor。

单选项编辑器CheckboxEditor

为布尔值提供checkbox。当前没有配置选项。

SelectEditor

利用xhtml中的Select字段创建编辑器。你可以在JAVASCRIPT中用DOM来创建select，然后传入到SelectEditor的构建函数，或者用这种简单的方式：定义一个select在xhtml文档中，定义 ygrid-editor class的样式。

ShadeMostly ShadySun or ShadeMostly SunnySunny

创建SelectEditor 对象, 传入Select之ID

var editor = new YAHOO.ext.grid.SelectEditor('light'); 

组合所有的功能在一起

你可以采用这种方式定义一个ColumnModel:

 
var yg = YAHOO.ext.grid;
var cols = [{ 
    header: "Common", 
    width: 120, 
    editor: new yg.TextEditor()
  },{
    header: "Light", 
    width: 80, 
    editor: new yg.SelectEditor('light')
  },{
    header: "Price", 
    width: 50, 
    renderer: formatMoney, 
    editor: new yg.NumberEditor({allowBlank: false, allowNegative: false})
  },{
    header: "Available", 
    width: 85, 
    renderer: formatDate, 
    editor: new yg.DateEditor({format: 'MM/dd/yy', minValue: '01/01/06'})
  },{
    header: "Indoor?", 
    width: 50, 
    renderer: formatBoolean, 
    editor: new yg.CheckboxEditor()
  }];
var colModel = new YAHOO.ext.grid.DefaultColumnModel(cols);

创建自己的编辑器

如果以上的编辑器不够用的话，GIRD与编辑器之间的接口（interface）是足够简单的让你轻松地创建你自己的编辑器。 甚至有个这样一个的基类（CellEditor），已经负责了75%-80%的工作量。CellEditor 接口由三个方法组成（grid, bodyElement, callback）；

init(grid, bodyElement, callback);

这方法在编辑器被激活之前调用（每次）。gird参数明显是gird对象。bodyElement 参数是gird内的元素，当你欲滚动gird body时，编辑器应该渲染的元素。回调函数是用于用户编辑单元格时的调用。

cell.startEditing(value, row, cell);

激活某个单元格编辑后，这个方法被调用。当调用后，编辑器组件应该适应其自身到单元格中，设置它的初始值，附加到特定的事件中，例如，另外一个单元格被激活编辑，那么原来的单元格就要停止编辑了。

stopEditing();

保存数据

改变单元格数据会触发DataModel的onCellUpdated事件。你可利用该事件来保存数据。如果你使用是XMLDataModel，所有的编辑会自动保存到由DataMODEL加载的XML文档。通过getDocument() 可获取该文档。

反馈

回溯到这篇贴子的目的，是为了可以尽可能测试，然后归档，准备发布出来。我正正需要的是反馈。缺了些什么？我肯定这里还有很多你需要、想要的功能而我还没做的。当前只有我一个人在做（不过我也希望有所改变），没有大家的参与是不可能开发想这样的GIRD。如果有你想看到功能，请发表评论或在论坛里参与讨论。谢！

目前这些功能来自反馈：

• NumberEditor.decimalSeparator - 支持不同的十进制分隔符
  
• NumberEditor.decimalPrecision, NumberEditor.decimalPrecisionFcn - Support for decimal precision and rounding etc. See the thread in the forum for details.
  
• Shift-tab to navigate backwards, enter moves down 1 cell.
  
• DatePicker changes: Highlights selected date, highlights today, restricts selection based on min/max values for the DateEditor.
  
• Hiding and "Unhiding" of columns programmatically. You can also start columns in a hidden state.
  
• More DateEditor/Picker enhancements: disabling of days (i.e. Saturday and Sunday), and disabling of individual dates/date ranges/dates each year. The disabling of the dates is accomplished by dynamically building a regular expression so it is very flexible and very fast. See DateEditor above for more details. The date format specifiers are different now and match the PHP date() function instead of Java mm/dd/yy style. The reason is I integrated this small date lib and got rid of my own date parsing code. It's faster and also support dates with text now, such as 15-Mar-06.
  
• Regular expression validation on the TextEditor without using a validator function.

请随时发表反馈！