AOM组件规范（试行版）

AOM组件规范

---

Chapter 1. 版本历史

Table 1.1. Apusic Operamasks组件规范 Version 0.1

规范版本号	0.1
最后更新	2008年6月6日
版本说明	初始版本
起草人	Patrick

Chapter 2. 组件使用

2.1. 组件体系

AOM2.0中常用组件约70多个（未包括图表类组件与JSF原生组件），在设计时已按照其功能特性分别归类到以下命名空间中：

• http://www.apusic.com/jsf/widget ：.  此命名空间中的组件大部分是常用的界面组件，通过这些组件可以快速的搭建应用程序。同时此命名空间中也提供了一些用于展现风格控制，页结构声明等场景的非可视化组件。下文中属于此命名的组件将以w:为命名空间前缀

• http://www.apusic.com/jsf/layout ：.  此命名空间中包含了一系列布局组件，通过使用这些布局组件，可以方便、灵活的对页面进行布局。下文中属于此命名的组件将以layout:为命名空间前缀。

• http://www.apusic.com/jsf/ajax ：.  此命名空间中包含了一组实用的ajax工具组件，可以很容易的为系统增加ajax特性。下文中属于此命名的组件将以ajax:为命名空间前缀。

• http://www.apusic.com/jsf/misc ：.  此命名空间中包含了与服务器端逻辑声明相关的一些标签。下文中属于此命名的组件将以om:为命名空间前缀。

由于命名空间本身会影响到用户的编程体验与设计工具的布局，因此在这里采用了较粗粒度的分类。对于AOM中的组件还可以从以下角度进行分类：

• 从页面组件是否关联到JSF的实体组件类（UIComponent的子类）来分类。 关联到组件类的页面组件（下文称为实体组件）将在服务器端组件树中创建对应的组件类，由AOM引擎来维护其组件树层次结构、状态恢复、模型绑定等特性。而 没有关联到组件类的页面组件（下文简称为非实体组件）在服务器端组件树中不存在对应的实体组件类，自然也无法在模型对象中绑定此类组件的组件类。

• 从 页面组件的可视化功能进行分类。从可视化特性来划分，组件可以大体分为可视组件与非可视组件。可视组件将对应最终呈现页面上的一块区域，并在其中展现其内 容。非可视组件则主要负责声明与功能行为，其自身在页面上不可见。但非可视组件仍可能对最终呈现的效果产生影响。例如<w: forEach>、<w:stylesheet>等组件。

  大部分可视组件属于实体组件，但也存在例外，非实体 的可视组件往往是一个结构性实体组件的子组件，例如<w:dataGrid>的<w:outputColumn>组件，或 <w:panelGrid>的<w:cell>组件等等。

下面将对可视组件与非可视组件按照其功能再作进一步的分类。这里仅列出各类组件的标签名称，组件的具体作用请参考组件文档。进行这种分类有助于下文对组件的共性与各类规则的描述。

2.1.1. 可视组件

下表列出了AOM2.0支持的可视组件标签，同时列出实体组件所对应的组件类。若标签没有指明组件类，则此标签为非实体组件。

2.1.2. 非可视组件

下表列出了AOM2.0支持的非可视组件标签，同时列出实体组件所对应的组件类。若标签没有指明组件类，则此标签为非实体组件。

2.2. 组件类

在页面中使用标签放置的实体组件，都对应一个服务器端组件类的实例。这个组件类实例可通过标签的bind属性或IoVC的@Bind标注与ManagedBean中的属性进行绑定，在ManagedBean中通过组件类的API进行各种操作。

一般来说，可视组件类的命名规则应为“UI”加上首字大写的页面标签名。例如<w:button>对应的组件类是UIButton。 http://www.apusic.com/jsf/ajax命名空间下的组件类以“Ajax”开头加上首字大写的页面标签名（此包下的可视组件亦以此 规则为准），例如<ajax:updater>的组件类是AjaxUpdater。非可视组件类的命名为首字大写的页面标签名。上一节的列表 中列出了与组件标签对应的组件类，对于不符合以上命名规则的组件类，用橙色标出。

