11.3 Creating a Web Page

While JSF supports a number of presentation layer technologies, JDeveloper uses JSP as the presentation technology for creating JSF web pages. When you use JSF with JSP, the JSF pages can be JSP pages (.jsp) or JSP documents (.jspx). JSP documents are well-formed XML documents, and the XML standard offers many benefits such as validation against a document type definition. Hence, Oracle recommends that you use JSP documents when you build your web pages using ADF Faces components. Unless otherwise noted, the term JSF page in this guide refers to both JSF JSP pages and JSF JSP documents.

JDeveloper gives you two ways to create JSF pages that will appear in your ViewController project:

Launch the Create JSF JSP wizard from the JSF category in the New Gallery.

OR
Drag a JSF Page from the Component Palette onto the faces-config.xml file when the file is open in the Diagram mode of the JSF Configuration Editor.

Section 11.3.1, "How to Add a JSF Page" uses the latter technique. It also introduces the JSF Navigation Modeler, which allows you to plan out your application pages in the form of a diagram, to define the navigation flow between the pages, and to create the pages.

11.3.1 How to Add a JSF Page

Oracle recommends using the JSF navigation diagram to plan out and build your application page flow. Because the JSF navigation diagram visually represents the pages of the application, it is also an especially useful way to drill down into individual web pages when you want to edit them in the JSP/HTML Visual Editor.

To add a JSF page to your ViewController project using the JSF navigation diagram:

Expand the ViewController - Web Content - WEB-INF folder in the Application Navigator and double-click faces-config.xml or choose Open JSF Navigation from the ViewController context menu to open the faces-config.xml file.

By default, JDeveloper opens the file in the Diagram tab, which is the JSF navigation diagram. If you've just started the ViewController project, the navigation diagram would be an empty drawing surface. If you don't see a blank drawing surface when you open faces-config.xml, select Diagram at the bottom of the editor.
In the Component Palette, select JSF Navigation Diagram from the dropdown list, and then select JSF Page.
Click on the diagram in the place where you want the page to appear. A page icon with a label for the page name appears on the diagram. The page icon has a yellow warning overlaid–this means you haven't created the actual page yet, just a representation of the page.
To create the new page, double-click the page icon and use the Create JSF JSP wizard.

When creating a page in JDeveloper for the first time, be sure to complete all the steps of the wizard.
In Step 1 of the Create JSF JSP wizard, select JSP Document (*.jspx) for the JSP file Type.
Enter a filename and accept the default directory name or choose a new location. By default, JDeveloper saves files in /ViewController/public_html in the file system.
In Step 2 of the wizard, keep the default selection for not using component binding automatically.
In Step 3 of the wizard, make sure that these libraries are added to the Selected Libraries list:
- ADF Faces Components
- ADF Faces HTML
- JSF Core
- JSF HTML
Accept the default selection for the remaining page and click Finish.

Your new JSF page will open in the JSP/HTML Visual Editor where you can begin to lay out the page using ADF Faces components from the Component Palette or databound components dropped from the Data Control Palette.

If you switch back to the JSF navigation diagram (by clicking the faces-config.xml editor tab at the top), you will notice that the page icon no longer has the yellow warning overlaid.

Tip:

If you create new JSF pages using the wizard from the New Gallery, you can drag them from the Application Navigator to the JSF navigation diagram when designing the application page flow.

11.3.2 What Happens When You Create a JSF Page

Figure 11-3 shows the Application Navigator view of the ViewController project after you complete the wizard steps to add a JSF page.

Figure 11-3 ViewController Project in the Navigator After You Add a JSF Page

New JSF page in ViewController project in navigator

Figure 11-4 shows the actual folders JDeveloper creates in the <JDEV_HOME>/jdev/mywork folder in the file system.

Figure 11-4 ViewController Folders in the File System After You Add a JSF Page

JDeveloper does the following when you create your first JSF page in a ViewController project via the JSF navigation diagram:

Adds adf-faces-impl.jar to /WEB-INF/lib.
Adds these libraries to the ViewController project properties:
- JSP Tag Libraries: ADF Faces Components, ADF Faces HTML. See Table 11-2.
- Libraries: JSP Runtime, ADF Faces Runtime, ADF Common Runtime
Creates the faces-config.oxd_faces file in the file system only, for example, in <JDEV_HOME>/jdev/mywork/Application1/ViewController/model/public_html/WEB-INF. When you plan out and build your page flow in the JSF navigation diagram, this is the file that holds all the diagram details such as layout and annotations. JDeveloper always maintains this file alongside its associated XML file, faces-config.xml. The faces-config.oxd_faces file is not visible in the Application or System Navigator.

