如何创建一个原生AOM输入域组件

实际应用中，用户往往希望能通过可视化的图形组件同时输入日期和时间，AOM2.1版本中没有提供现成的组件，现在我们就来动手做一个。

创建AOM组件的第一步工作是准备好客户端的控件实现，也就是说必须至少先用html和javascript在浏览器上实现这个控件。

在网上可以轻易找到解决这个需求的开源的Ext扩展，例如http://extjs.com/forum/showthread.php?t=21931。这个扩展的效果基本符合我们的要求：

但通过阅读源代码，我发现这个扩展如果要作为一个通用的组件，还至少需要加入以下功能：

对脚本代码进行修改后，新组件的效果如下：

注意截图中隐藏了鼠标指针，此时鼠标正指向分钟的右箭头，我在箭头上加了点小效果，鼠标经过时会更改样式变成空心，鼠标停留时显示“加N分钟”的说明。

组件的客户端脚本用法是：

datetime = new Ext.form.DateField({
format:'Y-m-d H:i',
value:'',
width:300,
menu:new Ext.om.DatetimeMenu({minuteStep:5})
});

可以看出这个控件的核心是Ext.om.DatetimeMenu。改动之后加入了以下初始化参数（全部可选）：

现在把脚本代码文件改名为DateTime-debug.js，注意文件名中的“-debug”是有讲究的，原因下面会说明。这样，我们有了一个可用的客户端控件脚本，并且知道了它的用法（很重要）。现在，我们开始着手把它整合到AOM中去。

为了在能让组件工作，最终渲染出来的页面（以下简称最终页面）必须正确引入 组件脚本代码文件（DateTime-debug.js），这包括两件事：

第一，最终页面上要（至少）包含这样一句：

<script type="text/javascript" src=".../DateTime-debug.js"></script>

第二，DateTime-debug.js文件必须位于在这个“...”的位置上。

第二点很容易办到，只需要把DateTime-debug.js和其他脚本资源放在一起就行了。因此我们把它复制到AOM工程的src/META-INF/resource/ext/om目录中，和其他AOM专有的脚本放在一起。

还需要考虑一点是，DateTime-debug.js是开发客户端控件时用的，包含了缩进格式。作为最终使用的脚本资源则浪费了不必要的带宽，应该考虑对其进行压缩。这里我使用了YUICompressor （http://www.julienlecomte.net/yuicompressor/），在AOM工程的src/META-INF/resource/ext/om目录中使用以下命令行对DateTime-debug.js进行压缩（假设YUICompressor.jar放在D盘根目录）：

java -jar D:\YUICompressor.jar -v -o DateTime.js DateTime-debug.js

执行后得到DateTime.js，文件大小由19kb减小到11kb。这样，通常情况下我们可以引入较小的DateTime.js，在需要进行客户端调试时，通过在operamasks.xml中加入以下设置：

<debug-mode> 
        <uncompressed-js>true</uncompressed-js>
  </debug-mode>

AOM会自动在文件名后加上-debug，改为引入DateTime-debug.js。这正是我们把可编辑的脚本代码文件改名为XXX-debug.js的原因。

现在回过头来看看第一点，事实上它只解决了部分问题，从前一节的控件用法可以看出，这个控件除了需要在DateTime.js中定义的Ext.om.DatetimeMenu，还需要依赖Ext.form.DateField类。这是在ext/package/datemenu.js中定义的，自然也需要引入这个文件。天知道Ext.form.DateField还依赖什么类，还需要引入什么脚本文件？

为了解决脚本包依赖的问题，AOM中使用了一个叫ext-packages.xml的包依赖描述文件，它位于AOM工程的

src\org\operamasks\faces\render\widget\yuiext

目录下，在这个文件中找到以下声明：

<!--
  Form - Date Field
  Files:
    DateField.js
  Dependencies:
    TriggerField.js Field.js TextField.js Component.js DateMenu.js DatePicker.js
    DateItem.js Date.js Layer.js Shadow.js MenuMgr.js Menu.js BasicItem.js Adapter.js
    KeyNav.js ClickRepeater.js
  -->
  <package name="Ext.form.DateField">
    <requires name="Ext.form.Field"/>
    <requires name="Ext.menu.DateMenu"/>
  </package>

