RichFaces开发指南3.3.3
1 介绍
RichFaces是一个开源框架,它不借助于JavaScript而增加Ajax能力到存在的JSF应用程序中。
RichFaces利用了JavaServer Faces框架,包括生命周期,验证,转换工具,以及静态和动态的资源管理。具用内建Ajax 支持和高度可定制观感的RichFaces组件能够容易地被纳入到JSF应用程序中。
RichFaces准许:
l 强化了整套JSF的好处,而且与Ajax一起工作。RichFaces完全集成到了JSF的生命周期内。虽然其它框架只给了你存取管理的beans的工具,而RichFaces在Ajax请求响应周期的时候,却促进了动作和值改变的侦听器,以及调用服务器边的验证和转换。
l 增加了Ajax能力到存在的JSF应用程序中。框架提供了两个组件库(Core Ajax 和 UI)。Core库设置Ajax功能到存在的页面,所以不需要编写任何JavaScript代码或者用新的Ajax组件替换存在的组件。RichFaces启用页面范围的Ajax支持,而不是传统的组件范围的支持,并且它给了在页面上定义事件的机会。 一个事件调用一个Ajax请求,并且在由根据客户端引发的事件的Ajax请求改变了在服务器上的数据之后,变成为同步于JSF组件树的页面区域。
l 快速创建基于开箱即用的组件的复杂视图。RichFaces UI库包含组件,用于添加富裕用户界面的功能到JSF应用程序。它扩展了RichFaces框架,包含了大量(不断增长的)强大的富裕的Ajax可用的带有广泛皮肤支持的组件的集合。
l 利用内建Ajax支持编写你自己的定制富裕组件。我们始终致力于组件开发包(CDK)的改善,它用于RichFaces UI库的创建。CDK包括了一个代码生成工具和一个使用了类似于JSP语法的模板工具。这些工具帮助避免了创建组件的常规流程。组件工厂就象一个运行良好的机器,允许创建一流的带有Ajax功能的富裕组件,比用传统编码方式的手段创建的简单组件要容易的多。
l 使用java类打包资源。除了它的核心,RichFaces的Ajax功能提供一个高级支持,用于不同的资源管理:图片、JavaScript代码和CSS样式表。资源框架可以容易地使得你的资源连同你定制组件的代码一起打包到jar文件中。
l 快速轻松地生成二进制资源。资源框架可以快速地生成图象、声音、Excel电子表格等等,因此,例如,使用“Java Graphics2D”库熟悉的方法创建图象成为可能。
l 利用基于皮肤的技术,创建一个现代的富裕的用户界面的观感。RichFaces提供了一个可换肤的功能,它允许你容易定义和管理色彩方案,以及其他带有命名皮肤参数帮助的UI参数。因此,可以从JSP代码或JAVA代码访问这些皮肤参数(例如,调整基于UI文本部分生成的快速图象)。RichFaces自带大量的让你着手的预定义皮肤,但是你也可以轻松地创建你自己的定制皮肤。
l 让你同时测试和创建组件、动作、侦听器和页面。一个自动测试工具是在我们将来不久的发展蓝图中。这个工具会生成测试案例,用于你尽可能快地开发你的组件。测试框架不仅测试组件,而且也用于任何其他服务边或者客户端的包含JavaScript代码的功能。此外,它不用部署测试应用程序到Servlet容器中就会做这一切。
RichFaces UI组件成为了准备就绪开箱即用,因此,节约了开发者的时间,并且立刻得到上面提及的在网页应用程序创建中的功能的好处。所以,可以更快、更轻松地获得使用的经验。
2 技术要求
开发RichFaces使用了一个开放的体系结构,可以最广泛地兼容各种环境。
下面是你开始运行RichFaces 3.3.3需要的东西:
1 Java
2 JavaServer Faces
3 Java 应用程序服务器或servlet容器
4 浏览器(在客户边)
5 RichFaces框架
2.1 支持的java版本
1 JDK 1.5 或更高
2.2 支持的JavaServer Faces实现和框架
1 Sun JSF-RI - 1.2_x (1.2_14 recommended), 2.x
2 MyFaces 1.2.x (1.2.5 recommended), 2.x
3 Facelets 1.1.x
4 Seam 2.x
2.3 支持的服务器
1 Apache Tomcat 5.5 - 6.0
2 BEA WebLogic 9.1 - 10.0
3 Resin 3.1.x
4 Jetty 6.1.x
5 Sun Application Server 9 (J5EE)
6 Glassfish V2, V3
7 JBoss 4.2.x - 5
8 Websphere 7.0. 或更高
9 Geronimo 2.0或更高
2.4 支持的浏览器
Linux环境:
1 Firefox 3.0或更高
2 Opera 9.5或更高r
Windows环境:
1 Firefox 3.0或更高
2 Google Chrome
3 Internet Explorer 6.0或更高
4 Opera 9.5或更高
5 Safari 3.0或更高
Mac OS环境
1 Safari 3.0或更高
2 Firefox 3.5或更高
这个列表是基于我们的用户的报告构成。我们假设这个列表不完整,并在该列表缺少你的环境,但并不意味着不兼容.
我们感激你反馈有关不在该列表中的,但与RichFaces兼容的平台和浏览器。帮助我们保持列表的更新
3 RichFaces入门
本章描述所有必要的行为和应该做的配置,用于将RichFaces组件插入到一个JSF应用程序中。该描述依靠一个简单JSF,它具有RichFaces应用程序从下载库到在浏览器中运行应用程序的创建过程。在这里描述的应用程序创建过程是通用的,并不依赖于使用的IDE。
3.1 下载RichFaces
最新的RichFaces组件发行版可以在JBoss社区下载: [http://labs.jboss.com/jbossrichfaces/downloads]。二进制文件(这里是以*.bin.zip或 *.bin.tar.gz档案形式上传的)包含编译的,准备使用的带有基本皮肤集的RichFaces版本。
要开始使用RichFaces,在计算机文件系统创建一个名为“RichFaces”的文件夹,下载并在这里解压二进制文件。
对那些希望下载并自己编译RichFaces的人,在JBoss社区有一篇文章,它描述RichFaces的知识库的结构概要[http://www.jboss.org/community/docs/DOC-11864],以及操作它的一些情况。
3.2 使用RichFaces的简单的JSF应用程序
简单的应用程序RichFaces Greeter,类似于hello-world应用程序,但有一点不同:RichFaces的世界会首先对用户说:“Hello!”。
使用所有必要的库创建标准的JSF 1.2项目;命名项目为“Greeter”,并遵循描述。
3.2.1 添加RichFaces库到项目
去到早先解码RichFaces二进制文件的文件夹,并打开lib文件夹。这个文件夹包含三个*.jar,它们是API,UI和实现库。拷贝lib文件夹的jars到“Greeter”JSF应用程序的WEB-INF/lib文件夹中。
[重要: 使用RichFaces的JSF应用程序假定下列包可用于项目中:commons-beanutils-1.7.0.jar, commons-collections-3.2.jar, commons-digester-1.8.jar, commons-logging-1.0.4.jar, jhighlight-1.0.jar
]
3.2.2 在web.xml中注册RichFaces
在RichFaces的库添加到项目内后,需要在web.xml中注册它们。在web.xml添加下列行:
...
<!-- Plugging the "Blue Sky" skin into the project -->
<context-param>
<param-name>org.richfaces.SKIN</param-name>
<param-value>blueSky</param-value>
</context-param>
<!-- Making the RichFaces skin spread to standard HTML controls -->
<context-param>
<param-name>org.richfaces.CONTROL_SKINNING</param-name>
<param-value>enable</param-value>
</context-param>
<!-- Defining and mapping the RichFaces filter -->
<filter>
<display-name>RichFaces Filter</display-name>
<filter-name>richfaces</filter-name>
<filter-class>org.ajax4jsf.Filter</filter-class>
</filter>
<filter-mapping>
<filter-name>richfaces</filter-name>
<servlet-name>Faces Servlet</servlet-name>
<dispatcher>REQUEST</dispatcher>
<dispatcher>FORWARD</dispatcher>
<dispatcher>INCLUDE</dispatcher>
</filter-mapping>
...
有关如何操作RichFaces的皮肤的详情见“换肤”章节。
web.xml最终结果如下:
<?xml version="1.0"?>
<web-app version="2.5"
xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/
javaee/web-app_2_5.xsd">
<display-name>Greeter</display-name>
<context-param>
<param-name>javax.faces.STATE_SAVING_METHOD</param-name>
<param-value>server</param-value>
</context-param>
<context-param>
<param-name>org.richfaces.SKIN</param-name>
<param-value>blueSky</param-value>
</context-param>
<context-param>
<param-name>org.richfaces.CONTROL_SKINNING</param-name>
<param-value>enable</param-value>
</context-param>
<filter>
<display-name>RichFaces Filter</display-name>
<filter-name>richfaces</filter-name>
<filter-class>org.ajax4jsf.Filter</filter-class>
</filter>
<filter-mapping>
<filter-name>richfaces</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>
3.2.3 管理的bean
“RichFaces Greeter”应用程序需要一个管理的bean。在项目的JavaSource文件夹中的demo包中创建一个名为user的管理的bean。代码如下:
package demo;
public class user {
private String name="";
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
}
3.2.4 在faces-cofig.xml注册bean
接下来user bean应该在faces-config.xml文件中被注册:
<?xml version="1.0" encoding="UTF-8"?>
<faces-config version="1.2"
xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/
ns/javaee/web-facesconfig_1_2.xsd">
<managed-bean>
<description>UsernName Bean</description>
<managed-bean-name>user</managed-bean-name>
<managed-bean-class>demo.user</managed-bean-class>
<managed-bean-scope>request</managed-bean-scope>
<managed-property>
<property-name>name</property-name>
<property-class>java.lang.String</property-class>
<value/>
</managed-property>
</managed-bean>
</faces-config>
3.2.5 RichFaces Greeter index.jsp
“RichFaces Greete”应用程序只有一个JSP页面。在WEB CONTENT文件夹的根部创建index.jsp页面,内容如下:
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %>
<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %>
<!-- RichFaces tag library declaration -->
<%@ taglib uri="http://richfaces.org/a4j" prefix="a4j"%>
<%@ taglib uri="http://richfaces.org/rich" prefix="rich"%>
<html>
<head>
<title>RichFaces Greeter</title>
</head>
<body>
<f:view>
<a4j:form>
<rich:panel header="RichFaces Greeter" style="width: 315px">
<h:outputText value="Your name: " />
<h:inputText value="#{user.name}" >
<f:validateLength minimum="1" maximum="30" />
</h:inputText>
<a4j:commandButton value="Get greeting" reRender="greeting" />
<h:panelGroup id="greeting" >
<h:outputText value="Hello, " rendered="#{not empty user.name}" />
<h:outputText value="#{user.name}" />
<h:outputText value="!" rendered="#{not empty user.name}" />
</h:panelGroup>
</rich:panel>
</a4j:form>
</f:view>
</body>
</html>
应用程序使用了三个RichFaces组件:<rich:panel>用来作为信息的可视化容器;带有内建Ajax 支持的<a4j:commandButton>允许在响应返回之后,动态地显示一个问候;<a4j:form>帮助按钮执行动作。
注意,RichFaces标签库应该在每个JSP页面声明。
对Facelets,你应该添加下列行,用于标签库的声明:
<ui:composition xmlns="http://www.w3.org/1999/xhtml"
xmlns:ui="http://java.sun.com/jsf/facelets"
xmlns:a4j="http://richfaces.org/a4j"
xmlns:rich="http://richfaces.org/rich">
...
</ui:composition>
好了!在服务器上运行该应用程序。在你的浏览器中输入: http://localhost:8080/Greeter/index.jsf,结果如下:
3.3 集成RichFaces到Maven项目
本节我们将告诉你如何使用Maven,创建一个带有RichFaces的简单的JSF应用程序。
首先,你需要确保你在本地机器上安装了Maven。我们将在Tomcat 6.0服务器上运行该JSF应用程序,所以,如果你还没有这样估,请下载并安装它。
现在我们可以继续创建应用程序了。要创建项目结构,并用最小的内容填充它,我们将使用“maven-archetype-jsfwebapp” Maven原型,它是RichFaces CDK的一部分。
“maven-archetype-jsfwebapp”原型和项目自身要求提供额外的知识库,即“http://snapshots.jboss.org/maven2/”和“http://repository.jboss.com/maven2/”。要使知识库对Maven成为可见的,最容易的方法是在“maven_installation_folder/conf/settings.xml”的<profiles>元素中创建一个配置。内容如下:
<profile>
<id>jsf-app-profile</id>
<repositories>
<repository>
<releases>
<enabled>true</enabled>
</releases>
<snapshots>
<enabled>true</enabled>
<updatePolicy>always</updatePolicy>
</snapshots>
<id>snapshots.jboss.org</id>
<name>Snapshot Jboss Repository for Maven</name>
<url>http://snapshots.jboss.org/maven2/</url>
<layout>default</layout>
</repository>
<repository>
<releases>
<enabled>true</enabled>
</releases>
<snapshots>
<enabled>true</enabled>
<updatePolicy>always</updatePolicy>
</snapshots>
<id>repository.jboss.com</id>
<name>Jboss Repository for Maven</name>
<url>http://repository.jboss.com/maven2/</url>
<layout>default</layout>
</repository>
</repositories>
</profile>
当配置被添加后,你需要在<activeProfiles>元素中激活它,如下所示:
<activeProfiles>
<activeProfile>jsf-app-profile</activeProfile>
</activeProfiles>
...
现在,我们有了使用“maven-archetype-jsfwebapp”原型创建项目的一切了。创建一个文件夹,它将收藏你的项目。然后,在它里面运行下面的命令:
...
mvn archetype:generate -DarchetypeGroupId=org.richfaces.cdk -DarchetypeArtifactId=maven-
archetype-jsfwebapp -DarchetypeVersion=3.3.3-SNAPSHOT -DgroupId=org.docs.richfaces -
DartifactId=jsf-app
...
你可以调整命令的一些参数。
参数 | 描述 |
-DgroupId | 定义用于管理的bean的包。 |
-DartifactId | 定义项目的名字 |
这个命令生成的一个JSF项目,结构如下:
jsf-app
|-- pom.xml
`-- src
|-- main
| |-- java
| | `-- org
| | `-- docs
| | `-- richfaces
| | `-- Bean.java
| |-- resources
| `-- webapp
| |-- WEB-INF
| | |-- faces-config.xml
| | `-- web.xml
| |-- index.jsp
| `-- pages
| |-- index.jsp
| `-- index.xhtml
`-- test
`-- java
`-- org
`-- docs
`-- richfaces
`-- BeanTest.java
现在,进入“jsf-app”文件夹,它包含了一个项目描述符(pom.xml)。打开项目描述符,编辑并添加依赖关系到<dependencies>元素。如下所示:
...
<dependencies>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>3.8.1</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>javax.servlet</groupId>
<artifactId>servlet-api</artifactId>
<version>2.4</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>javax.servlet</groupId>
<artifactId>jsp-api</artifactId>
<version>2.0</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>jstl</groupId>
<artifactId>jstl</artifactId>
<version>1.1.2</version>
</dependency>
<dependency>
<groupId>javax.servlet.jsp</groupId>
<artifactId>jsp-api</artifactId>
<version>2.1</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>javax.faces</groupId>
<artifactId>jsf-api</artifactId>
<version>1.2_12</version>
</dependency>
<dependency>
<groupId>javax.faces</groupId>
<artifactId>jsf-impl</artifactId>
<version>1.2_12</version>
</dependency>
<dependency>
<groupId>javax.el</groupId>
<artifactId>el-api</artifactId>
<version>1.0</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>el-impl</groupId>
<artifactId>el-impl</artifactId>
<version>1.0</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>javax.annotation</groupId>
<artifactId>jsr250-api</artifactId>
<version>1.0</version>
</dependency>
<!-- RichFaces libraries -->
<dependency>
<groupId>org.richfaces.framework</groupId>
<artifactId>richfaces-api</artifactId>
<version>3.3.3-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>org.richfaces.framework</groupId>
<artifactId>richfaces-impl</artifactId>
<version>3.3.3-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>org.richfaces.ui</groupId>
<artifactId>richfaces-ui</artifactId>
<version>3.3.3-SNAPSHOT</version>
</dependency>
</dependencies>
...
最后三个依赖关系添加RichFaces库到项目。你现在可以用mvn install命令构建项目。
当看见“BUILD SUCCESSFUL”消息时,项目已被装配,就可以导入IDE和运行在服务器上了。
使用命令mvn eclipse:eclipse -Dwtpversion=2.0,可以为Eclipse IDE构建项目。
然后你可以导入项目到Eclipse。在导入Eclipse之后,你可以打开“jsf-app/src/main/
webapp/WEB-INF/web.xml”,并根据指南的“在web.xml中注册RichFaces”的章节所列内容的配置它。
配置了项目,现在你可以开始使用RichFaces。打开“jsf-app/src/main/webapp/pages/index.jsp”文件,并添加标签库声明:
...
<%@ taglib uri="http://richfaces.org/rich" prefix="rich"%>
...
添加一些RichFaces组件到index.jsp页面,如<rich:calendar>实例。如下所示:
...
<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %>
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f"%>
<%@ taglib uri="http://richfaces.org/rich" prefix="rich"%>
<html>
<head>
<title>JSF Application with RichFaces built by Maven</title>
</head>
<body>
<f:view>
<rich:calendar />
</f:view>
</body>
</html>
...
现在,在Tomcat服务器上运行应用程序,在你喜爱的浏览器中输入“http://localhost:8080/jsf-app/”打开它。
3.4 相关的资源连接
The Photo Album Application [http://livedemo.exadel.com/photoalbum],使用RichFaces设计和开发。
Maven Resource Dependency Plugin Reference
[http://www.jboss.org/community/wiki/MavenResourceDependencyPluginReference],该文章讨论了插件的配置和使用。
JBoss Developer Studio
[https://www.redhat.com/apps/store/developers/jboss_developer_studio.html],带有一个RichFaces组件框架的紧密集成。 下面的链接可能对那些已使用IDE和RichFaces开发应用程序的人和那些希望改善开发流程的人是有用的。
1 Rich 组件
[http://download.jboss.org/jbosstools/nightly-docs/en/GettingStartedGuide/html/first_seam.html#rich_components] 。
在“JBoss Developer Studio指南”中的“Rich组件”章节,描述了如何添加RichFaces组件进入到一个CRUD应用程序;
2 JBoss工具箱 [http://download.jboss.org/jbosstools/nightly-docs/en/jsf/html/palette.html] 。
在“可视网页工具参考指南”中的“JBoss工具箱”章节,描述了用于包含RichFaces应用程序的快速、方便的页面制作处理的特定工具箱(连同JBDS一起)的优势;
3 开发网页应用程序的RichFaces工具包
[http://docs.jboss.org/tools/movies/demos/rich_faces_demo/rich_faces_demo.htm]
这个视频教程演示了与JBoss Developer Studio交互,同时又操作RichFaces的某些方面的内容;
1. 如何为RichFaces配置Maven
[http://docs.jboss.org/tools/movies/demos/rich_faces_demo/rich_faces_demo.htm]
该文章简洁地讨论了用于RichFaces的Maven配置;
1 RichFaces发布步骤[http://www.jboss.org/community/docs/DOC-13446]
该文章描述了RichFaces发布构建如何制作;
RichFaces installing and configuration
[http://www.jboss.org/community/wiki/RichFacesinstallingandconfiguration], 阅读该文章会找到如何集成RichFaces和Trinidad ,以及在JBoss服务器上启动RichFaces例子时可以发生的问题。