Getting Started with ADF Faces

What Happens When You Use an Application Template to Create a Workspace

By default, JDeveloper names the project for the data model Model, and the project for the user interface and controller ViewController. You can rename the projects using File > Rename after you've created them, or you can use Tools > Manage Templates to change the default names that JDeveloper uses.

Figure: ViewController Project in the Navigator After You Create a Workspace shows the Application Navigator view of the ViewController project after you create the workspace.

ViewController Project in the Navigator After You Create a Workspace

Figure: ViewController Folders in the File System After You Create a Workspace shows the actual folders JDeveloper creates in the <JDEV_HOME>/jdev/mywork folder in the file system.

ViewController Folders in the File System After You Create a Workspace

For example, if you created a workspace named Application1, the ViewController folder and its subfolders would be located in <JDEV_HOME>/jdev/mywork/Application1 in the file system.

When you use the Web Application [JSF, EJB, TopLink] template to create a workspace, JDeveloper does the following for you:

• Creates a ViewController project that uses JSF technology. The project properties include:

  • JSP Tag Libraries: JSF Core, JSF HTML. See Table: ADF Faces and JSF Tag Libraries.

  • Libraries: JSF, Commons Beanutils, Commons Digester, Commons Logging, Commons Collections, JSTL.

  • Technology Scope: JSF, JSP and Servlets, Java, HTML.

  When you work in the ViewController project, the New Gallery will be filtered to show standard web technologies (including JSF) in the Web Tier category.

  By default, JDeveloper uses JSTL 1.1 and a J2EE 1.4 web container that supports Servlet 2.4 and JSP 2.0.

• Creates a starter web.xml file with default settings in /WEB-INF of the ViewController project. See Starter web.xml File if you want to know what JDeveloper adds to web.xml.

• Creates an empty faces-config.xml file in /WEB-INF of the ViewController project. See Starter faces-config.xml File if you want to learn more about faces-config.xml.

  Note that if you double-click faces-config.xml in the Application Navigator to open the file, JDeveloper creates a model folder in the ViewController folder in the file system, and adds the file faces-config.oxd_faces in the model folder. For information about the faces-config.oxd_faces file, see What Happens When You Create a JSF Page.

• Adds jsf-impl.jar in /WEB-INF/lib of the ViewController project.

• Creates a Model project that uses TopLink and EJB technology. For more information about the Model project, see Building the Business Service in the Model Project.