在后面加入（并不强制要求，只不过放在一起好看一点）：

<!--
  Form - DateTime Field
  Files:
    DateTime.js
  Dependencies:
    TriggerField.js Field.js TextField.js Component.js DateMenu.js DatePicker.js
    DateItem.js Date.js Layer.js Shadow.js MenuMgr.js Menu.js BasicItem.js Adapter.js
    KeyNav.js ClickRepeater.js
  -->
  <package name="Ext.form.DateTimeField" file="/ext/om/DateTime.js">
    <requires name="Ext.form.DateField"/>
  </package>

这里，我们把这个包命名为Ext.form.DateTimeField，这个名称在后面会用到。并且声明了使用这个包需要引入/ext/om/DateTime.js文件，同时这个包依赖Ext.form.DateField包（参考上面声明）。这样，引入Ext.form.DateTimeField包时，AOM框架会自动根据这里定义的依赖关系在最终页面中渲染出所有必须引入的脚本。

到这里，关于客户端脚本的工作就告一段落了，现在我们（终于）可以开始写点java代码了。

显然，这个组件类应该从UIDateField继承。我们创建一个UIDateTimeFieldBase类，继承UIDateField：

package org.operamasks.faces.component.form.base;
...
public abstract class UIDateTimeFieldBase extends UIDateField {
    /***
     * 小时增量
     */
    protected Integer hourStep;
    
    /***
     * 分钟增量
     */
    protected Integer minuteStep;
    
    /***
     * 小时过滤器
     */
    protected String hourFilter;
    
    /***
     * 分钟过滤器
     */
    protected String minuteFilter;
    
    /***
     * 默认值对齐增量间隔时刻时是否允许超过当前时间。
     * 此值为true时，默认值总是取小于当前时间的符合增量间隔的时刻；
     * 此值为false时，默认值对齐增量间隔时刻时选择最接近的间隔，允许超过当前时间。
     * 默认为false。
     */
    protected Boolean limitedAlign;
}

慢着，你也许会问，为什么要一个UIDateTimeFieldBase类，而不直接用UIDateTimeField类呢？就这么几个属性多出来一个抽象类，这难道就是传说中的过度设计吗？其实，在真正的UIDateTimeField类中要写的远远不只这几个属性定义，而需要至少包括：

此外，还需要：

为了简化这些工作量，AOM提供了一种从组件基类自动生成组件类的机制。现在，你可以抛开以上列举的一大摊事，只需要做两件事：

第一，定义一个RendererHandler（后面会用到）：

package org.operamasks.faces.render.form;
public class DateTimeFieldRenderHandler {
}

第二，在上面定义的UIDateTimeFieldBase类上加上两个标注：

@ComponentMeta(tagName = "dateTimeField")
@Component(renderHandler = DateTimeFieldRenderHandler.class)
public class UIDateTimeFieldBase extends UIDateField {
...

其中，@ComponentMeta标注告诉AOM这个组件的一些配置信息，这里关键是指定了这个组件类对应的页面标签名。@Component标注告诉AOM这是一个组件基类，并且指定了由DateTimeFieldRenderHandler类来负责这个组件类的渲染。

由于组件类一旦写好就比较稳定，因此生成组件类的行为通常是屏蔽的，为了打开自动生成组件类的功能，我们打开org.operamasks.faces.component.form.base包（UIDateTimeFieldBase所在的包）下的package-info.java文件。此文件非常简单：

@ComponentPackage(value="org.operamasks.faces.component.form.impl",
                  catalog="form",enable=false)
@ComponentTagPackage(value="org.operamasks.faces.webapp.form")
package org.operamasks.faces.component.form.base;

这里设置了这个包下的组件基类生成组件类时的配置信息，其中，@ComponentPackage标签的：

因此，我们要做的只是把enable属性设为true。当然，如果是在一个全新的包里编写组件基类，则应该为这个包编写一个package-info.java文件。

万事具备，现在在eclipse的ant视图中执行AOM工程里build.xml的process-component任务，完成后刷新一下工程，你会发现在org.operamasks.faces.component.form.impl包里已经生成了UIDateTimeField类。此外，工程中都某些配置文件被修改过，AOM已经自动完成了相关的配置，现在在xhtml页面中写<w:dateTimeField>就已经不再报错并能绑定到UIDateTimeField类上了。

但是如果现在运行带有<w:dateTimeField>的页面，是什么都看不到的，因为我们还没有为它编写渲染器。

在上一步中我们其实已经创建了渲染器类DateTimeFieldRenderHandler，并且指定了它与UIDateTimeField的对应关系，接下来我们需要填入渲染逻辑。

datetime = new Ext.form.DateField({
format:'Y-m-d H:i',
value:'',
width:300,
menu:new Ext.om.DatetimeMenu({minuteStep:5})
});

public class DateTimeFieldRenderHandler extends DateFieldRenderHandler {
...

@ExtClass("Ext.form.DateField")
@DependPackages({"Ext.form","Ext.form.DateTimeField"})
public class DateTimeFieldRenderHandler extends DateFieldRenderHandler {

public class DateTimeFieldRenderHandler extends DateFieldRenderHandler {
    
