Getting Started with ICEfaces in Workshop for WebLogic

by Tom Stamm
07/16/2007

Abstract

ICEsoft's ICEfaces framework provides a way to Ajax-enable standard JavaServer Faces (JSF) applications without writing custom client-side Javascript code. This is a short introduction to using the ICEfaces tooling add-on for BEA Workshop for WebLogic. This tutorial covers installing the ICEfaces tooling, creating an ICEfaces-enabled project, and using ICEfaces and JSF to easily create an Ajax-enabled application to display and enter data. Because ICEfaces is adding Ajax capabilities to the regular JSF programming model, it is assumed that you have some familiarity with JSF.

Introduction

The ICEfaces framework builds on the JSF component model to provide a server-centric way of creating rich Internet applications. During the regular JSF component lifecycle, events are handled, components are created, and an HTML DOM rendering of the page is created on the server. When using ICEfaces, the server components can respond to actions and cause pieces of the DOM to be changed and rerendered. Then, rather than reloading the entire page, the changed parts of the DOM are sent back to the client and only the corresponding sections of the page are updated. This can happen via an asynchronous request, initiated by the client, or by a server "push." Using a Javascript debugger such as FireBug, you can watch the messages that are sent back and forth during these updates. ICEfaces provides implementations of all core JSF components, as well as some others that take advantage of asynchronous updates. In this tutorial, you'll use a tab control, a data table that can do dynamic sorting and pagination, and a modal pop-up dialog. Figure 1 shows what the finished application will look like.

Datatable-Runtime
Figure 1. A sample customer data table

Installing ICEfaces Support

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 -vmargs line.

Creating an ICEfaces-enabled Project

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 *.faces or *.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 .iface extension.

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.

Using ICEfaces to Display Data

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 beans and businessObjects into your project's src directory, as well as some stylesheets and images into the WebContent directory.

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 style and 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 first, id, and 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

Next Page »