How To Use ADF Faces With JDeveloper 10g

An Oracle JDeveloper How To Document (EA10)
Written by Jonas Jacobi & Poh Lee Tan, Oracle Corporation
September, 2004

Index

Introduction

ADF Faces is the Oracle Application Development Framework (ADF) view technology based on JavaServer Faces (JSF). Although JDeveloper 10g's complete and enhanced support for ADF Faces development will be provided in post 10g releases, it is still possible to productively do ADF Faces development in JDeveloper 10g. This document describes how to install and work with ADF Faces Early Access Release in JDeveloper 10g.

Oracle ADF Faces is a rich set of user interface components based on the new JavaServer Faces JSR (JSR-127). Oracle has been actively involved in this JSR since its beginning. The Oracle ADF Faces Components provide various user-interface components with built-in functionality - such as List-Of-Values, Table, hGrid, Color Picker, and Calendar - that can be customized and re-used in your application.

ADF Faces ensures a consistent look and feel for your application, allowing you to focus more on user interface interaction rather than look and feel compliance. The components support multi-language and translation implementation as well as accessibility features. ADF Faces Components use Partial Page Rendering (PPR) offering superior runtime interactivity. PPR allow the browser to just render a piece of a page instead of the entire page.

The intention with this early access release is to give developers and architects an opportunity to evaluate JSF and Oracle's JSF component offering.

Prerequisites

The dependencies of ADF Faces include:

  • JSF 1.1 reference implementation, and its dependencies. To install and register the JSF JSP tag libraries with JDeveloper, see How To Use JSF with JDeveloper 10g.
  • JSTL 1.0. This is already part of JDeveloper.

How to install the ADF Faces libraries into JDeveloper

Creating an "ADF Faces " Library and registering the ADF Faces tag libraries

  1. Download the adf-faces-ea10.zip from here. Unzip this file to a separate directory such as d:\adffaces. This directory will contain the subdirectories docs, lib, and src, and the adf-faces-demo.zip. The lib directory will contain the required jar files and tld (tag library descriptors) files for JDeveloper to work with ADF Faces.
  2. Create a JDeveloper "ADF Faces " library to manage the required ADF Faces jar files in JDeveloper.
    • Select Tools-> Manage Libraries from the main menu.
    • Select the "Libraries" tab.
    • Select the "System Libraries" node and click "New".
    • Name the library "ADF Faces ".
    • For "Class Path:" click "Edit..." and add all of the jar files: adf-faces-api.jar, adf-faces-impl.jar, and share-1_1_18.jar located in your ADF Faces lib directory: "d:\adffaces\lib".
  3. Now register the ADF Faces tag libraries with JDeveloper and add them to the Component Palette.
    • Again, select Tools-> Manage Libraries from the menu.
    • This time select the "JSP Tag Libraries" tab and click "New".
    • Add the " ADF Faces Core" tag library by specifying the following:
      • TLD File: D:\adffaces\lib\adf-faces-impl.jar\WEB-INF\af.tld (Use the Browse button to locate the ADF Faces Core tld in adf-faces-impl.jar.)
      • Libraries: ADF Faces (Click on the Browse button and select your new "ADF Faces" library.)
      • URI: http://xmlns.oracle.com/adf/faces/EA10 (Should be autofilled)
      • Prefix: af
    • Leave the "Execute Tags in JSP Visual Editor" checkbox unchecked and click "OK".
    • Answer " Yes" to the dialog asking to add the tag library to the Component Palette.
    • Name the Palette Page name: " ADF Faces Core". (You can edit the combobox.)
  4. Repeat this process to add the second " ADF Faces HTML" tag library with the following:
    • Select Tools-> Manage Libraries, choose the "JSP Tag Libraries" tab and click "New".
      • TLD File: D:\adffaces\lib\adf-faces-impl.jar\WEB-INF\afh.tld (Use the Browse button to locate the ADF Faces HTML tld in adf-faces-impl.jar.)
      • Libraries: ADF Faces (Click Browse and select the same ADF Faces library as before.)
      • URI: http://xmlns.oracle.com/adf/faces/EA10/html (Should be autofilled)
      • Prefix: afh
    • Leave the "Execute Tags in JSP Visual Editor" checkbox unchecked and click "OK".
    • Answer "Yes" to the dialog asking to add the tag library to the Component Palette, and this time specify the Palette Page name as: " ADF Faces HTML".

      Note: WYSIWYG visual editing for ADF Faces is not yet available in JDeveloper, but is being worked on for an upcoming production release of JDeveloper.
       
  5. That's it, you're done! You've just configured JDeveloper 10g to work with ADF Faces. The next step is to configure a project to use ADF Faces.

How to configure a project to use ADF Faces