2.2.1. 组件属性

2.2.1.1. 属性命名规则

本节列出一些常见属性的命名规则，描述中使用以下术语：

• 以...为前缀：表示名称以某字符串开头，不应改变其大小写。

• 以...为标识：表示名称中应包含某字符串，若其位于名称开头，应首字小写，否则，应首字大写。

• 以...命名：表示应以此字符串作为名称，不应改变其大小写。

常见属性的命名遵循以下规则：

1. 可见性属性：

   • rendered属性表示此组件是否被渲染。目前所有组件均有此属性，但应注意此属性不支持在ajax环境下动态修改，需要配合<ajax:updater>使用。

   • visible属性表示此组件会被渲染时在客户端设定的可见性。

     * 目前违反此规则的属性与对应组件有：

     hidden : outputColumn idColumn

   • 组件部件的可见性，以前缀show加上首字大写部件为名称的属性表示是否显示此部件。

     * 目前违反此规则的属性和对应组件有：

     border           : accordionLayout columnLayout tree iframe tabLayout borderLayout tableLayout editDataGrid gridLayout panelBox cardLayout panelGrid dataGrid window absoluteLayout panel
     footer           : cardLayout accordionLayout columnLayout tree dataGrid tabLayout borderLayout window tableLayout editDataGrid panel absoluteLayout
     frameborder      : iframe
     header           : accordionLayout columnLayout tree tabLayout borderLayout tableLayout editDataGrid cardLayout dataGrid outputColumn window idColumn absoluteLayout panel 
     hideBorders      : cardLayout accordionLayout columnLayout tree dataGrid tabLayout borderLayout window tableLayout editDataGrid panel absoluteLayout 
     hideCollapseTool : cardLayout accordionLayout columnLayout tree dataGrid tabLayout borderLayout window tableLayout editDataGrid panel absoluteLayout 
     hideHeaders      : dataGrid editDataGrid 
     hideLabel        : checkBox numberField textField combo timeField dateField textArea calcNumberField simpleHtmlEditor 
     hideParent       : cardLayout accordionLayout columnLayout tree dataGrid tabLayout borderLayout window tableLayout editDataGrid panel absoluteLayout 
     hideTrigger      : combo timeField dateField 
     drawArrow        : textAnnotation 
     drawBaseLine     : xAxis axis yAxis 
     drawGridLine     : xAxis axis yAxis 
     drawItemLabel    : compositeChart scatterChart timeDataItem curveAreaChart lineChart chart areaChart curveChart xyDataItem functionItem histogramDataItem barChart radarChart pieChart dataItem 
     drawLine         : xAxis axis yAxis 
     drawLines        : curveChart functionItem xyDataItem timeDataItem curveAreaChart lineChart histogramDataItem dataItem 
     drawMarkers      : curveChart functionItem xyDataItem timeDataItem curveAreaChart lineChart histogramDataItem dataItem 
     drawOutline      : compositeChart scatterChart timeDataItem curveAreaChart lineChart chart areaChart curveChart xyDataItem functionItem histogramDataItem barChart radarChart pieChart dataItem 
     drawTickLabels   : xAxis axis yAxis 
     drawTickMarks    : xAxis axis yAxis

2. 有效性属性：

   • disabled属性用于决定组件自身的有效性；

   • 根据组件有效性设置而生效的属性，以enabled或disabled为前缀。例如disabledClass等。

   • 动作的有效性使用动词的able形式。例如editable，closable等；

   • 特性或子部件的有效性使用“enableXXX”形式，例如enableColumnMove等。

     目前违反此规则的属性和对应组件有：

     maskDisabled : cardLayout accordionLayout columnLayout tree dataGrid tabLayout borderLayout window tableLayout editDataGrid panel absoluteLayout

   • 表示是否需要引擎提供支持（更新，回调，注入等）的属性，使用require为前缀。

     目前违反此规则的属性和对应组件有：

     updateAble : treeNode

