zk组件开发指南(1)

欢迎使用zk 框架，丰富web 应用最简单的方式。
      组件开发指南描述如何开发zk 组件；关于zk 的概念和特性可以参考开发指南。关于安装可参考快速开始指南。关于组件属性和方法的全面描述大家可参考ZK 开发参考手册。
      在这章节中，我们将向你介绍zk 组件最基本的概念和组件的开发。
1.1 组件的两面性（Two Sides of a Component ）
      一个组件是由两部分组成的：展现层和句柄。它们就像同一硬币的两面。展现层是组件的可视化部分，它运行在浏览器端并负责和用户进行交互。句柄是一个java 对象，它运行在服务器端并负责和应用程序进行交互。

 
1.1.1 展现层
      展现层是一个组件的可视化部分。它是用户看到并与之交互的界面。当一个组件被创建并附属于一个页面时，它的展现层才会在客户端被创建从而提供可视化的外观。
例如，当应用在服务器端创建一个按钮时，按钮模样的展现层就会在客户相应地被创建，因此用户可以点击它。
1.1.2 句柄
      句柄实质上是一个运行在服务器端的java 对象。它拥有应用程序可访问的所有状态和API 函数。从应用程序的角度来看，所能知道和访问的就是这个java 对象。换句话说，应用程序并不是通过互联网与用户直接交互的。相反，应用程序是与java 对象进行交互的，而java 对象（大体说，是组件）相应地再更新 展现层部分。同样，如果用户访问可视化部分，组件会更新java 对象并通过事件的方式通知应用程序。应用程序不需要知道任何关于Ajax ，java mobile ，gongle android 或Flash 。客户端和交互的技术已经在组件的实现中被封装。
1.2 页面和渲染（Page and Rendering ）
      当一个组件被创建（例如 new Button （）），它并不属于任何页面。也就是说，如果组件不属于某个页面，在客户端该组件是不能被展现的。这也意味着任何对组件的更新操作在客户端都是不起作用的。
另一方面，一旦某个组件附属于一个页面（例如，属于一个页面），任何对该组件的更新操作都会使展现层相应发生变化。
为了提高执行效率，zk 不会立即更新客户端的变化。相反，它汇集所有的更新，优化它们，然后将客户端需要更新的一个最小集合做最终处理解析后发送给客户端。最终的解析叫渲染解析。
从应用程序的角度看，存在四种解析。而从组件的角度看，其他的解析都相同，因此对于组件而言，你可以说存在渲染解析和非渲染解析这两种解析。
1.2.1 非渲染解析（The Non-Rendering Phases ）
      与渲染解析相反，在非渲染解析中，除了redraw 方法以外，应用程序和zk 可以访问组件的其他任何方法。如果一个组件需要重画或展现层需要更新状态，这些工作都是组件通知zk 引擎的。例如，你有一个导致客户端重画展现层的方法，那么你可以回调invalidate() 方法。

Java 代码

1. public MyComp extends org.zkoss.zk.ui.AbstractComponent {   
2.        public void setValue(String value) {   
3.               _value = value;   
4.               invalidate();  
5.        }   
6. }   

public MyComp extends org.zkoss.zk.ui.AbstractComponent {

       public void setValue(String value) {

              _value = value;

              invalidate();

       }

}

     Invalidate() 方法的调用后会通知zk 在渲染解析中重画这个组件。它并不立即重画组件。相反，zk 引擎会自动汇集所有的更新，稍后在渲染解析中处理它们。
1.2.2 渲染解析（The Rendering Phase ）
      所有的事件处理完成后，zk 启动渲染解析重画组件在其他解析中无效的部分。换句话说，如果一个组件的invalidate 方法曾被调用，zk 就会在渲染解析中调用redraw() 方法。
      在渲染解析中，只有redraw() 方法被调用,invalidate() 方法不被调用---- 这表明在渲染解析中除了redraw 方法，其他的方法都不能调用。
模式（Molds ）
       AbstractComponent 类的主要实现中介绍了模式的概念。模式是组件表面层样式的一种展现。例如tabbox 支持default 和accordion 两种模式，这两种模式为同一组件提供不同的展示效果。

 

Xml 代码

1. <tabbox mold="default">   
2. </tabbox>   
3. <tabbox mold="accordion">   
4. </tabbox>  

<tabbox mold="default">

</tabbox>

<tabbox mold="accordion">

</tabbox>

  
       为了加速开发效率，在组件开发中推荐继承AbstractComponent 或它的衍生类。继承AbstractComponent ，你不需要直接实现redraw() 方法，而你可以用你喜欢的servlet 技术生成展现层，例如DSP 和JSP 。
1.3 开发组件三部曲（Trilogy of Component Development ）
      从开发的角度看，实现一个组件有三步：第一，你需要设计展现层；第二，你必须在服务器端实现以java 类形式存在的句柄。最后，你需要用xml 文件对它们进行配置使它能被应用程序访问。
      如何实现展现层取决于客户端的技术，例如，ajax 浏览器采用的是html 标记语言和js 代码，而java 手机客户端采用的是Java MIDlet 技术。出于描述的方便，我们在指南中重点放到了ajax 浏览器。下面的图说名了它们之间的关系。


 
1.3.1 开发展现层Development of View
      对于ajax 浏览器，组件的展现层是基于HTML 标签和有选择性的JavaScript 方法。HTML tags 用于可视化的展现，而JavaScript 方法用于初始化、清除、监听浏览器事件和服务器交互。