<?xml version = '1.0' encoding = 'windows-1252'?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
          http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
         version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee">
  <description>Empty web.xml file for Web Application</description>

  <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>Faces Servlet</servlet-name>
    <url-pattern>/faces/*</url-pattern>
  </servlet-mapping>
...
</web-app>

<?xml version="1.0" encoding="windows-1252"?>
<!DOCTYPE faces-config PUBLIC
  "-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.1//EN"
  "http://java.sun.com/dtd/web-facesconfig_1_1.dtd">
<faces-config xmlns="http://java.sun.com/JSF/Configuration">

</faces-config>

What You May Need to Know About the ViewController Project

The ViewController project contains the web content that includes the web pages and other resources of the web application. By default, the JDeveloper web application template you select adds the word "controller" to the project name to indicate that the web application will include certain files that define the application's flow or page navigation (controller), in addition to the web pages themselves (view).

The technology that you use to create web pages in JDeveloper will determine the components of the ViewController project and the type of page controller your application will use. The SRDemo application uses JSF combined with JSP to build the web pages:

• JSF provides a component-based framework for displaying dynamic web content. It also provides its own page controller to manage the page navigation.

• JSP provides the presentation layer technology for JSF user interfaces. The JSF components are represented by special JSP custom tags in the JSP pages.

JDeveloper tools will help you to easily bind the JSF components with the Java objects of the Model project, thus creating databound UI components. As described earlier, the ViewController project contains the web pages for the user interface. To declaratively bind UI components in web pages to a data model, the ViewController project must be able to access data controls in the Model project. To enable the ViewController project to access the data controls, a dependency on the Model project must be specified. The first time you drag an item from the Data Control Palette and drop it onto a JSF page, JDeveloper configures the dependency for you. If you wish to set the dependency on the Model project manually, use the following procedure.

To set dependency on a Model project for a ViewController project in JDeveloper:

1. Double-click ViewController in the Application Navigator to open the Project Properties dialog.

2. Select Dependencies and then select the checkbox next to Model.jpr.

What You May Need to Know About Multiple JSF Configuration Files

A JSF application can have more than one JSF configuration file. For example, if you need individual JSF configuration files for separate areas of your application, or if you choose to package libraries containing custom components or renderers, you can create a separate JSF configuration file for each area or library.

To create another JSF configuration file, simply use a text editor or use the JSF Page Flow & Configuration wizard provided by JDeveloper.

To launch the JSF Page Flow & Configuration wizard:

1. In the Application Navigator, right-click ViewController and choose New.

2. In the New Gallery window, expand Web Tier. Select JSF and then double-click JSF Page Flow & Configuration (faces-config.xml).

When creating a JSF configuration file for custom components or other JSF classes delivered in a library JAR:

• Name the file faces-config.xml if you desire.

• Store the new file in /META-INF.

• Include this file in the JAR that you use to distribute your custom components or classes.

This is helpful for applications that have packaged libraries containing custom components and renderers.

When creating a JSF configuration file for a separate application area:

• Give the file a name other than faces-config.xml.

• Store the file in /WEB-INF.

• For JSF to read the new JSF configuration file as part of the application's configuration, specify the path to the file using the context parameter javax.faces.CONFIG_FILES in web.xml. The parameter value is a comma-separated list of the new configuration file names, if there is more than one file.

  If using the JSF Page Flow & Configuration wizard, select the Add Reference to web.xml checkbox to let JDeveloper register the new JSF configuration file for you in web.xml. Example: Configuring for Multiple JSF Configuration Files in the web.xml File shows how multiple JSF configuration files are set in web.xml by JDeveloper if you select the checkbox.

This is helpful for large-scale applications that require separate configuration files for different areas of the application.

<context-param>
  <param-name>javax.faces.CONFIG_FILES</param-name>
  <param-value>/WEB-INF/faces-config1.xml,/WEB-INF/faces-config2.xml</param-value>
</context-param>

Any JSF configuration file, whether it is named faces-config.xml or not, must conform to Sun's DTD located at http://java.sun.com/dtd/web-facesconfig_1_x.dtd. If you use the wizard to create a JSF configuration file, JDeveloper takes care of this for you.

If an application uses several JSF configuration files, at runtime JSF finds and loads the application's configuration settings in the following order:

1. Searches for files named META-INF/faces-config.xml in any JAR files for the application, and loads each as a configuration resource (in reverse order of the order in which they are found).

2. Searches for the javax.faces.CONFIG_FILES context parameter set in the application's web.xml file. JSF then loads each named file as a configuration resource.

3. Searches for a file named faces-config.xml in the WEB-INF directory and loads it as a configuration resource.

JSF then instantiates an Application class and populates it with the settings found in the various configuration files.

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:

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

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 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, keep the default selection for not using component binding automatically.

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

What Happens When You Create a JSF Page

Figure: ViewController Project in the Navigator After You Add a JSF Page shows the Application Navigator view of the ViewController project after you complete the wizard steps to add a JSF page.

ViewController Project in the Navigator After You Add a JSF Page

Figure: ViewController Folders in the File System After You Add a JSF Page shows the actual folders JDeveloper creates in the <JDEV_HOME>/jdev/mywork folder in the file system.

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: ADF Faces and JSF Tag Libraries.

  • 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: Starter JSF JSP Document Created by JDeveloper shows a starter page for a JSF JSP document.

<?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>

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 Adding Page Navigation.

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

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

How to Add UI Components to a JSF Page

You can use both standard JSF components and ADF Faces components within the same JSF page. For example, to insert and use the panelPage component in a starter JSF page created by JDeveloper, you could use the following procedure.

To insert UI components into a JSF page:

1. If not already open, double-click the starter JSF page in the Application Navigator to open it in the visual editor.

2. In the Component Palette, select ADF Faces Core from the dropdown list.

3. Drag and drop PanelPage from the palette to the page in the visual editor.

   
   

   As you drag a component on the page in the visual editor, notice that the Structure window highlights the h:form component with a box outline, indicating that the h:form component is the target component. The target component is the component into which the source component will be inserted when it is dropped.

4. In the Structure window, right-click the newly inserted af:panelPage or any of the PanelPage facets, and choose from the Insert before, Insert inside, or Insert after menu to add the UI components you desire.

   
   

   You create your input or search forms, tables, and other page body contents inside the panelPage component. For more information about panelPage and its facets, see Using the PanelPage Component.

   
   

   Tip: Using the context menu in the Structure window to add components ensures that you are inserting components into the correct target locations. You can also drag components from the Component Palette to the Structure window. As you drag a component on the Structure window, JDeveloper highlights the target location with a box outline or a line with an embedded arrow to indicate that the source component will be inserted in that target location when it is dropped. See Editing in the Structure Window for additional information about inserting components using the Structure window.

   
   

5. To edit the attributes for an inserted component, double-click the component in the Structure window to open a property editor, or select the component and then use the Property Inspector.

As you build your page layout by inserting components, you can also use the Data Control Palette to insert databound UI components. Simply drag the item from the Data Control Palette and drop it into the desired location on the page. For further information about using the Data Control Palette, see Displaying Data on a Page.

What Happens When You First Insert an ADF Faces Component

Figure: ViewController Project in the Navigator After You Insert the First ADF Faces Component shows the Application Navigator view of the ViewController project after adding your first ADF Faces component in a page.

ViewController Project in the Navigator After You Insert the First ADF Faces Component

When you first add an ADF Faces component to a JSF page, JDeveloper automatically does the following:

• Imports the ADF Faces Core and HTML tag libraries (if not already inserted) into the page. See Example: Starter JSF JSP Document Created by JDeveloper.

• Replaces the html, head, and body tags with afh:html, afh:head, and afh:body, respectively. See Example: JSF JSP Document After You Add the First ADF Faces Component.

• Adds the ADF Faces filter and mapping configuration settings to web.xml. See More About the web.xml File.

• Adds the ADF Faces default render kit configuration setting to faces-config.xml. See More About the faces-config.xml File.

• Creates a starter adf-faces-config.xml in /WEB-INF of the ViewController project. See Starter adf-faces-config.xml File.

• Creates the /ViewController/public_html/WEB-INF/temp/adf folder in the file system. This folder contains images and styles that JDeveloper uses for ADF Faces components. You might not see the folder in the Application Navigator until you close and reopen the workspace.

<?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:afh="http://xmlns.oracle.com/adf/faces/html" 
          xmlns:af="http://xmlns.oracle.com/adf/faces">
  <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>
    <afh:html>
      <afh:head title="untitled1">
        <meta http-equiv="Content-Type"
              content="text/html; charset=windows-1252"/>
      </afh:head>
      <afh:body>
        <h:form>
          <af:panelPage title="Title 1">
            <f:facet name="menu1"/>
            <f:facet name="menuGlobal"/>
            <f:facet name="branding"/>
            <f:facet name="brandingApp"/>
            <f:facet name="appCopyright"/>
            <f:facet name="appPrivacy"/>
            <f:facet name="appAbout"/>
          </af:panelPage>
        </h:form>
      </afh:body>
    </afh:html>
  </f:view>
</jsp:root>

<?xml version = '1.0' encoding = 'windows-1252'?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
          http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
         version="2.4" xmlns="http://java.sun.com/xml/ns/j2ee">
  <description>Empty web.xml file for Web Application</description>

  <!-- Installs the ADF Faces filter -- >
  <filter>
    <filter-name>adfFaces</filter-name>
    <filter-class>oracle.adf.view.faces.webapp.AdfFacesFilter</filter-class>
  </filter>

  <!-- Adds the mapping to ADF Faces filter -- >
  <filter-mapping>
    <filter-name>adfFaces</filter-name>
    <servlet-name>Faces Servlet</servlet-name>
  </filter-mapping>

  <servlet>
    <servlet-name>Faces Servlet</servlet-name>
    <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
    <load-on-startup>1</load-on-startup>
  </servlet>

  <!-- Installs the ADF Faces ResourceServlet -- >
  <servlet>
    <servlet-name>resources</servlet-name>
    <servlet-class>oracle.adf.view.faces.webapp.ResourceServlet</servlet-class>
  </servlet>

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

  <!-- Maps URL pattern to the ResourceServlet's symbolic name -->
  <servlet-mapping>
    <servlet-name>resources</servlet-name>
    <url-pattern>/adf/*</url-pattern>
  </servlet-mapping>
...
</web-app>

<?xml version="1.0" encoding="windows-1252"?>
<!DOCTYPE faces-config PUBLIC
  "-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.1//EN"
  "http://java.sun.com/dtd/web-facesconfig_1_1.dtd">
<faces-config xmlns="http://java.sun.com/JSF/Configuration">
  ...
  <!-- Default render kit for ADF components -->
  <application>
    <default-render-kit-id>oracle.adf.core</default-render-kit-id>
  </application>
  ...
</faces-config>

<?xml version="1.0" encoding="windows-1252"?>
<adf-faces-config xmlns="http://xmlns.oracle.com/adf/view/faces/config">

  <skin-family>oracle</skin-family>

</adf-faces-config>

What You May Need to Know About Creating JSF Pages

Consider the following when you're developing JSF web pages:

• Do not use JSTL and HTML tags in a JSF page. JSTL tags cannot work with JSF at all prior to J2EE 1.5, and HTML tags inside of JSF tags often mean you need to use f:verbatim.

  For example you can't use c:forEach around JSF tags at all. When you nest a JSF tag inside a non-JSF tag that iterates over its body, the first time the page is processed the nested tag is invoked once for each item in the collection, creating a new component on each invocation. On subsequent requests because the number of items might be different, there is no good way to resolve the problem of needing a new component ID for each iteration: JSP page scoped variables cannot be seen by JSF; JSF request scoped variables in a previous rendering phase are not available in the current postback request.

  Other non-JSF tags may be used with JSF tags but only with great care. For example, if you use c:if and c:choose, the id attributes of nested JSF tags must be set; if you nest non-JSF tags within JSF tags, you must wrap the non-JSF tags in f:verbatim; if you dynamically include JSP pages that contain JSF content, you must use f:subview and also wrap all included non-JSF content in f:verbatim.

• In the SRDemo user interface, all String resources (for example, page titles and field labels) that are not retrieved from the ADF Model are added to a resource properties file in the ViewController project. If you use a resource properties file to hold the UI strings, use the f:loadBundle tag to load the properties file in the JSF page. For more information about resource bundles and the f:loadBundle tag, see Internationalizing Your Application.

• There is no requirement to use the ADF Faces af:form tag when you're using ADF Faces components—you can use the standard JSF h:form with all ADF Faces components. If you do use af:form, note that the af:form component does not implement the JSF NamingContainer API. This means a component's ID in the generated HTML does not include the form's ID as a prefix. For pages with multiple forms, this implies you can't reuse ID values among the forms. For example, this code snippet generates the component ID foo:bar for inputText:

  <h:form id="foo">
    <af:inputText id="bar"/>
  </h:form>
  
  

  But the following code snippet generates the component ID bar2 for inputText:

  <af:form id="foo2">
    <af:inputText id="bar2"/>
  </af:form>
  
  

  The advantages of using af:form are:

  • It is easier to write JavaScript because it does not result in prefixed "name" and "id" attributes in its contents (as explained above).

  • It results in more concise HTML, for example, in cases where you may not know the form's ID.

  • You can use some CSS features on the fields.

  • You can set a default command for form submission. Set the defaultCommand attribute on af:form to the ID of the command button that is to be used as the default submit button when the Enter key is pressed. By defining a default command button for a form, when the user presses the Enter key, an ActionEvent is created and the form submitted. If a default command button is not defined for a form, pressing Enter will not submit the form, and the page simply redisplays.

• The afh:body tag enables partial page rendering (PPR) in a page. If a page cannot use the afh:body tag and PPR support is desired, use the af:panelPartialRoot tag in place of the afh:body tag. For information about PPR, see Enabling Partial Page Rendering.

• The af:document tag generates the standard root elements of an HTML page, namely html, head, and body, so you can use af:document in place of afh:html, afh:head, and afh:body.

For more tips on using ADF Faces components, see Best Practices for ADF Faces.

Editing in the Structure Window

In the Structure window while inserting, copying, or moving elements, you select an insertion point on the structure that is shown for the page, in relation to a target element. JDeveloper provides visual cues to indicate the location of the insertion point before, after, or contained inside a target element.

When dragging an element to an insertion point, do one of the following:

• To insert an element before a target element, drag it towards the top of the element until you see a horizontal line with an embedded up arrow, and then release the mouse button.

• To insert an element after a target element, drag it towards the bottom of the element until you see a horizontal line with an embedded down arrow, and then release the mouse button.

• To insert or contain an element inside a target element, drag it over the element until it is surrounded by a box outline, and then release the mouse button. If the element is not available to contain the inserted element, the element will be inserted after the target element.

Tip: A disallowed insertion point is indicated when the drag cursor changes to a circle with a slash.

<error-page>
  <exception-type>java.lang.Exception</exception-type>
  <location>/faces/infrastructure/SRError.jspx</location>
</error-page>

<jsp:root ...>
  <jsp:output ...>
  <jsp:directive.page contentType="text/html;charset=windows-1252"
                      errorPage="faces/SRError.jspx"/>
  <f:view></f:view>
</jsp:root>

Using the PanelPage Component

The SRDemo pages use panelPage as the main ADF Faces layout component, which lets you lay out an entire page with specific areas for navigation menus, branding images, and page body contents, as illustrated in Figure: Page Layout Created with a PanelPage Component.

The panelPage component uses facets (or JSF f:facet tags) to render children components in specific, predefined locations on the page. Consider a facet as a placeholder for one child component. Each facet has a name and a purpose, which determines where the child component is to be rendered relative to the parent component. The child component is often a container component for other child components.

The panelPage component uses menu1, menu2, and menu3 facets for creating hierarchical, navigation menus that enable users to go quickly to related pages in the application. In the menu facets you could either:

• Manually insert the menu components (such menuTabs and menuBar) and their children menu items. By manually inserting individual children components, you need a lot of code in your JSF pages, which is time-consuming to create and maintain.

  For example, to create two menu tabs with subtabs, you would need code like this:

  <f:facet name="menu1">
    <af:menuTabs>
      <af:commandMenuItem text="Benefits" selected="true"
                          action="go.benefits"/>
      <af:commandMenuItem text="Employee Data" action="go.emps"/>
    </af:menuTabs>
  </f:facet>
  <f:facet name="menu2">
    <af:menuBar>
      <af:commandMenuItem text="Insurance" selected="true"
                          action="go.insurance"/>
      <af:commandMenuItem text="Paid Time Off" selected="false"
                          action="go.pto"/>
    </af:menuBar>
  </f:facet>
  
  

• Bind the menu components to a MenuModel object, and for each menu component use a nodeStamp facet to stamp out the menu items (which does not require having multiple menu item components in each menu component). By binding to a MenuModel object and using a nodeStamp facet, you use less code in your JSF pages, and almost any page (regardless of its place in the hierarchy) can be rendered using the same menu code. For example, to create the same two menu tabs shown earlier:

  <f:facet name="menu1">
    <af:menuTabs var="menutab" value="#{menuModel.model}">
      <f:facet name="nodeStamp">
        <af:commandMenuItem text="#{menutab.label}"
                            action="#{menutab.getOutcome}"/>
      </f:facet>
    </af:menuList>
  </f:facet> 
  <f:facet name="menu2">
    <af:menuBar startDepth="1" var="menusubtab" value="#{menuModel.model}">
      <f:facet name="nodeStamp">
        <af:commandMenuItem text="#{menusubtab.label}"
                            action="#{menusubtab.getOutcome}"/>
      </f:facet>
    </af:menuList>
  </f:facet> 
  
  

  In the SRDemo pages, the menu components are bound to a menu model object that is configured via managed beans. For information about how to create a menu structure using managed beans, see Using Dynamic Menus for Navigation.

In addition to laying out hierarchical menus, the panelPage component supports other facets for laying out page-level and application-level text, images, and action buttons in specific areas, as illustrated in Figure: Basic Page Layout with Branding Images, Navigation Menus, and Application-Level Text and Figure: Basic Page Layout with Page-Level Actions and Informational Text.

For instructions on how to insert child components into facets or into panelPage itself, see How to Add UI Components to a JSF Page.

PanelPage Facets

Figure: Basic Page Layout with Branding Images, Navigation Menus, and Application-Level Text shows panelPage facets (numbered 1 to 12) for laying out branding images, global buttons, menu tabs, bars, and lists, and application-level text.

Basic Page Layout with Branding Images, Navigation Menus, and Application-Level Text

Table: PanelPage Facets for Branding Images, Navigation Menus, and Application-Level Text shows the panelPage facets (as numbered in Figure: Basic Page Layout with Branding Images, Navigation Menus, and Application-Level Text), and the preferred children components that you could use in them. In JDeveloper, when you right-click a facet in the Structure window, the Insert inside context menu shows the preferred component to use, if any.

PanelPage Facets for Branding Images, Navigation Menus, and Application-Level Text

No.	Facet	Description
1	branding	For a corporate logo or organization branding using objectImage. Renders its child component at the top left corner of the page.
2	brandingApp	For an application logo or product branding using objectImage. Renders its child component after a branding image, if used. If chromeType on panelPage is set to "expanded", the brandingApp image is placed below the branding image.
3	brandingAppContextual	Typically use with outputFormatted text to show the application's current branding context. Set the styleUsage attribute on outputFormatted to inContextBranding.
4	menuSwitch	For a menuChoice component that allows the user to switch to another application from any active page. Renders its child component at the top right corner of the page. The menuChoice component can be bound to a menu model object.
5	menuGlobal	For a menuButtons component that lays out a series of menu items as global buttons. Global buttons are buttons that are always available from any active page in the application (for example a Help button). Renders its children components at the top right corner of the page, before a menuSwitch child if used. A text link version of a global button is automatically repeated at the bottom of the page. The menuButtons component can be bound to a menu model object.
6	menu1	For a menuTabs component that lays out a series of menu items as tabs. Renders its children components (right justified) at the top of the page, beneath any branding images, menu buttons, or menu switch. A text link version of a tab is automatically repeated at the bottom of the page. Menu tab text links are rendered before the text link versions of global buttons. Both types of text links are centered in the page. The menuTabs component can be bound to a menu model object.
7	menu2	For a menuBar component that lays out a series of menu items in a horizontal bar, beneath the menu tabs. The children components are left justified in the bar, and separated by vertical lines. The menuBar component can be bound to a menu model object.
8	menu3	For a menuList component that lays out a bulleted list of menu items. Renders the children components in an area offset by color on the left side of a page, beneath a menu bar. The menuList component can be bound to a menu model object.
9	search	For a search area using an inputText component. Renders its child component beneath the horizontal menu bar. A dotted line separates it from the page title below.
10	appAbout	For a link to more information about the application using commandLink. The link text appears at the bottom left corner of the page.
11	appCopyright	For copyright text using outputText. The text appears above the appAbout link.
12	appPrivacy	For a link to a privacy policy statement for the application using commandLink. The link text appears at the bottom right corner of the page.

Tip: Many UI components support facets, not only panelPage. To quickly add or remove facets on a component, right-click the component in the Structure window and choose Facets - <component name>, where <component name> is the name of the UI component. If the component supports facets, you'll see a list of facet names. A checkmark next to a name means the f:facet element for that facet is already inserted in the page, but it may or not contain a child component.

Figure: Basic Page Layout with Page-Level Actions and Informational Text shows panelPage facets (numbered 1 to 7) for laying out page-level actions and text.

Basic Page Layout with Page-Level Actions and Informational Text

Table: PanelPage Facets for Page-Level Actions and Informational Text shows the panelPage facets (as numbered in Figure: Basic Page Layout with Page-Level Actions and Informational Text), and the preferred children components that you could use in them.

PanelPage Facets for Page-Level Actions and Informational Text

No.	Facet	Description
1	actions	For page-level actions that operate on the page content. Typically use with a panelButtonBar to lay out a series of buttons, a processChoiceBar, or a selectOneChoice. Renders its children components below the page title, right-justified. The children components are also automatically repeated near the bottom of the page (above any text link versions of menu tabs and global buttons) on certain devices and skins.
2	contextSwitcher	A context switcher lets the user change the contents of the page based on the context. For example, when a user is viewing company assets for a department, the user can use the context switcher to switch to the assets of another department. All the pages will then change to the selected context. Typically use with a selectOneChoice component. The facet renders its child component on the same level as the page title, right-justified.
3	infoFootnote	For page-level information that is ancillary to the task at hand. Typically use with an outputFormatted component, with styleClass or styleUsage set to an appropriate value. The facet renders its child component near the bottom of the page, left-justified and above the infoReturn link.
4	infoReturn	For a "Return to X" link using commandLink. For the user to move quickly back to the default page of the active menu tab. The facet renders its child component near the bottom of the page, left-justified and above the text link versions of menu tabs and global buttons.
5	infoStatus	For page-level status information about the task at hand. Could also use to provide a key notation. A key notation is a legend used to define icons, elements, or terms used within the page contents. Typically use with an outputFormatted component, with styleClass or styleUsage set to an appropriate value. The facet renders its child component below the page title, left-justified.
6	infoSupplemental	For any other additional information. Typically use with a panelBox to show the information in an area offset by color. In the panelBox you could use for example panelList or outputFormatted text to provide additional information that might help the user, but is not required for completing a task. The facet renders its children components on the right side of the page, below the infoUser facet child component.
7	infoUser	For presenting user login and connection information. Typically use with an outputFormatted component, with styleClass or styleUsage set to an appropriate value. The facet renders its child component on the right side of the page, immediately below the menu bars.

Tip: Like panelPage, the page component also lets you lay out an entire page with specific content areas. Unlike panelPage, you can bind the value of page to a menu model object to create the page's hierarchical menus—you don't have to bind individual menu components to a menu model object.

How to Create and Configure a Backing Bean

The Overview mode of the JSF Configuration Editor lets you create and configure a backing bean declaratively. Suppose you have a JSF page with the filename SRDemopage.jspx. Now you want to create a backing bean for the page.

To create and configure a backing bean as a managed bean:

1. In the Application Navigator, double-click faces-config.xml to open it in the default mode of the JSF Configuration Editor.

2. At the bottom of the editor, select the Overview tab to switch to the Overview mode, if necessary.

3. In the element list on the left, select Managed Beans.

4. Click New to open the Create Managed Bean dialog.

5. In the dialog, specify the following for a managed bean:

   • Name: Enter a unique identifier for the managed bean (e.g., backing_SRDemopage). This identifier determines how the bean will be referred to within the application using EL expressions, instead of using the bean's fully-qualified class name.

   • Class: Enter the fully qualified class name (e.g., oracle.srdemo.view.backing.SRDemopage). This is the JavaBean that contains the properties that hold the data for the UI components used on the page, along with the corresponding accessor methods and any other methods (such as navigation or validation). This can be an existing or a new class.

   • Scope: This determines the scope within which the bean is stored. The valid scope values are:

     • application: The bean is available for the duration of the web application. This is helpful for global beans such as LDAP directories.

     • request: The bean is available from the time it is instantiated until a response is sent back to the client. This is usually the life of the current page. Backing beans for pages usually use this scope.

     • session: The bean is available to the client throughout the client's session.

     • none: The bean is instantiated each time it is referenced.

6. Select the Generate Class If It Does Not Exist checkbox to let JDeveloper create the Java class for you. If you've already created the Java class, don't select this checkbox.

What Happens When You Create and Configure a Backing Bean

If you select the Generate Class If It Does Not Exist checkbox, JDeveloper creates a new Java class using the fully qualified class name set as the value of Class. The new file appears within the Application Sources node of the ViewController project in the Application Navigator, as illustrated in Figure: Backing Bean for SRDemopage.jspx in the Navigator.

Backing Bean for SRDemopage.jspx in the Navigator

To edit the backing bean class, double-click the file in the Application Navigator (for example, SRDemopage.java) to open it in the source editor. If it's a new class, you would see something similar to Example: Empty Java Class Created by JDeveloper.

package oracle.srdemo.view.backing;
 
public class SRDemopage {
    public SRDemopage() {
    }
}

In faces-config.xml, JDeveloper adds the backing bean configuration using the <managed-bean> element, as shown in Example: Registering a Managed Bean in the faces-config.xml File.

<faces-config xmlns="http://java.sun.com/JSF/Configuration">
  ...
  <!-- Page backing beans typically use request scope-->
  <managed-bean>
    <managed-bean-name>backing_SRDemopage</managed-bean-name>
    <managed-bean-class>oracle.srdemo.view.backing.SRDemopage</managed-bean-class>
    <managed-bean-scope>request</managed-bean-scope>
  </managed-bean>
  ...
</faces-config>

How to Use a Backing Bean in a JSF Page

Once a backing bean is defined with the relevant properties and methods, you use JSF EL expressions such as #{someBean.someProperty} or #{someBean.someMethod} to bind a UI component attribute to the appropriate property or method in the bean.

For example, the following code snippets illustrate value binding expressions and method binding expressions:

<af:inputText value="#{someBean.someProperty}"/>
..
<af:inputText disabled="#{someBean.anotherProperty}"/>
..
<af:commandButton action=#{someBean.someMethod}"/>
..
<af:inpuText valueChangeListener="#{someBean.anotherMethod}"/>

When such expressions are encountered at runtime, JSF instantiates the bean if it does not already exist in the bean scope that was configured in faces-config.xml.

In addition to value and method bindings, you can also bind the UI component's instance to a bean property using the binding attribute:

<af:commandButton binding="#{backing_SRDemopage.commandButton1}"

When the binding attribute of a UI component references a property in the bean, the bean has direct access to the component, and hence, logic in the bean can programmatically manipulate other attributes of the component, if needed. For example, you could change the color of displayed text, disable a button or field, or cause a component not to render, based on some UI logic in the backing bean.

To reiterate, you can bind a component's value attribute or any other attribute value to a bean property, or you can bind the component instance to a bean property. Which you choose depends on how much control you need over the component. When you bind a component attribute, the bean's associated property holds the value for the attribute, which can then be updated during the Update Model Values phase of the component's lifecycle. When you bind the component instance to a bean property, the property holds the value of the entire component instance, which means you can dynamically change any other component attribute value.

How to Use the Automatic Component Binding Feature

JDeveloper has a feature that lets you automatically bind a UI component instance on a JSF page to a backing bean property. When you turn on the Auto Bind feature for a page, for any UI component that you insert into the page, JDeveloper automatically adds property code in the page's backing bean, and binds the component's binding attribute to the corresponding property in the backing bean. If your backing bean doesn't have to modify the attributes of UI components on a page programmatically, you don't need to use the automatic component binding feature.

To turn on automatic component binding for a JSF page:

1. Open the JSF page in the visual editor. Select