Whether you create JSF pages by launching the Create JSF JSP wizard from the JSF navigation diagram or the New Gallery, by default JDeveloper creates starter pages that are JSF JSP 2.0 files, and automatically imports the JSF tag libraries into the starter pages. If you select to add the ADF Faces tag libraries in step 3 of the wizard, JDeveloper also imports the ADF Faces tag libraries into the starter pages. Example 11-4 shows a starter page for a JSF JSP document.

Example 11-4 Starter JSF JSP Document Created by JDeveloper

<?xml version='1.0' encoding='windows-1252'?>
<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" version="2.0"
          xmlns:f="http://java.sun.com/jsf/core"
          xmlns:h="http://java.sun.com/jsf/html"
          xmlns:af="http://xmlns.oracle.com/adf/faces"
          xmlns:afh="http://xmlns.oracle.com/adf/faces/html"
  <jsp:output omit-xml-declaration="true" doctype-root-element="HTML"
              doctype-system="http://www.w3.org/TR/html4/loose.dtd"
              doctype-public="-//W3C//DTD HTML 4.01 Transitional//EN"/>
  <jsp:directive.page contentType="text/html;charset=windows-1252"/>
  <f:view>
    <html>
      <head>
        <meta http-equiv="Content-Type" 
              content="text/html; charset=windows-1252"/>
        <title>untitled1</title>
      </head>
      <body>
        <h:form></h:form>
      </body>
    </html>
  </f:view>
</jsp:root>

11.3.3 What You May Need to Know About Using the JSF Navigation Diagram

In the JSF navigation diagram, you will notice that the label of the page icon has an initial slash (/), followed by the name of the page. The initial slash is required so that the page can be run from the diagram. If you remove the slash, JDeveloper will automatically reinstate it for you.

Be careful when renaming and deleting pages from the JSF navigation diagram:

Renaming pages: If you rename a JSF page on a JSF navigation diagram, this is equivalent to removing a page with the original name from the diagram and adding a new one with the new name; the page icon changes to a page icon overlaid with the yellow warning, indicating that the page does not yet exist. If you have already created the underlying page, that page remains with its original name in the Application Navigator.

Similarly, if you have a JSF page in the Application Navigator and the page icon is displayed on the diagram, if you now rename the page in the Application Navigator, this is equivalent to removing the original file and creating a new file. The diagram, however, retains the original name, and now displays the page icon overlaid with the yellow warning, indicating that the page does not exist.
Deleting pages: When you delete a page icon in the JSF navigation diagram, the associated web page is no longer visible in the diagram. If you have created the actual file, it is still available from the Web Content folder in the ViewController project in the Application Navigator.

For information about the JSF navigation diagram and creating navigation rules, see Chapter 16, "Adding Page Navigation".

11.3.4 What You May Need to Know About ADF Faces Dependencies and Libraries

ADF Faces is compatible with JDK 1.4 (and higher), and cannot run on a server that supports only Sun's JSF Reference Implementation 1.0. The implementation must be JSF 1.1_01 (or later) or Apache MyFaces 1.0.8 (or later).

The ADF Faces deliverables are:

adf-faces-api.jar: All public APIs of ADF Faces are in the oracle.adf.view.faces package.
adf-faces-impl.jar: All private APIs of ADF Faces are in the oracle.adfinternal.view.faces package.

ADF Faces provides two tag libraries that you can use in your JSF pages:

ADF Faces Core library
ADF Faces HTML library

Table 11-2 shows the URIs and default prefixes for the ADF Faces and JSF tag libraries used in JDeveloper.

Table 11-2 ADF Faces and JSF Tag Libraries

Library	URI	Prefix
ADF Faces Core	`http://xmlns.oracle.com/adf/faces`	`af`
ADF Faces HTML	`http://xmlns.oracle.com/adf/faces/html`	`afh`
JSF Core	`http://java.sun.com/jsf/core`	`f`
JSF HTML	`http://java.sun.com/jsf/html`	`h`

JDeveloper also provides the ADF Faces Cache and ADF Faces Industrial tag libraries, which use the prefix afc and afi, respectively. For information about ADF Faces Cache, see Chapter 23, "Optimizing Application Performance with Caching". For information about ADF Faces Industrial, see the JDeveloper online help topic "Developing ADF Mobile Applications".

All JSF applications must be compliant with the Servlet specification, version 2.3 (or later) and the JSP specification, version 1.2 (or later). The J2EE web container that you deploy to must provide the necessary JAR files for the JavaServer Pages Standard Tag Library (JSTL), namely jstl.jar and standard.jar. The JSTL version to use depends on the J2EE web container:

JSTL 1.0—Requires a J2EE 1.3 web container that supports Servlet 2.3 and JSP 1.2
JSTL 1.1—Requires a J2EE 1.4 web container that supports Servlet 2.4 and JSP 2.0

For complete information about ADF Faces and JSF deployment requirements, see Chapter 34, "Deploying ADF Applications".