HTML 标记 （HTML Tags ）
      对于ajax 浏览器，可视化展现是由一系列的HTML 标记语言实现的。例如，你想用HTML 的BUUTON 标记去代表一个组件，那么表面的设计可能是这个样的： 

Xml 代码

1. <BUTTON id="z_ed_0" z.type="mycomps.MyButton">I am a button</BUTTON>   

<BUTTON id="z_ed_0" z.type="mycomps.MyButton">I am a button</BUTTON>

       在这里，z_ed_0 是组件的UUID （该属性是zk 加载器分配 的），z.type 是一个特殊属性用来代表组件的类型。可视化展现层被浏览器解析并运行在浏览器端，然而，它们却是在服务器端生成的，生成时 redraw() 方法被调用。所有的东西都被写在writer argument 这个参数中传递给redraw() 方法后发送给客户端的。为了实现redraw() 方法，你可以通过继承 AbstractComponent 类或它的衍生类来实现，而不需要你自己直接去实现。你可以用你喜欢的Servlet 技术去实现所谓的模板，例如DSP ，JSP 等等。出于描述方便的考虑，我们在这个指南中主要应用DSP 。关于采用Java Servlet 技术，你可以用一个叫组件渲染器的类去实现（即org.zkoss.zk.ui.util.ComponentRenderer ）。它的可读性可能比较困难，但执行效率很好。我们在文章的下边会讲到它。
JavaScript 方法（JavaScript Methods ）
     除了继承一个简单的组件外，你通常需要提供一些JavaScript 代码，用来与用户进行交互、操作HTML 标签和与服务器交互。JavaScript 代 码根据它们的目的不同可以分组为单个的方法。例如，在客户端，你想在组件的初始化中注册一个事件监听器，那么它对应的JavaScript 代码可能是这样 的： 

Js 代码

1. zkMyButton.init = function (cmp) {   
2.       zk.listen(cmp, "click", function (evt) {/*my listener*/});   
3. };   

zkMyButton.init = function (cmp) {

      zk.listen(cmp, "click", function (evt) {/*my listener*/});

};

      在这里，方法的名字是由组件类型决定的，同时名字也决定了何时被调用。在这个例子中，按钮的z.type 是mycomps.MyButton （关于 z.type 属性具体说明在上面有描述）。它表示调用的JavaScript 代码是存储在/web/js/mycomps.js. 这个 JavaScript 文件中的（注意该文件必须存放在可被类加载器加载的位置）。它的组件类型是MyButton 。如果我们想让它在初始化的时候执行，那 么方法的名字必须是zkMyButton.init
(= "zk" + "Type" + ".when"). 类似的, 如果你想在浏览器重新设置大小的时候调用，那么这个方法的名字将是zkMyButton.onSize. 在后面我们会对它做更多的解释。
1.3.2 句柄的开发（Development of Handle ）
      句柄是组件中可被web 应用程序访问的状态和API ，更确切地说，它是实现org.zkoss.zk.ui.Component 接口的一个java 类。一般你不需要直接实现这个接口，你可根据需求，从已存在的类中继承，这些存在的类象
org.zkoss.zk.ui.AbstractComponent, org.zkoss.zk.ui.HtmlBasedComponent, and
org.zkoss.zul.XulComponent. 例如，你想扩展AbstractComponent 的主要实现，java 类的实现可能是这样的：

 

public MyButton extends AbstractComponent { }

      如果你是扩展一些主要应用的实现，除了组件指定的方法外，基本不存在你要实现的抽象类。
1.3.3 配置（Configuration ）
        一旦你实现了展现层和句柄，你可以在xml 文件中说明该组件，以便zk 能加载它，应用程序能用它。这个配置文件叫lang-addon.xml. 在工程中有两个地方你可以放置该文件，一个是在/metainfo/zk 目录下，这种是通过类的路径存储的（一般是jar 文件的一部分）。另一种方法是在web 应用程序中（作为war 文件的一部分）通过在/WEB-INF/zk.xml 中指定正确的路径。
      假设我们展现层的是/web/myaddon/button.dsp ，句柄是com.myaddon.MyButton 类，那么让我们看一下配置应该是这样的：

Xml 代码

1. <language-addon>   
2.     <addon-name>myAddon</addon-name>   
3.      <language-name>xul/html</language-name>   
4.      <component>  
5.         <component-name>mybutton</component-name>   
6.          <component-class>com.myaddon.MyButton</component-class>    
7.         <mold>   
8.            <mold-name>default</mold-name>   
9.             <mold-uri>~./web/myaddon/button.dsp</mold-uri>   
10.         </mold>   
11.     </component>   
12. </language-addon>  

<language-addon>

    <addon-name>myAddon</addon-name>

     <language-name>xul/html</language-name>

     <component>

        <component-name>mybutton</component-name>

         <component-class>com.myaddon.MyButton</component-class> 

        <mold>

           <mold-name>default</mold-name>

            <mold-uri>~./web/myaddon/button.dsp</mold-uri>

        </mold>

    </component>

</language-addon>

      正如上面展现的一样，每一个lang-addon.xml 必须指定一个唯一的名字(addon-name) 和它属于的语言(language- name) 。每个组件定义必须指定组件的名字（component-name ）、句柄 (component-class) 和 展现 (mold). 每个组件可以有多个表现层，每个表现层都有一个名字（mold-name ）。默认的模板名字是default ，该模板必须有（除非你想直接 继承redraw 方法）。