    private static final String NEW_MENU_STATEMENT = "new Ext.om.DatetimeMenu(";

    @Override
    protected void processExtConfig(FacesContext context, UIComponent component, ExtConfig config) {
        super.processExtConfig(context, component, config);
        UIDateTimeField field = (UIDateTimeField) component;
        StringBuilder buf = new StringBuilder();
        buf.append(NEW_MENU_STATEMENT).append("{");
        Integer hourStep = field.getHourStep();
        if (hourStep != null && hourStep > 0 && hourStep < 24) {
            buf.append("hourStep:").append(hourStep.toString()).append(",");
        }
        Integer minuteStep = field.getMinuteStep();
        if (minuteStep != null && minuteStep > 0 && minuteStep < 60) {
            buf.append("minuteStep:").append(minuteStep.toString()).append(",");
        }
        Boolean limitedAlign = field.getLimitedAlign();
        if (Boolean.TRUE == limitedAlign) {
            buf.append("limitedAlign:true,");
        }
        String hourFilter = field.getHourFilter();
        if (hourFilter != null) {
            buf.append("hourFilter:").append(hourFilter).append(",");
        }
        String minuteFilter = field.getMinuteFilter();
        if (minuteFilter != null) {
            buf.append("minuteFilter:").append(minuteFilter).append(",");
        }
        buf.deleteCharAt(buf.length() - 1);
        if (buf.length() == NEW_MENU_STATEMENT.length()) {
            buf.append(")");
        } else {
            buf.append("})");
        }
        config.set("menu", buf.toString(), true);
    }

public class DateFieldRenderHandler extends TextFieldRenderHandler {
...
    protected void processExtConfig(FacesContext context, UIComponent component, ExtConfig config) {
...
            String format = DateTimeFormatUtils.DEFAUTL_DATE_FORMAT;

public class DateFieldRenderHandler extends TextFieldRenderHandler {
...
    protected void processExtConfig(FacesContext context, UIComponent component, ExtConfig config) {
...
        format = getDefaultFormat();
...
    }

    protected String getDefaultFormat() {
        return DateTimeFormatUtils.DEFAUTL_DATE_FORMAT;
    }

public class DateTimeFieldRenderHandler extends DateFieldRenderHandler {
...
    @Override
    protected String getDefaultFormat() {
        return DateTimeFormatUtils.DEFAULT_DATETIME_FORMAT;
    }
}

至此，这个组件就大功告成了。对于其他某些输入域组件，还需要编写对应的转换器和校验器。但本例中由于继承的UIDateField所用的DefaultDateTimeConverter就有时间转换能力，因此不用另外编写。现在，我们可以编写一个简单的页面对这个新组件进行测试：

页面：

<w:page title="Insert title here">
        <w:form>
            <w:dateTimeField limitedAlign="true" hourFilter="chk_workhour"
                format="yyyy年MM月dd日HH时mm分" width="250" />
            <w:button id="action" />
        </w:form>
    </w:page>
    <script>
    <!--
        function chk_workhour(v) {
           return (v >= 8 && v <= 12) || (v >= 14 && v <= 18);
        }
     -->
    </script>

Bean

import java.util.Date;

public class TestDateTimeFieldBean implements Serializable {
    @Bind
    Date datetime;
 
    @Action
    private void action() {
        System.out.println(datetime.toString());
    }
}

展现效果：

提交后控制台输出：