3. 可接受性属性：

   • 表示允许接受某种子组件或输入值的属性，使用allow为前缀。例如allowChildren。

   • 具体列出允许或不允许的取值的属性，使用allowed或disallowed为前缀。

   • readOnly属性表示是否允许用户输入。

     目前违反此规则的属性和对应组件有：

     readonly: chooseSkin dateMenu slider datePicker button

4. 有序属性：

   • 表示“排序前一位”或“上一次”的属性使用prev为前缀。例如<w:pagingToolbar>的prevText。

   • 表示“排序后一位”或“下一次”的属性使用next为前缀。

   • 表示第一位或第一次的属性使用first为前缀。

   • 表示最后一位或最后一次的属性使用last为前缀。

   • 表示显示位置的前面使用before为前缀。例如<w:pagingToolbar>的beforePageText。表示显示位置的后面使用after为前缀。

5. 统计量属性：

   • 表示最大值的属性，在不引起歧义的情况下，可使用maximum作为属性名。若同一组件可设定多种最大值，组件自身取值的最大值使用maxValue作为属性名，其它表示最大值的属性应以max为前缀。

   • 表示最小值的属性，在不引起歧义的情况下，可使用minimum作为属性名。若同一组件可设定多种最小值，组件自身取值的最小值使用minValue作为属性名，其它表示最大值的属性应以min为前缀。

6. 信息属性：

   • 标题统一以title命名（或前缀）。

     目前违反此规则的属性和对应组件有：

     captionClass : panelGrid gridLayout 
     captionStyle : panelGrid gridLayout

   • 表示组件的标签性提示信息的属性，以label为标识。（注，以xxx为标识指属性名中包含此字符串，若其并非开头，应按照java bean属性命名规则首字大写。下同。）

   • 表示跟随鼠标弹出提示信息的属性，以tip为标识。

   • 表示正常情况下提示信息的属性，以text为标识。例如：emptyText

   • 表示出错提示信息（包括未符合其他属性所指定的条件）的属性，以message为标识。

     目前违反上述两项的属性和对应组件有：

     blankText            : numberField textField combo timeField dateField textArea calcNumberField
     disabledDatesText    : dateField
     disabledDaysText     : dateField
     invalidText          : checkBox numberField textField combo timeField dateField textArea calcNumberField simpleHtmlEditor
     maxLengthText        : numberField textField combo timeField dateField textArea calcNumberField
     maxText              : numberField timeField dateField calcNumberField
     minLengthText        : numberField textField combo timeField dateField textArea calcNumberField
     minText              : numberField timeField dateField
     nanText              : numberField calcNumberField
     regexText            : numberField textField combo timeField dateField textArea calcNumberField
     valueNotFoundText    : combo timeField
     vtypeText            : numberField textField combo timeField dateField textArea calcNumberField
     
     completeMessage      : fileUploadProgress
     startMessage         : fileUploadProgress
     uploadingMessage     : fileUploadProgress

7. 样式属性：

   • 背景颜色属性统一命名为bgcolor。与背景相关的属性统一以bg为前缀

     backgroundAlpha      : scatterChart compositeChart curveChart curveAreaChart lineChart barChart chart radarChart pieChart areaChart 
     backgroundColor      : scatterChart compositeChart legend curveChart title curveAreaChart lineChart barChart chart radarChart pieChart areaChart 
     backgroundImage      : scatterChart compositeChart curveChart curveAreaChart lineChart barChart chart radarChart pieChart areaChart 
     backgroundImageAlpha : scatterChart compositeChart curveChart curveAreaChart lineChart barChart chart radarChart pieChart areaChart 
     backgroundImagePosition : scatterChart compositeChart curveChart curveAreaChart lineChart barChart chart radarChart pieChart areaChart

   • 与CSS Class相关的属性以class为标识（不应称为XXXStyleClass）。

     contentStyleClass    : panelBox
     startStyleClass      : status
     stopStyleClass       : status
     styleClass           : drawImage form chart simpleDataGrid gridLayout separator toolBar menuItem pieChart menu idColumn fileUpload radioMenuItem scatterChart compositeChart checkMenuItem menuBar curveAreaChart updater lineChart cell status commandMenuItem areaChart linkMenuItem chooseSkin curveChart panelBox panelGrid dataView slider page barChart progressBar outputColumn renderGroup radarChart logger

   • 与CSS Style相关的属性以style为标识。组件自身的CSS Style的属性命名为style。

