4.3 Creating a Web Page

While JSF supports a number of presentation layer technologies, JDeveloper uses JSP as the presentation technology for creating JSF user interfaces or 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. 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 open faces-config.xml file.

Section 4.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.

4.3.1 How to Add a JSF Page

Oracles recommends using the JSF navigation diagram to plan out and create your application pages. 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 to open the JSF navigation diagram, which would be an empty drawing surface if you've just created the project.

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.
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 ADF data controls from the Data Control Palette.

If you switch back to the JSF navigation diagram (by clicking faces-config.xml at the top of the editor), 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.

4.3.2 What Happens When You Create a JSF Page

Figure 4-3 shows the Application Navigator view of the ViewController project after you complete the wizard steps to add a JSF page. Figure 4-4 shows the actual folders JDeveloper creates in the <JDEV_HOME>/jdev/mywork folder in the file system.

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

New JSF page in ViewController project in navigator

Figure 4-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:

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 4-2.
- Libraries: JSP Runtime, ADF Faces Runtime, ADF Common Runtime

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 and ADF Faces tag libraries into the starter pages. Example 4-4 shows a starter page for a JSF JSP document.

Example 4-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>

4.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, deleting, and editing 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. If you have created the underlying page, that page remains with its original name.

Similarly, if you have already created a JSF page and it is displayed on the diagram, if you rename it in the Application Navigator, this is equivalent to removing the original file and creating a new file. The diagram retains the original name, and now displays the page icon overlaid with the warning indicating that the page does not exist.

Because JSF pages are not referenced directly in faces-config.xml, renaming a JSF page on a JSF navigation diagram does not affect faces-config.xml. However, navigation rules in faces-config.xml do contain the names of JSF pages.

If you rename a JSF page on a JSF navigation diagram, this has no effect on any navigation rules defined in faces-config.xml, which still refer to the original name of the page. For this reason, if you rename a page that is used in a navigation rule, pages with both the original name and the new name may be displayed on the diagram.
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.
Editing pages: When you edit web pages manually, JDeveloper does not automatically update the JSF navigation diagram or faces-config.xml. Conversely, when you make changes to a page flow that affect the behavior of an existing web page, JDeveloper does not automatically update the code in the web page. To coordinate web page changes and JSF navigation diagram changes, right-click the diagram and choose Diagram > Refresh Diagram From All Pages.

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

4.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 4-2 shows the URIs and default prefixes for the ADF Faces and JSF tag libraries used in JDeveloper.

Table 4-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`

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 22, "Deploying ADF Applications".