9.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. Unless otherwise noted, the term JSF page in this guide refers to both JSF JSP pages and JSF JSP documents.

9.3.1 How to Create a JSF Web 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:

1. Expand the ViewController/Web Content/WEB-INF folder in the Application Navigator and double-click faces-config.xml.

   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.

2. In the Component Palette, select JSF Navigation Diagram from the dropdown list, and then select JSF Page.

3. 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.

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

5. In Step 1 of the Create JSF JSP wizard, select JSP Page (*.jsp) or JSP Document (*.jspx) for the JSP file Type.

6. 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.

7. In Step 2 of the wizard, select whether or not to automatically expose UI components in a managed bean.

   For more information about managed beans and UI components, see Section 9.4, "Creating and Using a Backing Bean for a Web Page".

8. 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

9. Accept the default selection for the remaining page and click Finish.

Your new JSF page opens 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 ADF Faces 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.

9.3.2 What Happens When You Create a JSF Web Page

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

Figure 9-7 ViewController Project in the Navigator 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

  • 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.

JDeveloper also creates a starter page that is a JSF JSP 2.0 file, and automatically imports the JSF tag libraries into the starter page. 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 9-1 shows a starter page for a JSF JSP document.

Example 9-1 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>

9.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, see Oracle Application Development Framework Developer's Guide.