孙景文  程序人生

JSF RichFaces 中文用户开发指南

1. 介绍

2. 开始使用Ajax4jsf
    环境需求
    下载Ajax4jsf
    安装
    简单的 AJAX Echo 项目
    JSP 页面
    数据 Bean
    faces-config.xml
    Web.xml
    部署

3.  Ajax4jsf 框架的基本概念
    介绍
    结构概览
    如何做...
    发送一个AJAX 请求
    决定发送什么
    决定改变什么

4. Ajax4JSF 组件库
    a4j:ajaxListener
    a4j:region
    a4j:page
    a4j:support
    a4j:commandLink
    a4j:commandButton
    a4j:outputPanel
    a4j:actionparam
    a4j:status
    a4j:loadBundle
    a4j:mediaOutput

5. Ajax4jsf内建的换肤功能

6. 技术要求
    支持的java版本
    支持的 JavaServer Faces 实现
    支持的服务器
    支持的浏览器

7. 附加的设置
    Web程序描述符参数
    Sun JSF RI
    Apache MyFaces
    Facelets 支持
    JBoss Seam 支持

8. 与IDE集成 

9. Exadel VCP 和 Ajax4jsf

10. Web上的资源
    List of Tables
    4.1. a4j:ajaxListener attributes
    4.2. a4j:region attributes
    4.3. a4j:page attributes
    4.4. a4j:support attributes
    4.5. a4j:commandLink attributes
    4.6. a4j:commandButton attributes
    4.7. a4j:outputPanel attributes
    4.8. a4j:actionparam attributes
    4.9. a4j:status attributes
    4.10. a4j:loadBundle attributes
    4.11. a4j:mediaOutput attributes
    7.1. Initialization Parametres
    7.2. org.ajax4jsf.Filter Initialization Parametres
    10.1. Ajax4jsf Resources


序言:

Ajax4JSF是一个很容易使用的框架.有什么问题可以在JSF中文论坛讨论.

Chapter 1. 介绍

    Ajax4jsf 是一个添加Ajax功能到JSF项目中的开源框架,使用该框架不用写JS代码.
    Ajax4jsf 充分利用了JSF框架的优点,如: 生命周期, 验证,转换的灵活性和受管理的静态和动态资源.
    Ajax4jsf, 具有Ajax支持的富组件和高度可自定义的外观感觉可以很容易的与JSF结合起来.
   
    Ajax4JSF 被设计用来:
    在使用Ajax时充分显示JSF的优点.Ajax4jsf 完全被结合到 JSF 生命周期中. 当其他框架仅仅给你访问Managed Bean的便利时,Ajax4JSF带给你 Action 和 Value Change 监听器,激活服务端验证,在Ajax请求-响应周期中的转化这些功能.

    添加 AJAX 功能到已经存在的 JSF 项目. 该框架被实现为使用一个组件库来添加ajax功能到你的页面中,而不要写js代码或者使用新的Ajax装饰器替换你已经做好的JSF组件. Ajax4jsf 具有页面范围(page-wide)的Ajax支持,而不是传统的组件范围(component-wide)的ajax支持.  这意味着你可以在页面中定义一个激活Ajax请求的事件,和当根据客户端事件触发Ajax请求来改变服务器端数据后如何使用JSF组件树来同步显示JSF页面.

    使用内建的Ajax支持写自定义富组件. 将来, 我们将有一个完全的组件开发包(CDK)来支持AJax4JSF. CDK 将包含代码生成工具和一个使用类似JSP语法的模版工具.这些功能将去除一些创建组件的一个例行工作.使用这个喝满油的组件工厂机器来创建一个带有 Ajax功能的富组件将比使用传统的编码过程创建一个简单的组件还要简单.

    项目的Java类与资源包. 除了核心的 AJAX 功能外, Ajax4jsf 也有管理资源的高级支持,例如:图片,JS代码和CSS样式表单,资源框架使 简单的打包这些资源到你自定义组件的Jar文件中成为可能.
   
    动态(on-the-fly)将非常容易. 作为另外一种附加的功能, 资源框架有一个动态产生图片的工具. 使用这个特性,你可以使用类似于使用Java Graphic2D库的方法来创建图片.

    使用基于皮肤的技术来创建一个现代富用户界面的外观感觉(look-and-feel). Ajax4jsf 提供一个换肤特性 . 该特性允许通过命名的皮肤参数来简单的定义和管理不同颜色模式与其他UI特性. 你可以从JSP代码和Java代码(例如:基于UI的文本来产生动态的图片)来访问这些皮肤参数 . 注意:, 虽然换肤功能不是完全的替代传统的CSS,但是它还是值得称赞的.

    测试components, actions, listeners, 和 pages 就像你在创建他们一样容易. 一个制动测试工具正在开发中 .它将在你开发组件使为你的组件产生测试案例. 该测试框架不仅仅测试组件,也测试服务端和客户端的功能包括JS代码 .作为附加的有用工具,你不需要单独的部署测试程序到Servlet容器中 就可以做到这些了.

    Ajax4JSF 组件已经可以使用了, 因此开发者可以立即使用这种省时的具有高级特性的工具来创建提供了更快更可靠的用户体验的Web程序了.