To start building an ADF Faces application, you will need to configure a project's web.xml and include a starter faces-config.xml file and a starter adf-faces-config.xml file.

  1. To get started you'll need an Application Workspace containing an empty project:
    • Select File->New...->General->Application Workspace.
    • Name the workspace "adf_app" and accept the defaults for Directory Name: and Application Package Prefix:.
    • For Application Template:, choose "No Template [All Technologies]".
    • Click OK to proceed.
    • A new Application Workspace along with an empty Project (named "Project") will be generated. You can use it for your ADF Faces application. (You may rename it to "adftest" using File->Rename...)
  2. In the project, create a new JSP.
    • File->New...->Web-Tier->JavaServer Pages->JSP Page.
    • Name it "helloadffaces.jsp". This will also generate a web.xml file in the project's WEB-INF directory.
  3. In the Application Navigator, locate the web.xml file and double-click to edit it.
  4. Add the following after the <description>..</description> tags in your web.xml:
  5. <!-- Faces Servlet -->
    <servlet>
      <servlet-name>faces</servlet-name>
      <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
    </servlet>

    <!-- Faces Servlet Mapping -->
    <servlet-mapping>
      <servlet-name>faces</servlet-name>
      <url-pattern>/faces/*</url-pattern>
    </servlet-mapping>

    Note: You can actually use any Faces servlet mapping. For example: <url-pattern>*.faces</url-pattern>.

  6. Now create a faces-config.xml file in the same location as your web.xml. Create a new simple file:
    • Select File->New->General->Simple File...
  7. Name the file faces-config.xml and use the Browse... button to specify its location in your project's WEB-INF directory.
  8. Copy and paste the content below into your new faces-config.xml file:
  9. <?xml version="1.0"?>
    <!DOCTYPE faces-config PUBLIC
    "-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.0//EN"
    "http://bit.ly/199R3Wz">

    <faces-config>

    </faces-config>

  10. Now create an adf-faces-config.xml file in the same location as your web.xml. Create a new simple file:
    • Select File->New->General->Simple File...
  11. Name the file adf-faces-config.xml and use the Browse... button to specify its location in your project's WEB-INF directory.
  12. Copy and paste the content below into your new adf-faces-config.xml file:
  13. <?xml version="1.0"?>

    <adf-faces-config xmlns="http://xmlns.oracle.com/adf/view/faces/config">

      <debug-output>true</debug-output>
      <accessibility-mode>#{prefs.proxy.accessibilityMode}</accessibility-mode>
      <look-and-feel>#{prefs.proxy.lookAndFeel}</look-and-feel>

    </adf-faces-config>

  14. That's it! Your project is configured to work with ADF Faces.

Installing the ADF Faces installable resources

ADF Faces makes use of its own images, JSPs, Javascript libraries, and style sheets. These files are distributed in the adf-faces-install.zip file. Unzip the installable files into the root directory of the web application (public_html). This should create the following directories:

  • public_html\adf\images
  • public_html\adf\jsLibs
  • public_html\adf\styles

Creating a simple ADF Faces application to test your configuration

Now that you've configured a project for ADF Faces, you can test your configuration by creating a simple ADF Faces application.

  1. If not already open, open the new JSP "helloadffaces.jsp" in the JSP Visual Editor.
  2. Switch the Component Palette to the "JSF Core" page.
  3. Drag and drop the "view" tag onto the page. The "view" tag is required for all Faces pages.
  4. Now switch the Component Palette to "ADF Faces Core".
  5. Drag and drop an "outputText" tag inside the existing "view" tag. The black border denotes containership.
  6. In the Property Inspector, set the value attribute of the outputText tag to "hello ADF Faces!".
  7. Save all your work by clicking on the "Save All" icon on the main menu.
  8. Make sure you enable "J2SE 1.4 Assertions" in the project properties.
    • Select Tools -> Project Properties -> Profiles -> Development -> Compiler
  9. Add the J2EE library
    • Select 'Tools -> Project Properties -> Libraries' and add 'J2EE'
  10. Start the embedded OC4J, by running the page.
  11. Important: This will NOT work immediately as you have to insert the "/faces" servlet mapping into the URL of your browser to make a request using the Faces servlet.
    Insert as follows: http:// yourhost:8988/ YourJ2EEContextRoot/ faces/helloadffaces.jsp into your browser's URL window.
  12. As you access the page with the proper URL, you should see your page with a "hello ADF Faces!" message.

Importing and running the ADF Faces demo

The file adf-faces-demo.zip is a demo WAR with missing third party libraries. It has been renamed to a ZIP so that users don't try to run it without the missing libraries. Please follow the direction below to turn adf-faces-demo.zip into a functioning WAR.

  1. Extract adf-faces-demo.zip. We'll call the directory you unzip it into [DEMO_HOME ] .
  2. Get the missing JSF 1.1 JAR files - go to the download button for "JavaServer Faces v1.1 Reference Implementation" and download the zip 'jsf-1_1.zip'. Extract the following jars to [DEMO_HOME ] /WEB-INF/lib (WinZip's "Use Folder Names" option should be unchecked):
  • jsf-api.jar
  • jsf-impl.jar
  1. Rezip the result into a file named 'adf-faces-demo.war'. Make sure the directory structure is the same as it was in adf-faces-demo.zip.

Now the WAR is ready to go.

  1. Create a new workspace.
    • Select File -> New -> General -> Workspaces -> Workspace.
    • Set the name to "MyWorkspace"
    • In the "Create Workspace" dialog uncheck the "Add a New Empty Project" option.
    • Click Finish
  2. In the new workspace, create a project from a WAR file.
    • Select File -> New -> General -> Projects -> Project from WAR File.
  3. In step 1 of the wizard, name the project "adffacesdemo" and accept the default directory location.
  4. In step 2, locate the WAR file (adf-faces-demo.war).
  5. Click Finish. This will expand the WAR file contents into your new project directory. You should now see your new project in the Application Navigator.
  6. Take a few seconds to familiarize yourself with the various files in this application. You'll find the adf-faces-config.xml along with other files in the WEB-INF directory.
  7. Make sure you enable "J2SE 1.4 Assertions" in the project properties.
    • Select Tools -> Project Properties -> Profiles -> Development -> Compiler
  8. Add the J2EE library
    • Select 'Tools -> Project Properties -> Libraries' and add 'J2EE'
  9. You can now start the demo by running index.jspx.

false ,,,,,,,,,,,,,,,