8. 连接属性：

   • 对外部网址的引用属性（不经JSF导航规则处理），使用href命名。

   • 对会经过JSF导航规则处理的地址引用，使用url命名。

2.3. 组件事件

AOM中存在着多种事件，包括请求生命周期事件，组件事件，应用事件等。本文只对组件事件进行规范。

根据组件事件的发起位置，可以分为UI（User Interface）事件和模型事件两类：

• UI事件：指跟UI相关并由用户的操作而产生的事件。例如一个<w:button>组件的onclick事件，或一个<w:textField>组件的onchange事件等。

• 模型事件：指跟UI无关，主要由于组件模型自身机制而产生的事件。例如dataGrid在装载数据时所广播的ondataload事件。

2.3.1. UI事件

根据UI事件侦听逻辑的执行位置，可以分为客户端侦听与服务器端侦听两种。

2.3.1.1. 在客户端侦听并响应UI事件

客户端的侦听逻辑通过组件属性暴露，若需要在客户端侦听并响应UI事件，应在组件的事件属性中使用客户端脚本（javascript）编写侦听逻 辑。事件属性的命名应为“on”开头后续全小写的事件名称，例如<w:button onclick="...">。事件属性的取值应为String类型，或结果为String类型的EL表达式，取值为javascript代码，代 码前可以加上javascript:标识，也可以忽略。因此，在AOM中以下三种写法是等价的：

• 页面：
  <w:button onclick="alert('I am clicked');"/>

   

• 页面：
  <w:button onclick="#{bean.clickedJs}/>
  
  ManagedBean：
  public String getClickedJs() {
      return "javascript:alert('I am clicked');"
  }

   

• 页面：
  <w:button onclick="#{bean.clickedJs()}/>
  
  ManagedBean：
  public String clickedJs() {
      return "alert('I am clicked');"
  }

2.3.1.2. 在服务器端侦听并响应UI事件

2.3.1.2.1. 静态定义服务器端侦听方法

在AOM中，所有在客户端执行的事件都可通过<ajax:action>标签转变为在服务器端执行，根据下面规则：

• <ajax:action>作为UI组件的子组件，侦听其父组件的UI事件，并引起页面提交，触发服务器端处理逻辑。 可使用以下三种方式之一指定<ajax:action>所侦听的事件：

  1. 使用<ajax:action>标签的event属性指定事件名称。

     <w:textField id="txt">
         <ajax:action event="onblur" action="#{bean.txtBlurAction}"/>
     </w:textField>

  2. 使用@Action或@ActionListener标注在ManagedBean上作IoVC绑定，用标注的event属性指定事件名称指定。

     页面代码：
     <w:textField id="txt"/>
     
     ManagedBean：
     @Action(id = "txt", event = "onblur")
     public void txtBlurAction()

     注：@ActionListener与@Action作用相同，但@ActionListener标注的方法还可接收一个类型为javax.faces.event.ActionEvent的参数，获取触发此侦听方法的事件实例。例如：

     @ActionListener(id = "btn1")
     private void action1(ActionEvent event) {
         System.out.println("action1 called by " + event.getSource().getClass());
     }
         
     @ActionListener(id = "btn1")
     private void action2() {
         System.out.println("action2 called");
     }

     单击页面中所绑定的<w:button id="btn1"/>按钮，得到的输出为：

     action1 called by class org.operamasks.faces.component.widget.UIButton
     action2 called

     使用@ActionListener可为一个组件绑定多个侦听方法，但这些侦听方法执行顺序未作定义。此外，使用标签@ActionListeners应可为多个组件事件指定同一个侦听方法：

     @ActionListeners({
         @ActionListener(id = "btn1"),
         @ActionListener(id = "btn2")})
     private void action(ActionEvent event) {
         System.out.println("action called by " + ((UIComponent)event.getSource()).getId());
     }

  3. 使用@Action或@ActionListener标注在ManagedBean上作IoVC绑定，由被标注方法的命名约定“<UI组件id>_<侦听事件名称>”指定。

     页面代码：
     <w:textField id="txt"/>
     
     ManagedBean：
     @Action
     public void txt_onblur()