Chapter 2. 开始使用Ajax4jsf

    Table of Contents
    Environment
    Downloading Ajax4jsf
    Installation
    Simple AJAX Echo Project
    JSP Page
    Data Bean
    faces-config.xml
    Web.xml
    Deployment


环境要求

    要使用Ajax4JSF 框架你仅仅需要JDK1.4或者更高,任何JSF实现,和你最喜欢的Servlet容器.在下一章我们将给你提供详细的环境信息.

    Ajax4jsf 被设计为一个容易使用的框架.仅仅有一点简单的设置步骤就可以在你的JSF程序中使用Ajax功能了.


下载 Ajax4jsf

    最新的Ajax4jsf 发布版在这里 https://ajax4jsf.dev.java.net/nonav/ajax/ajax-jsf/download.html 下载.

安装

    解压 ajax4jsf.zip 文件.复制 ajax4jsf.jar and oscache-2.2.jar 到程序的 WEB-INF/lib 文件夹下.把下面的内容添加到你的程序的 WEB-INF/web.xml 文件中:
    <filter>
        <display-name>Ajax4jsf Filter</display-name>
        <filter-name>ajax4jsf</filter-name>
        <filter-class>org.ajax4jsf.Filter</filter-class>
    </filter>
    <filter-mapping>
        <filter-name>ajax4jsf</filter-name>
        <servlet-name>Faces Servlet</servlet-name>
        <dispatcher>REQUEST</dispatcher>
        <dispatcher>FORWARD</dispatcher>
        <dispatcher>INCLUDE</dispatcher>
    </filter-mapping>
    注意. 你可以复制和粘贴上面的内容在 README.txt 文件中.


    添加下面的内容:
    <%@ taglib uri="https://ajax4jsf.dev.java.net/ajax" prefix="a4j"%>
    到你每个使用Ajax功能的JSP页面中.


简单的 AJAX Echo 项目

    让我们来看一个简单的JSF项目. 我们仅仅需要一个JSP页面,里面包含一个Form和一些JSF标签:<h:inputText> 和 <h:outputText>.
   
    我们这个简单的程序应该可以让我们输入一些文字到<h:inputText>中, 然后发送数据到Server,并在 <h:outputText>中显示Server的响应(给我们一个Echo信息).


JSP 页面

下面是一个我们需要的页面代码 (echo.jsp) :
<%@ taglib uri="https://ajax4jsf.dev.java.net/ajax" prefix="a4j"%>
<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h"%>
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f"%>
<html>
    <head>
        <title>repeater</title>
    </head>
    <body>
        <f:view>
            <h:form>
                <h:inputText size="50" value="#{bean.text}" >
                    <a4j:support event="onkeyup" reRender="rep"/>
                </h:inputText>
                <h:outputText value="#{bean.text}" id="rep"/>
            </h:form>
        </f:view>
    </body>
