by Tom Stamm
Figure 1. A sample customer data table
ICEfaces tooling is provided as an update to Workshop for WebLogic 10.1, and must be installed separately via an Eclipse update. To do this, run the software update tool in Workshop (found under Help->Software Updates-> Find and Install). Select "Search for new features to install," and click Next. Click New Remote Site, and enter the URL
http://dev2dev.bea.com/eclipse/icefaces-tooling/. Make sure that the new site is selected, and then click Finish. On the next wizard, make sure the archive file is selected, and then click Next. Accept the terms of the license, and click Next, and then Finish. When the Feature Verification screen appears, click Install All. After the update is finished, you will be prompted to restart Workshop for the changes to take effect.
Note: Because this update is adding a fragment to an existing plug-in, Workshop must be restarted with the
-clean option. This can either be added to the command line used to start Workshop, or to the
<BEA Home>/workshop_10.1/workshop4WP/workshop4WP.ini file before the
The ICEfaces tooling update includes a WTP project facet that installs the ICEfaces runtime libraries into a project and makes the required changes to the project's configuration files. The simplest way to create an ICEfaces-enabled project is to run the New Dynamic Web Project wizard (choose File->New->Project..., and then select Web/Dynamic Web Project as the project type). Enter a project name, and in the Configurations drop-down, select either ICEfaces Project or ICEfaces Project with WLS 10.0. The latter option will use WebLogic library modules for everything except ICEfaces itself. Click Next to review the facet selections, and then Next again to go through the individual library selections. For ICEfaces you will need to click the Add... button and download the latest ICEfaces library from the BEA Web site. Finally, click Finish to create the project.
You can now open the generated
web.xml to see that some changes have been made to support ICEfaces; in particular, the Persistent Faces Servlet and the Blocking Servlet entries have been added. These provide the server-side DOM rendering and asynchronous communications used by the ICEfaces runtime, respectively. A mapping has been added so that requests matching the pattern
*.iface will be routed to the ICEfaces servlet instead of the regular JSF servlet. This can be updated to
*.jsf, and the Sun JSF servlet can be removed, so that all faces requests will be handled by ICEfaces. This tutorial will use the default configuration and the
ICEfaces also requires that JSPs use XML namespace syntax when importing tag libraries, instead of the JSP taglib import directive. The ICEfaces runtime cannot parse JSP directives, and will throw an error if any are encountered. For example, the default page in your new Web application (
/WebContent/pages/welcome.jsp) has the following opening tag:
<f:view xmlns:f="#" xmlns:h="#" xmlns:ice="http://www.icesoft.com/icefaces/component">
Other tag libraries can be imported in a similar manner. The JSP editor currently generates only JSP taglib import directives, so if you drag a tag from a library in the palette that is not already imported, you must remove the generated import directive and add an equivalent XML namespace declaration. When creating new JSPs in this project, you can select the New ICEfaces JSP template in the new JSP wizard to generate pages using this syntax.
At this point, you can run
/WebContent/index.jsp, which will redirect to
/WebContent/pages/welcome.iface so that the welcome page will be executed using the ICEfaces servlet. The default contents of the welcome page is not that exciting, so now you'll add some functionality.
The first thing you'll add is a data table. This will be very similar to the JSF data table, and, in fact, the ICEfaces
dataTable tag is a superset of the JSF HTML
dataTable tag. However, by using the ICEfaces extensions and a few extra tags, this table will have features like sorting and scrolling between pages without requiring a full page refresh.
To support this example, you must first import some files (found in
imports.zip in the Download section) into your project. Right-click your project in the Project Explorer, select Import->Import..., and choose Archive File. In the next screen, browse to
imports.zip, select all files, make sure that the Into Folder: textbox is showing your project name, and click Finish. This will import the packages
businessObjects into your project's
src directory, as well as some stylesheets and images into the
The classes in the
businessObjects package are simple POJOs that represent Customer data. The
beans.CustomerBean class will be registered as a JSF bean, and provides some sample Customer data, as well as some application control logic. In a real application this bean could query a database for the Customer data, but here it is all hard-coded. After importing the source code, the
CustomerBean must be registered in the faces configuration file. To do this, open
/WebContent/WEB-INF/config/faces-config.xml. Right-click Managed Beans, and select New Managed Bean. Enter
customers as the name of the bean, change the scope to
session, and enter
beans.CustomerBean as the bean type. Click Finish, and then save the file.
Now, open the welcome page (
/WebContent/pages/welcome.jsp). For this example, all of the functionality will be contained in this page, and all interaction with the server will happen asynchronously, with no page refreshes, after the initial page load. To get started, delete everything inside the
body tags, so that you can start with an empty page.
An important part of pages that use ICEfaces widgets is the stylesheet reference:
<link href="./xmlhttp/css/xp/xp.css" rel="stylesheet" type="text/css" />
This stylesheet is part of the ICEfaces runtime and provides default styles for some of the widgets. Because it is part of the runtime, it does not need to be copied into each ICEfaces webapp. Most tags have
styleClass attributes so that you can override the defaults, but this example sticks with the provided styles. Note that it is served up by the
xmlhttp servlet, which is also part of the ICEfaces runtime. Because the Workshop tooling is not aware of what this servlet has access to, you'll see a warning that the stylesheet cannot be found; this can be safely ignored.
The interface for our application will have two tabs: one to display data, and one that contains a form to add data. This is provided by the ICEfaces
panelTabSet tag. A
panelTabSet must be wrapped in a
form tag, so first drag a
form tag from the ICEfaces section of the palette onto the page. The form does not need an id or any other attributes. Then drag a
panelTabSet tag and drop it inside the form. A dialog will pop up. Click the "..." button next to "Tab items" to add tabs. We'll need one with an id of
viewTab labeled View, and one with an id of
addTab labeled Add. Also, set the style class to
componentPanelTabSetLayout. The resulting code should look like this:
<ice:form> <ice:panelTabSet var="" styleClass="componentPanelTabSetLayout"> <ice:panelTab id="viewTab" label="View"> </ice:panelTab> <ice:panelTab id="addTab" label="Add"> </ice:panelTab> </ice:panelTabSet> </ice:form>
You can add some text in each tab and run the page to verify that it's working. Make sure you either invoke the page as
/pages/welcome.iface, or run
/index.jsp, so that it will be executed by the ICEfaces servlet.
Now you'll add a data table to the first tab that will databind to the list of
Customer objects provided by the backing bean. The table will include clickable headers that will sort the data, and will have a paginator control to move through pages of data. The final result can be found in the Download section within
project.zip. The completed project can be imported into a clean workspace by using File->Import, selecting "Existing Projects into Workspace," and choosing the "Select archive file" option to select the downloaded zip file. This section will go over some of the major points in the project.
To create the table, drag a
dataTable tag onto the first tab in the tabset. When the table dialog pops up, choose the
customers property of the
customers JSF managed bean as the enumerable, and name the iteration variable "customer." The dialog should automatically recognize the type as
businessObjects.Customer. This is the variable that will be referred to in the table columns. Click Next, and select the
last properties to display, and then click Next to order them. This will generate a basic table, similar to a plain JSF dataTable. You can also select some of the address properties to display if you want. Using the smart editor, set the id of the table to
custTable so that you can refer to it later, and set the
rows attribute to 5 so that it will not show too many rows at once.
Now you can add sorting. Drag a
commandSortHeader tag into the header facet of the
id column, call the column name "id," and click the "arrow" checkbox so that the sort order will be indicated. Next, move the
outputText tag with the column name inside the
commandSortHeader tag. Do the same for the
last column, naming it "LastName," so that the table will be sortable for customer id and last name. ICEfaces depends on the backing bean to enable sorting; the bean keeps track of what column the data should sort on, and knows how to sort the data based on that column and which direction it should be sorted. When the
customers property is accessed by the data table, it will return a presorted list. In this example, the bean is simply sorting an internal list; if it was executing a query against a database, it might specify the sort in the query. To wire this up you need to databind the
sortColumn attribute of the data table to the
sortColumnName property of the backing bean, and the
sortAscending attribute to the
sortAscending property of the backing bean. This can be done with the smart editor by clicking the button next to each property, and browsing to the bean.
Pages: 1, 2