• 服务器端侦听方法可使用以下两种方式之一指定（示例同上）：

  1. 使用<ajax:action>标签的action属性指定类型为MethodExpression的统一EL表达式。

  2. 使用@Action或@ActionListener标注在ManagedBean中绑定侦听方法。

  服务器端侦听方法允许使用以下两种签名之一：

  • 无参数

  • 带一个类型为AjaxEvent的参数。AjaxEvent接口定位为：

    /**
     * 获取触发事件的UI组件
     */
    public UIComponent getSource();
    
    /**
     * 获取本事件的相关参数
     */
    public Map<String, Object> getParams();

注：计划加入支持静态定义AjaxActionListener的方式（关于AjaxActionListener接口详见Section 2.3.1.2.2, “动态定义服务器端侦听器” ），但具体方案仍在设计中。初定在UI组件标签中加入名为“<事件名称>Listener”的属性，用于指定结果类型为AjaxActionListener的统一EL表达式。例如可通过以下代码加入一个onclick事件的服务器端侦听器：

<w:button id="btn" onclickListener="#{mylistener}"/>

其中mylistener是一个实现了AjaxActionListener接口的ManagedBean。

2.3.1.2.2. 动态定义服务器端侦听器

在AOM中，可通过组件类实例的addFacesListener(FacesListener listener)方法动态加入一个服务器端侦听器。传入的listener应为AjaxActionListener接口的实现类。 AjaxActionListener接口暴露以下方法：

public interface AjaxActionListener extends javax.faces.event.FacesListener {
   /**
    * 返回此侦听器所侦听的事件名称
    */
   Set<String> getListeningEvents();

   /**
    * 事件被触发时的处理逻辑
    */
   void process(AjaxEvent event);
}

2.3.1.3. 客户端侦听方法与服务器端侦听器的执行关系

若一个组件的一个事件同时定义了客户端侦听方法与服务器端侦听器，执行顺序为：事件触发时，首先在客户端执行客户端侦听方法，若此方法顺利执行并返 回true（若方法无返回值，默认为true），则提交页面，执行服务器端侦听器逻辑。若客户端侦听方法显式返回false，则不会提交页面，自然也不执 行服务器端侦听器逻辑。

2.3.2. 模型事件

由于组件模型自身机制而产生的事件称为模型事件，此类事件统一以消息总线（MessageBus）的形式进行处理。例如以下代码定义了id为grid的DataGrid组件的ondataload事件的侦听方法：

@EventListener("grid_ondataload")
private void ondataload(AjaxEvent event) {
   ...
}

2.4. transient属性

所有UI组件均具有transient属性，在AOM中，此属性为false（默认）指UI组件将保存完整ViewState信息，为true表明 此UI组件只保存无法从faces页面重建的部分ViewStateView。由于ViewState本身对用户透明，因此对于任一组件，除非需要在运行 期动态修改其子组件树结构，否则该组件在transient属性为true时的渲染结果和行为应与transient属性为false时一致。

若需要让transient属性为true的组件支持动态子组件树，需要将其置于<om:stateAware>组件之中：

<om:stateAware deep="true">
    <ajax:updater binding="#{DynamicPageBean.updater}">
          <layout:panelGrid binding="#{DynamicPageBean.panelGrid}" columns="1" border="1">
          </layout:panelGrid>
    </ajax:updater>
</om:stateAware>