</html>


    就如你看到的,唯一一行于常给JSF页面代码不同的就是下面的一行
    <a4j:support event="onkeyup" reRender="rep"/>

    在这里我们在父标签(<h:inputText>)中添加了一个AJAX 支持. 该支持绑定了JavaScript事件“onkeyup” .因此, 每一次该事件发布给父标签时,我们的程序将发送一个AJAX请求到Server.这意味着我们的受管理的bean将包含该“text” 域中我们输入的最新数据.

    <a4j:support> 标签的“reRender” 属性(attribute)定义我们的页面的哪一部分被更新. 在这里,该页面唯一被更新的部位是 <h:outputText> 标签,因为他的ID值和“reRender” 的属性值向匹配. 在一个页面中更新多个元素(elements)也是很简单的:仅仅把他们的IDs放在 “reRender” 属性中就可以了.
   
    当然了,为了运行这个程序我们还需要一个受管理的bean
    package demo;
    public class Bean {
        private String text;
       
        public Bean() {
        }
       
        public String getText() {
            return text;
        }
       
        public void setText(String text) {
            this.text = text;
        }
    }


faces-config.xml

    下一步, 我们需要在faces-config.xml 中注册上面的bean:
   
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE faces-config PUBLIC "-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.1//EN"
    "http://java.sun.com/dtd/web-facesconfig_1_1.dtd">
    <faces-config>
    <managed-bean>
        <managed-bean-name>bean</managed-bean-name>
        <managed-bean-class>demo.Bean</managed-bean-class>
        <managed-bean-scope>request</managed-bean-scope>
        <managed-property>
            <property-name>text</property-name>
        <value/>
        </managed-property>
    </managed-bean>
    </faces-config>
    注意:这里没有任何东西直接和Ajax4jsf 有关联.

Web.xml

    最后,不要忘了添加jar文件和更改 web.xml 文件:
   
    <?xml version="1.0"?>
    <web-app version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">
   
        <display-name>a4jEchoText</display-name>
   
        <context-param>
            <param-name>javax.faces.STATE_SAVING_METHOD</param-name>
            <param-value>server</param-value>
        </context-param>
   
        <filter>
            <display-name>Ajax4jsf Filter</display-name>
            <filter-name>ajax4jsf</filter-name>
            <filter-class>org.ajax4jsf.Filter</filter-class>
        </filter>
   
        <filter-mapping>
            <filter-name>ajax4jsf</filter-name>
            <servlet-name>Faces Servlet</servlet-name>
            <dispatcher>REQUEST</dispatcher>
            <dispatcher>FORWARD</dispatcher>
            <dispatcher>INCLUDE</dispatcher>
        </filter-mapping>
   
        <listener>
            <listener-class>
                com.sun.faces.config.ConfigureListener
            </listener-class>
        </listener>
       
        <!-- Faces Servlet -->
        <servlet>
            <servlet-name>Faces Servlet</servlet-name>
            <servlet-class>
                javax.faces.webapp.FacesServlet
            </servlet-class>
            <load-on-startup>1</load-on-startup>
        </servlet>
       
        <!-- Faces Servlet Mapping -->
        <servlet-mapping>
            <servlet-name>Faces Servlet</servlet-name>
            <url-pattern>*.jsf</url-pattern>
        </servlet-mapping>
       
        <login-config>
            <auth-method>BASIC</auth-method>
        </login-config>
    </web-app>
   
    就这样了, 现在你的程序应该可以工作了.


部署

    最终,你可以在Servlet容器中部署你的程序了. 在你喜欢的容器中部署,然后在你的浏览器中输入: http://localhost:8080/a4jEchoText/echo.jsf


Chapter 3.Ajax4jsf 框架中的基本概念

    Table of Contents
    Introduction
    Architecture Overview
    How To...
    Send an AJAX Request
    Decide What to Send
    Decide What to Change

