Getting started with the ICEfaces (1.5.2) library of rich AJAX JSF components in JDeveloper 10.1.3.x

November 2006 saw the announcement by ICEsoft that their ICEfaces library of JSF components was being released under an open source license. This basically means that a lot of rich, often AJAX powered components became much more readily available for JSF application developers. Next to for example ADF Faces/MyFaces Trinidad and MyFaces Tomahawk, ICEfaces is another set to pick components from. Note however:  ICEfaces does not mix freely within a JSF page with other JSF implementations. More on that later in this article. I decided to give ICEfaces a spin, watched the demos on http://component-showcase.icefaces.org/component-showcase/ and became convinced that the components were worth a second look. ICEfaces comes with a plugin for JDeveloper 10.1.3.x – since I am a happy JDeveloper user, that was to be my starting point. I will show you how to get a simple ICEfaces application running in no time at all (well, under 30 minutes). We will be using ICEfaces 1.5.2, which was released just days ago.

To get started with ICEfaces:

1. Go to http://www.icefaces.org/main/downloads/os-downloads.iface, Register (if this is your first visit – note: registering is free) or Login (for a returning visitor)

2. Download ICEfaces-v1.5.2-JDeveloper.zip by pressing the download button. Save the zip-file just anywhere on your drive (c:\temp will do nicely)

 

3. Fire up JDeveloper 10.1.3.1. Go to Help, Check for Updates. Choose install from local file. Then browse and select the ICEfaces-v1.5.2-JDeveloper.zip file you have downloaded from ICEfaces. Click Next and subsequently Finish at the first opportunity.

 

4. JDeveloper needs to be restarted. When that is done, the plugin is installed and ready to rock. (you may check to see either if there are new Libraries predefined or if the menu option ICEfaces Integration has been added to the RMB menu on projects).

 

5. Let’s now create a new Application and a new Project. 

 

 

6. Apparently, the ICEfaces Integration option in the Project’s RMB menu is only available for a Web Project. We can turn our project into a Web Project by creating a dummy JSF page: go to File, New and from Web Tier, JSF pick JSF JSP. Accept all defaults in the wizard that pops up.

 

7. Now when you go to the RMB menu on the MyFirstICEfaces project, the option ICEfaces Integration is enabled. Click on that option.  

 

Two things happen: the ICEfaces libraries are added to your project and some ICEfaces configuration details are added to the web.xml file. Or at least: that is what I thought should happen. For my project, it did not happen. So I opened the web.xml file and pasted in the following elements:

<context-param>
        <param-name>javax.faces.STATE_SAVING_METHOD</param-name>
        <param-value>server</param-value>
    </context-param>
    <context-param>
        <param-name>javax.faces.application.CONFIG_FILES</param-name>
        <param-value>/WEB-INF/faces-config.xml</param-value>
    </context-param>
    <servlet>
        <servlet-name>Persistent Faces Servlet</servlet-name>
        <servlet-class>com.icesoft.faces.webapp.xmlhttp.PersistentFacesServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet>
        <servlet-name>Blocking Servlet</servlet-name>
        <servlet-class>com.icesoft.faces.webapp.xmlhttp.BlockingServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet>
        <servlet-name>uploadServlet</servlet-name>
        <servlet-class>com.icesoft.faces.component.inputfile.FileUploadServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet>
        <servlet-name>Faces Servlet</servlet-name>
        <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>Persistent Faces Servlet</servlet-name>
        <url-pattern>/xmlhttp/*</url-pattern>
    </servlet-mapping>
    <servlet-mapping>
        <servlet-name>Persistent Faces Servlet</servlet-name>
        <url-pattern>*.iface</url-pattern>
    </servlet-mapping>
    <servlet-mapping>
        <servlet-name>Persistent Faces Servlet</servlet-name>
        <url-pattern>*.jspx</url-pattern>
    </servlet-mapping>
    <servlet-mapping>
        <servlet-name>Faces Servlet</servlet-name>
        <url-pattern>/faces/*</url-pattern>
    </servlet-mapping>
    <servlet-mapping>
        <servlet-name>Blocking Servlet</servlet-name>
        <url-pattern>/block/*</url-pattern>
    </servlet-mapping>
    <servlet-mapping>
        <servlet-name>uploadServlet</servlet-name>
        <url-pattern>/uploadHtml</url-pattern>
    </servlet-mapping> 

 

 8. Add the ICEfaces Taglibrary to the project. Double click on the MyFirstICEfaces project (or select Edit Project Properties) and go to JSP Tag Libraries. Click the Add button. Select the ICEfaces Component Suite 1.5.2 to add to the project.

 

9. Let’s create our first JSF page with ICEfaces components. Go to File, New and from Web Tier, JSF choose the option JSF JSP. The Create JSF JSP Page wizard opens. Call the file for example ICEfacesTabsDemo.jspx. Select the ICEfaces Taglibrary along with the JSF Core and JSF Html libraries.

 

 

The WYSIWYG JSP Editor opens – with a pretty much blank screen as we have not yet added any content to the page. Go to the source view. Move the namespace declarations on t
he jsp:root element to the f:view element. Then remove all
tags outside f:view (the elements jsp:root, jsp:output and jsp:directive.page). Next, add our very first ICEfaces element: ice:outputText. The page now looks as follows:

<f:view xmlns:h="http://java.sun.com/jsf/html"
          xmlns:f="http://java.sun.com/jsf/core"
          xmlns:ice="http://www.icesoft.com/icefaces/component">
    <html>
      <head>
        <meta http-equiv="Content-Type"
              content="text/html; charset=windows-1252"/>
        <title>MyFirst ICEfaces</title>
      </head>
      <body>
         <h:form>
           <ice:outputLabel value="Hello World" />
         </h:form>
      </body>
    </html>
  </f:view> 

We can also drag and drop ICEfaces components from the Component Palette onto the editor:

 

When we run this page, the browser opens up with the familiar:

 

A slightly more interesting ICEface component

 

<f:view xmlns:h="http://java.sun.com/jsf/html"
        xmlns:f="http://java.sun.com/jsf/core"
        xmlns:ice="http://www.icesoft.com/icefaces/component">
  <html>
    <head>
      <meta http-equiv="Content-Type"
            content="text/html; charset=windows-1252"/>
      <title>MyFirst ICEfaces</title>
      <link href="css/xp/xp.css" rel="stylesheet" type="text/css"/>
    </head>
    <body><ice:form style="width: 45%;">
        <ice:panelTabSet>
          <ice:panelTab label="Tab 1">
            <ice:outputText value="Other Content"/>
          </ice:panelTab>
          <ice:panelTab label="Tab 2">
            <ice:outputText value="Some Content"/>
          </ice:panelTab>
          <ice:panelTab label="Tab 3">
            <ice:outputText value="Empty"/>
          </ice:panelTab>
        </ice:panelTabSet>
      </ice:form></body>
  </html>
</f:view>
  
 

Mixing ICEfaces with other JSF libraries such as ADF Faces/MyFaces Trinidad and Apache MyFaces Tomahawk

ICEfaces components cannot be used in the same page as JSF components from other libraries. This is caused by the special ViewHandler used by ICEfaces in conjunction with its Dynamic (Ajax) Rendering architecture. It’s a shame, since my main JSF library is usually ADF Faces, but some components in ICEfaces make for interesting complements to ADF Faces.

It is possible to combine ICEfaces and other JSF implementations in the same web application. That means we can have pages containing a mix of ADF Faces and MyFaces Tomahawk for example as well as pages based in ICEfaces components. It has been suggested that using (I)FRAMES this opens up possibilities of still combining ADF Faces and ICEfaces in what at least appears to be a single page… It is also quite possible to open up pop-up window from an ADF Faces page that is based on ICEfaces and displays in the data context and using the underlying data as the ADF Faces page.

Note that the ICEfaces Faces Servlet is also mapped to the iface url extension (for example http://10.255.255.100:8988/MyFirstIICEfaces-MyFirstICEfaces-context-root/ICEfacesTabsDemo.iface). That allows us eventually to distinguish between jspx and iface which in turn makes it possible to mix in one web application both ICEfaces pages and for example pages built using ADF Faces or Apache MyFaces Tomahawk.

Resources

ICEfaces Tutorials: http://www.icefaces.org/main/resources/tutorials.iface .