介绍

    该框架被实现为使用一个组件库来添加ajax功能到你的页面中,而不要写js代码或者使用新的Ajax装饰器替换你已经做好的JSF组件. Ajax4jsf 具有页面范围(page-wide)的Ajax支持,而不是传统的组件范围(component-wide)的ajax支持.  这意味着你可以在页面中定义一个激活Ajax请求的事件,和当根据客户端事件触发Ajax请求来改变服务器端数据后如何使用JSF组件树来同步显示JSF页面. (This means you can define the event on the page that invokes an AJAX request and the areas of the page that should be synchronized with the JSF Component Tree after the AJAX request changes the data on the server according to the events fired on the client).


    下面的图片展示了它是如何工作的:



    Ajax4jsf 允许你定义(意味着通过JSF tags)你希望通过AJAX请求更新的JSF页面的不同部分并且提供的一些发送AJAX请求到服务器端的选项,除了你的JSF页面于常规的JSF有点不同外,没有其他的不同了,这是一个你不需要写JS代码和XMLHttpRequest对象的天堂.
结构概览
   
    下面的图片展示了Ajax4jsf 框架的一些重要的元素



    Ajax 过滤器(Filter).  为了得到应用 Ajax4jsf 的好处 你必须在在 web.xml 文件中注册一个Ajax Filter.该过滤器有一些职责. Ajax Filter 可以识别多种ajax请求种类. 图片3的序列图展示了在处理常规页面和AJAX请求页面的不同之处.在开始的情况下,所有的JSF树将被编码(encoded). 在第二种情况下依据AJAX 区域(region) (你可以通过使用<a4j:region> tag来定义AJAX region  )的大小(size). 就如你看到的,第二种情况下 过滤器将解析AJAX响应的内容,在它被发送到客户端以前, 查看下面的图片来理解这两种方式:

    在这两种情况下, 你的程序所需要的静态或者动态资源的信息将被注册到ResourseBuilder 类中.当请求一个资源时(图片4),AJAX filter 检查资源缓存(Resource Cache)看看这个资源是否存在,如果存在该资源将被送到客户端.否则过滤器将在ResourceBuilder中搜索注册的资源. 如果该资源被注册了,AJAX filter将发送一个请求到 ResourceBuilder来创建[create (deliver)]该资源.下面的图片显示了请求资源的处理过程.

    Ajax动作组件(Action Components).  有3个Ajax动作组件: AjaxCommandButton, AjaxCommandLink 和 AjaxSupport. 你可以使用他们从客户端发送AJAX请求.

    Ajax容器 (Containers).  AjaxContainer 是一个接口,该接口描述了在Ajax请求中应该被解码(decoded)的JSF页面中的一个区域.AjaxViewRoot 和 AjaxRegion 实现了该接口.

    JavaScript引擎 (Engine).  Ajax4jsf JavaScript 引擎 在客户端运行. 它知道如何根据来自于Ajax响应的信息来更新你JSF页面上的不同的区域. 程序开发者不需要直接使用这里的JavaScript代码.它自动的下载到客户端.



如何做...


    发送一个 AJAX 请求

    从JSF页面发送ajax请求有不同的方法. 你可以使用 <a4j:commandButton>, <a4j:commandLink> 或者 <a4j:support> tags.

    所有的这些标签隐藏了在创建一个XMHttpRequest 对象和发送ajax请求所需要的JavaScript 活动.并且, 他们允许你选择页面中那个JSF组件被重新渲染(re-rendered) 来表现Ajax响应的结果 (你可以列出他们的 IDs 在“reRender” 属性中).
    <a4j:commandButton> 和 <a4j:commandLink> tags 用来在 “onclick” JavaScript 事件中发送Ajax请求.
    在你选择JS事件(“onkeyup”, “onmouseover”, etc)时, <a4j:support> tag 允许你在普通的JSF组件中添加Ajax 功能和发送ajax请求.

    提供Ajax请求功能的大部分重要的属性如下:

    reRender 属性 - 就如我们前面提到过的,在一个Ajax响应到来时重新渲染(reRendered)组件.
    RequestDelay 属性 ? 用来调节请求的频率.
    <h:inputText size="50" value="#{bean.text}">
        <a4j:support event="onkeyup" RequestDelay=”3”/>
    </h:inputText>
   
    因此每一个来自于键盘事件的请求将会延迟3 ms ,来减少请求的次数.
    EventsQueue ? 储存下一个请求的队列的名字. 队列帮助阻止下一个请求知道当前的处理完.
    LimitToList 用来控制更新的区域. 设置为true ? 将更新仅在reRender list中的区域, 如果为false,将更新所有Output Panels区域.
    ajaxSingle 如果设置为false用来指定发送请求的区域  ? 如果为true则发送整个区域 - only control caused event.(attributes specify regions to be sent with request if false ? it’ll be full region in other case - only control caused event.)


决定发送什么


    你可能描述了一个你决定发送到服务器的页面区域.当你发送ajax请求的时候,通过这种方式你可以控制JSF View的那个部分在服务器端被解码(decoded).
    描述你JSF页面上的一个Ajax区域的最容易的方法是什么都不做.这是因为在<f:view> 和 </f:view> tags 中的内容在默认值的情况下认为是ajax区域.
    通过使用<a4j:region> tag你可以在一个JSF页面中定义多个Ajax区域 (they can even be nested).
    如果你希望渲染ajax响应以外的区域,那么renderRegionOnly属性值应该设置为false.否则ajax更新被限制在活动区域的元素中.

决定改变什么

    在大部分情况下都可以使用 “reRender”中的ids来定义需要更新的 “AJAX zones”.
    但是如果你的页面包含<f:verbatim/> tag(你希望在ajax响应中更新它的内容)你不可以使用这种方式.
    我们在上面描述的<f:verbatim/> tag 的问题涉及到JSF组件的transientFlag值. 如果该标记的值为true,这个组件不能参与保存和恢复组件树(saving or restoring)的处理过程.
    为了提供一种解决这个问题的方法, Ajax4jsf 利用<a4j:outputPanel> tag定义了一个output panel . 如果你把<f:verbatim/> tag放在output panel中, 那么在AJAX 响应中 <f:verbatim/> tag和其他panel中的child tags中的内容可以被更新 .有两种方法来控制它:
    设置“ajaxRendered” 属性值为true.
    设置动作组件的“reRender” 属性值为output panel的 ID.

Chapter 4. Ajax4JSF 组件库

    Table of Contents
    a4j:ajaxListener
    a4j:region
    a4j:page
    a4j:support
    a4j:commandLink
    a4j:commandButton
    a4j:outputPanel
    a4j:actionparam
    a4j:status
    a4j:loadBundle
    a4j:mediaOutput
    a4j:ajaxListener
   
    和 ActionListener或者ValueChangeListener的工作方式一样, 只是仅用于AJAX容器. 添加一个指定的类作为AjaxEvent的监听器. (sent in case of an AJAX request for this container).


Table 4.1. a4j:ajaxListener attributes

    type 注册到AjaxListener 中类的完全限定的Java类名

    <a4j:region selfRendered="true" ajaxListener="#{bean.processAjax}" id="Region">
        …
    </a4j:region>

    当来自于Region的AJAX request触发时,将调用bean的'processAjax'方法.

    a4j:region 该标签定义在AJax请求处理过程中被发送到服务器端解码的部分JSF组件树.
   
Table 4.2. a4j:region 的属性

    selfRendered 如果为true,在调用应用程序(InvokeApplication )阶段自渲染子树(如果immediate 属性设置为true则是 Decode)
    renderRegionOnly 标记,用来决定活动区域外的内容在Ajax响应中是否渲染.如果为"true" , 在AJAX response过程中活动区域外的组件都不渲染. 如果为"false", 将渲染包含在响应中的所有组件树.默认值为"true"
    rendered 如果为 false, 该组件将不被重新渲染.
    id 每个组件都应该有个唯一的id. 如果没有指定的话,将会自动产生.
    immediate 如果该组件被Ajax请求激活的话,标记该组件应该立即(在应用请求值阶段)被感兴趣的监听器和动作处理,而不是等到调用应用程序阶段.(译者注:该标记和JSF中的immediate标记所代表的意思差不多,跳过验证阶段到呈现响应阶段)
    binding 组件绑定ajaxListener 方法绑定,当该组件被ajax请求激活时,将调用该监听器方法处理该事件.该方法必须为public的并且接受一个 AjaxEvent 参数,返回void.

<a4j:region>
    <!--Some content-->
<a4j:region>