| Oracle® Application Development Framework Developer's Guide For Forms/4GL Developers 10g Release 3 (10.1.3.0) Part Number B25947-02 |
|
|
View PDF |
| Oracle® Application Development Framework Developer's Guide For Forms/4GL Developers 10g Release 3 (10.1.3.0) Part Number B25947-02 |
|
|
View PDF |
This chapter describes the process of setting up your user interface project to use ADF Faces. It also supplies basic information about creating and laying out a web page that will rely on ADF Faces components for the user interface.
The chapter includes the following sections:
Oracle ADF Faces is a 100% JavaServer Faces (JSF) compliant component library that offers a broad set of enhanced UI components for JSF application development. Based on the JSF JSR 127 specification, ADF Faces components can be used in any IDE that supports JSF. More specifically, ADF Faces works with Sun's JSF Reference Implementation 1.1_01 (or later) and Apache MyFaces 1.0.8 (or later).
ADF Faces ensures a consistent look and feel for your application, allowing you to focus more on user interface interaction than look and feel compliance. The component library supports multi–language and translation implementations, and accessibility features. ADF Faces also supports multiple render kits for HTML, mobile, and telnet users—this means you can build web pages with the same components, regardless of the device that will be used to display the pages.
Using the partial-page rendering features of ADF Faces components, you can build interactive web pages that update the display without requiring a complete page refresh. In the future, Oracle plans to provide render kits that make even more sophisticated use of AJAX technologies—JavaScript, XML, and the Document Object Model (DOM)—to deliver more Rich Internet Applications with interactivity nearing that of desktop-style applications.
ADF Faces has many of the framework and component features most needed by JSF developers today, including:
Partial-page rendering
Client-side conversion and validation
A process scope that makes it easier to pass values from one page to another
A hybrid state-saving strategy that provides more efficient client-side state saving
Built-in support for label and message display in all input components
Built-in accessibility support in components
Support for custom skins
Support for mobile applications
ADF Faces UI components include advanced tables with column sorting and row selection capability, tree components for displaying data hierarchically, color and date pickers, and a host of other components such as menus, command buttons, shuttle choosers, and progress meters.
ADF Faces out-of-the-box components simplify user interaction, such as the input file component for uploading files, and the select input components with built-in dialog support for navigating to secondary windows and returning to the originating page with the selected values.
For more information about ADF Faces, refer to the following resources:
ADF Faces Core tags at
ADF Faces HTML tags at
ADF Faces Javadocs at
ADF Faces developer's guide at
When you create JSF JSP pages that use ADF Faces components for the UI and use JSF technology for page navigation, you can leverage the advantages of the Oracle Application Development Framework (Oracle ADF) by using the ADF Model binding capabilities for the components in the pages. For information about data controls and the ADF Model, see Section 1.3, "Declarative Development with Oracle ADF and JavaServer Faces".
Table 11-1 shows the platforms currently supported for ADF Faces.
Table 11-1 Supported Platforms for ADF Faces
| User Agent | Windows | Solaris | Mac OS X | Red Hat Linux | Windows Mobile | Palm OS |
|---|---|---|---|---|---|---|
|
Internet Explorer |
6.0 * |
2003+ |
||||
|
Mozilla |
1.7.x |
1.7.x |
||||
|
Firefox |
1.0.x |
1.0.x |
||||
|
Safari |
1.3, 2.0 ** |
|||||
|
WebPro (Mobile) |
3.0 |
* Accessibility and BiDi is only supported on IE on Windows.
** Apple bug fixes provided in Safari 1.3 patch 312.2 and Safari 2.0 patch 412.5 required.
Tip:
On a UNIX server box, button images may not render as expected. Assuming you're using JDK 1.4 or later, Oracle strongly recommends using
-Djava.awt.headless=true as a command-line option with UNIX boxes.Read this chapter to understand:
How to create a workspace using an application template in JDeveloper
What files are created for you in the view project when you add a JSF page and insert UI components
How to use panel and layout components to create page layouts
What JDeveloper does for you when you work with backing beans
JDeveloper provides application templates that enable you to quickly create the workspace and project structure with the appropriate combination of technologies already specified. The SRDemo application uses the Web Application [JSF, ADF BC] application template, which creates one project for the data model, and one project for the controller and view (user interface) components in a workspace.
To create a new application workspace in JDeveloper and choose an application template:
Right-click the Applications node in the Application Navigator and choose New Application.
In the Create Application dialog, select the Web Application [JSF, ADF BC] application template from the list.
You don't have to use JDeveloper application templates to create an application workspace—they are provided merely for your convenience.
At times you might already have an existing WAR file and you want to import it into JDeveloper.
To import a WAR file into a new project in JDeveloper:
Right-click your application workspace in the Application Navigator and choose New Project.
In the New Gallery, expand General in the Categories tree, and select Projects.
In the Items list, double-click Project from WAR File.
Follow the wizard instructions to complete creating the project.
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.
Note:
The illustrations and project names used in this chapter are the JDeveloper default names. The SRDemo application, however, uses the project name UserInterface for the JSF view and controller components, and DataModel for the project that contains ADF Business Components. The SRDemo application also has additional projects in the Application Navigator (for example, BuildAndDeploy), which you create manually to organize your application components into logical folders.Figure 11-1 shows the Application Navigator view of the ViewController project after you create the workspace.
Figure 11-2 shows the actual folders JDeveloper creates in the <JDEV_HOME>/jdev/mywork folder in the file system.
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, ADF BC] 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 11-2.
Libraries: JSF, Commons Beanutils, Commons Digester, Commons Logging, Commons Collections, JSTL.
Technology Scope: JSF, JSP and Servlets, Java, HTML, XML.
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 Section 11.2.1.1, "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 Section 11.2.1.2, "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 Section 11.3.2, "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 ADF Business Components technology. For information about creating a reusable layer of entity objects in the Model project, see Section 2.5, "Creating a Layer of Business Domain Objects for Tables". For information about building application modules and view objects, see Section 2.6, "Building the Business Service to Handle the Use Case".
Part of a JSF application's configuration is also determined by the contents of its J2EE application deployment descriptor, web.xml. The web.xml file defines everything about your application that a server needs to know (except the root context path, which is assigned by JDeveloper or the system administrator when the application is deployed). Typical runtime settings include initialization parameters, custom tag library location, and security settings.
Example 11-1 shows the starter web.xml file JDeveloper first creates for you.
Example 11-1 Starter web.xml File Created by JDeveloper
<?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>
The JSF servlet and servlet mapping configuration settings are automatically added to the starter web.xml file when you first create a JSF project.
JSF servlet: The JSF servlet is javax.faces.webapp.FacesServlet, which manages the request processing lifecycle for web applications utilizing JSF to construct the user interface. The configuration setting maps the JSF servlet to a symbolic name.
JSF servlet mapping: The servlet mapping maps the URL pattern to the JSF servlet's symbolic name. You can use either a path prefix or an extension suffix pattern.
By default, JDeveloper uses the path prefix /faces/*. For example, if your web page is index.jsp or index.jspx, this means that when the URL http://localhost:8080/SRDemoADFBC/faces/index.jsp or http://localhost:8080/SRDemoADFBC/faces/index.jspx is issued, the URL activates the JSF servlet, which strips off the faces prefix and loads the file /SRDemoADFBC/index.jsp or /SRDemoADFBC/index.jspx.
To edit web.xml in JDeveloper, right-click web.xml in the Application Navigator and choose Properties from the context menu to open the Web Application Deployment Descriptor editor. If you're familiar with the configuration element names, you can also use the XML editor to modify web.xml.
For reference information about the configuration elements you can use in web.xml when you work with JSF, see Section A.7, "web.xml".
Note:
If you use ADF data controls to build databound web pages, JDeveloper adds the ADF binding filter and a servlet context parameter for the application binding container inweb.xml. For more information, see Section 12.4, "Configuring the ADF Binding Filter".The JSF configuration file is where you register a JSF application's resources such as custom validators and managed beans, and define all the page-to-page navigation rules. While an application can have any JSF configuration filename, typically the filename is faces-config.xml. Example 11-2 shows the starter faces-config.xml file JDeveloper first creates for you when you create a project that uses JSF technology.
Small applications usually have one faces-config.xml file. For information about using multiple configuration files, see Section 11.2.3, "What You May Need to Know About Multiple JSF Configuration Files".
Example 11-2 Starter faces-config.xml File Created by JDeveloper
<?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>
In JDeveloper you can use either editor to edit faces-config.xml:
JSF Configuration Editor: Oracle recommends you use the JSF Configuration Editor because it provides visual editing.
XML Source Editor: Use the source editor to edit the file directly, if you're familiar with the JSF configuration elements.
To launch the JSF Configuration Editor:
In the Application Navigator, double-click faces-config.xml to open the file.
By default JDeveloper opens faces-config.xml in Diagram mode, as indicated by the active Diagram tab at the bottom of the editor window. When creating or modifying JSF navigation rules, Oracle suggests you use the Diagram mode of the JSF Configuration Editor.
In JDeveloper a diagram file, which lets you create and manage page flows visually, is associated with faces-config.xml. For information about creating JSF navigation rules, see Chapter 16, "Adding Page Navigation".
To create or modify configuration elements other than navigation rules, use the Overview mode of the JSF Configuration Editor. At the bottom of the editor window, select Overview.
Both Overview and Diagram modes update the faces-config.xml file.
Tip:
JSF allows more than one<application> element in a single faces-config.xml file. The JSF Configuration Editor only allows you to edit the first <application> instance in the file. For any other <application> elements, you'll need to edit the file directly using the XML editor.For reference information about the configuration elements you can use in faces-config.xml, see Section A.9, "faces-config.xml".
Note:
If you use ADF data controls to build databound web pages, JDeveloper adds the ADF phase listener infaces-config.xml, as described in Section 12.2.3, "What Happens When You Use the Data Control Palette".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).
Note:
The concept of separating page navigation from page display is often referred to as Model 2 to distinguish from earlier style (Model 1) applications that managed page navigation entirely within the pages themselves. In a Model 2 style application, the technology introduces a specialized servlet known as a page controller to handle page navigation events at runtime.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:
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:
In the Application Navigator, right-click ViewController and choose New.
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 11-3 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.
Example 11-3 Configuring for Multiple JSF Configuration Files in the web.xml File
<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:
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).
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.
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.
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.
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.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-4 shows the actual folders JDeveloper creates in the <JDEV_HOME>/jdev/mywork folder in the file system.
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>
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".
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 |
|
|
|
ADF Faces HTML |
|
|
|
JSF Core |
|
|
|
JSF HTML |
|
|
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".
Most of the SRDemo pages use the ADF Faces panelPage component to lay out the entire page. The panelPage component lets you define specific areas on the page for branding images, navigation menus and buttons, and page-level or application-level text, ensuring that all web pages in the application will have a consistent look and feel. Figure 11-5 shows an example of a page created by using a panelPage component.
After you create a new JSF page using the wizard, JDeveloper automatically opens the blank page in the JSP/HTML Visual Editor. To edit a page, you can use any combination of JDeveloper's page design tools you're comfortable with, namely:
Structure window
JSP/HTML Visual Editor
XML Source Editor
Property Inspector
Component Palette
When you make changes to a page in one of the design tools, the other tools are automatically updated with the changes you made.
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:
If not already open, double-click the starter JSF page in the Application Navigator to open it in the visual editor.
In the Component Palette, select ADF Faces Core from the dropdown list.
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.
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 Section 11.4.4, "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 Section 11.4.3.1, "Editing in the Structure Window" for additional information about inserting components using the Structure window.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 Chapter 12, "Displaying Data on a Page".
Figure 11-6 shows the Application Navigator view of the ViewController project after adding your first ADF Faces component in a page.
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 11-4.
Replaces the html, head, and body tags with afh:html, afh:head, and afh:body, respectively. See Example 11-5.
Adds the ADF Faces filter and mapping configuration settings to web.xml. See Section 11.4.2.1, "More About the web.xml File".
Adds the ADF Faces default render kit configuration setting to faces-config.xml. See Section 11.4.2.2, "More About the faces-config.xml File".
Creates a starter adf-faces-config.xml in /WEB-INF of the ViewController project. See Section 11.4.2.3, "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.
Tip:
The
WEB-INF/lib and WEB-INF/temp/adf folders are used by JDeveloper at runtime only. To reduce clutter in the Application Navigator, you may exclude them from the ViewController project. Double-click ViewController to open the Project Properties dialog. Under Project Content, select Web Application and then use the Excluded tab to add the folders you wish to exclude.Example 11-5 JSF JSP Document After You Add the First ADF Faces Component
<?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>
When you insert an ADF Faces component into a JSF page for the first time, JDeveloper automatically inserts the following ADF Faces configuration settings into web.xml:
ADF Faces filter: Installs oracle.adf.view.faces.webapp.AdfFacesFilter, which is a servlet filter to ensure that ADF Faces is properly initialized by establishing a AdfFacesContext object. AdfFacesFilter is also required for processing file uploads. The configuration setting maps AdfFacesFilter to a symbolic name.
ADF Faces filter mapping: Maps the JSF servlet's symbolic name to the ADF Faces filter.
ADF Faces resource servlet: Installs oracle.adf.view.faces.webapp.ResourceServlet, which serves up web application resources (such as images, style sheets, and JavaScript libraries) by delegating to a ResourceLoader. The configuration setting maps ResourceServlet to a symbolic name.
ADF Faces resource mapping: Maps the URL pattern to the ADF Faces resource servlet's symbolic name.
Example 11-6 shows the web.xml file after you add the first ADF Faces component.
Example 11-6 Configuring for ADF Faces in the web.xml File
<?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>
For reference information about the configuration elements you can use in web.xml when you work ADF Faces, see Section A.7.1, "Tasks Supported by the web.xml File".
Tip:
If you use multiple filters in your application, make sure that they are listed inweb.xml in the order in which you want to run them. At runtime, the filters are called in the sequence listed in that file.As mentioned earlier, JDeveloper creates one empty faces-config.xml file for you when you create a new project that uses JSF technology. When you insert an ADF Faces component into a JSF page for the first time, JDeveloper automatically inserts the default render kit for ADF components into faces-config.xml, as shown in Example 11-7.
Example 11-7 Configuring for ADF Faces Components in the faces-config.xml File
<?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>
When you create a JSF application using ADF Faces components, you configure ADF Faces–specific features (such as skin family and level of page accessibility support) in the adf-faces-config.xml file. The adf-faces-config.xml file has a simple XML structure that enables you to define element properties using the JSF expression language (EL) or static values.
In JDeveloper, when you insert an ADF Faces component into a JSF page for the first time, a starter adf-faces-config.xml file is automatically created for you in the /WEB-INF directory of your ViewController project. Example 11-8 shows the starter adf-faces-config.xml file.
Example 11-8 Starter adf-faces-config.xml File Created by JDeveloper
<?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>
By default JDeveloper uses the Oracle skin family for a JSF application. You can change this to minimal or use a custom skin. The SRDemo application uses the srdemo skin. If you wish to use a custom skin, you need to create the adf-faces-skins.xml configuration file, and modify adf-faces-config.xml to use the custom skin. For more information, see Section 22.3.1, "How to Use Skins".
To edit the adf-faces-config.xml file in JDeveloper, use the following procedure.
To edit the adf-faces-config.xml file:
In the Application Navigator, double-click adf-faces-config.xml to open the file in the XML editor.
If you're familiar with the element names, enter them in the editor. Otherwise use the Structure window to help you insert them.
To use the Structure window, follow these steps:
Right-click any element to choose from the Insert before or Insert after menu, and click the element you wish to insert.
Double-click the newly inserted element in the Structure window to open it in the properties editor.
Enter a value or select one from a dropdown list (if available).
In most cases you can enter either a JSF EL expression (such as #{view.locale.language=='en' ? 'minimal' : 'oracle'}) or a static value (e.g., <debug-output>true</debug-output>). EL expressions are dynamically reevaluated on each request, and must return an appropriate object (for example, a Boolean object).
Note:
All elements can appear in any order within the root element<adf-faces-config>. You can include multiple instances of any element. For reference information about the configuration elements you can use in adf-faces-config.xml, see Section A.10, "adf-faces-config.xml".Typically, you would want to configure the following in adf-faces-config.xml:
Level of page accessibility support (See Section 11.6, "Best Practices for ADF Faces")
Skin family (See Section 22.3, "Using Skins to Change the Look and Feel")
Time zone (See Section 22.4.2, "How to Configure Optional Localization Properties for ADF Faces")
Enhanced debugging output (See Section A.10.1.3, "Configuring For Enhanced Debugging Output")
Oracle Help for the Web (OHW) URL (See Section A.10.1.11, "Configuring the Help Site URL")
You can also register a custom file upload processor for uploading files. For information, see Section 19.6.5, "Configuring a Custom Uploaded File Processor".
Once you have configured elements in the adf-faces-config.xml file, you can retrieve the property values programmatically or by using JSF EL expressions. For more information, see Appendix A, "Retrieving Configuration Property Values From adf-faces-config.xml".
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 Section 22.4, "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 Section 19.4, "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 Section 11.6, "Best Practices for ADF Faces".
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.Most of the SRDemo pages use the af:messages tag to display error messages. When you create databound pages using the Data Control Palette, ADF Faces automatically inserts the af:messages tag for you at the top of the page. When there are errors at runtime, ADF Faces automatically displays the messages in a message box offset by color. For more information about error messages, see Section 20.7, "Displaying Error Messages".
In addition to reporting errors in a message box, you could use a general JSF error handling page for displaying fatal errors such as stack traces in a formatted manner. If you use a general error handling page, use the <error-page> element in web.xml to specify a type of exception for the error page (as shown in Example 11-9), or specify the error page using the JSP page directive (as shown in Example 11-10).
Example 11-9 Configuring Error-Page and Exception-Type in the web.xml File
<error-page> <exception-type>java.lang.Exception</exception-type> <location>/faces/infrastructure/SRError.jspx</location> </error-page>
Example 11-10 Specifying ErrorPage in a JSF Page Using JSP Directive
<jsp:root ...>
<jsp:output ...>
<jsp:directive.page contentType="text/html;charset=windows-1252"
errorPage="faces/SRError.jspx"/>
<f:view></f:view>
</jsp:root>
Consider the following if you intend to create and use a general JSF JSP error page:
Due to a current limitation in Sun's JSF reference implementation, if you use the Create JSF JSP wizard in JDeveloper to create a JSF JSP error page, you need to replace <f:view></f:view> with <f:subview></f:subview>.
In web.xml you need to add the following settings to ADF Faces filter mapping:
<dispatcher>REQUEST</dispatcher> <dispatcher>ERROR</dispatcher>
In the JSF page that uses the error page, <jsp:directive errorPage=""/> needs to include the faces/ prefix in the errorpage URI, as shown in this code snippet:
<jsp:directive.page contentType="text/html;charset=windows-1252"
errorPage="faces/SRError.jspx"/>
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 11-5.
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 Section 19.2, "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 11-7 and Figure 11-8.
For instructions on how to insert child components into facets or into panelPage itself, see Section 11.4.1, "How to Add UI Components to a JSF Page".
Figure 11-7 shows panelPage facets (numbered 1 to 12) for laying out branding images, global buttons, menu tabs, bars, and lists, and application-level text.
Table 11-3 shows the panelPage facets (as numbered in Figure 11-7), 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.
Table 11-3 PanelPage Facets for Branding Images, Navigation Menus, and Application-Level Text
| No. | Facet | Description |
|---|---|---|
|
1 |
|
For a corporate logo or organization branding using |
|
2 |
|
For an application logo or product branding using |
|
3 |
|
Typically use with |
|
4 |
|
For a |
|
5 |
|
For a |
|
6 |
|
For a |
|
7 |
|
For a |
|
8 |
|
For a |
|
9 |
|
For a search area using an |
|
10 |
|
For a link to more information about the application using |
|
11 |
|
For copyright text using outputText. The text appears above the |
|
12 |
|
For a link to a privacy policy statement for the application using |
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 11-8 shows panelPage facets (numbered 1 to 7) for laying out page-level actions and text.
Table 11-4 shows the panelPage facets (as numbered in Figure 11-8), and the preferred children components that you could use in them.
Table 11-4 PanelPage Facets for Page-Level Actions and Informational Text
| No. | Facet | Description |
|---|---|---|
|
1 |
|
For page-level actions that operate on the page content. Typically use with a |
|
2 |
|
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 |
|
3 |
|
For page-level information that is ancillary to the task at hand. Typically use with an |
|
4 |
|
For a "Return to X" link using |
|
5 |
|
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 |
|
6 |
|
For any other additional information. Typically use with a |
|
7 |
|
For presenting user login and connection information. Typically use with an |
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.After you've set up the panelPage facets, create your forms, tables, and other page body contents inside the panelPage component. ADF Faces panel components (and others) help you to organize content on a page. Use Table 11-5 to decide which components are suitable for your purposes.
For information about the component attributes you can set on each component, see the JDeveloper online help. For an image of what each component looks like, see the ADF Faces Core tag document at
Table 11-5 ADF Faces Layout and Panel Components
| To... | Use these components... |
|---|---|
|
Align form input components in one or more columns, with the labels right-justified and the fields left-justified |
|
|
Arrange components horizontally, optionally specifying a horizontal or vertical alignment |
|
|
Arrange components consecutively with wrapping as needed, horizontally in a single line, or vertically |
|
|
Create a bulleted list in one or more columns |
|
|
Lay out one or more components with a label, tip, and message |
Place multiple When laying out input component, the |
|
Place components in a container offset by color |
Typically use a single child inside |
|
Place components in predefined locations using facets |
|
|
Lay out a series of buttons |
|
|
Display additional page-level or section-level hints to the user |
|
|
Create page sections and subsections with headers |
|
|
Add quick links to sections in long pages |
Set the |
|
Let the user toggle a group of components between being shown (disclosed) and hidden (undisclosed) |
|
|
Let the user select and display a group of contents at a time |
A ShowOne component with ShowOne components include |
|
|
In JSF, backing beans are JavaBeans used mainly to provide UI logic for handling events and page flow. Typically you have one backing bean per JSF page. The backing bean contains any logic and properties for the UI components used on the page. For example, to programmatically change a UI component as a result of some user activity or to execute code before or after an ADF declarative action method, you provide the necessary code in the page's backing bean and bind the component to the corresponding property or method in the bean.
If you don't perform any UI component manipulation or conditional page flow logic, then you might not even need to use a backing bean for a page. The rest of this section provides information about using backing beans, if you need to use them for your pages.
For a backing bean to be available when the application starts, you register it as a managed bean with a name and scope in faces-config.xml. At runtime, whenever the managed bean is referenced on a page through a JSF EL value or method binding expression, the JSF implementation automatically instantiates the bean, populates it with any declared, default values, and places it in the managed bean scope as defined in faces-config.xml.
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:
In the Application Navigator, double-click faces-config.xml to open it in the default mode of the JSF Configuration Editor.
At the bottom of the editor, select the Overview tab to switch to the Overview mode, if necessary.
In the element list on the left, select Managed Beans.
Click New to open the Create Managed Bean dialog.
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.
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.
Note:
At this point, you haven't defined a strict relationship between the JSF page and the backing bean. You've simply configured a backing bean infaces-config.xml, which you can now reference via JSF EL expressions on a page. To define a strict relationship between a page and a backing bean, see Section 11.5.3, "How to Use a Backing Bean in a JSF Page".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 11-9.
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 11-11.
Example 11-11 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 11-12.
Example 11-12 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>
Note:
For a backing bean to access the ADF Model binding layer at runtime, the backing bean could inject the ADF binding container. For information about how this is done, see Section 11.5.7, "Using ADF Data Controls and Backing Beans".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.
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:
Open the JSF page in the visual editor. Select Design at the bottom of the editor window.
Choose Design > Page Properties to display the Page Properties dialog.
Select Component Binding.
Select Auto Bind.
Select a managed bean from the dropdown list or click New to configure a new managed bean for the page.
If the Auto Bind feature is turned on for a JSF page, you'll see a special comment line near the end of the page:
...
</f:view>
<!--oracle-jdev-comment:auto-binding-backing-bean-name:backing_SRDemopage-->
</jsp:root>
In faces-config.xml, a similar comment line is inserted at the end of the page's backing bean configuration:
<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>
<!--oracle-jdev-comment:managed-bean-jsp-link:1SRDemopage.jspx-->
</managed-bean>
When you turn on the Auto Bind feature for a page, JDeveloper does the following for you every time you add a UI component to the page:
Adds a property and property accessor methods for the component in the backing bean. For example, the next code snippet shows the code added for an inputText and a commandButton component:
private CoreInputText inputText1;
private CoreCommandButton commandButton1;
public void setInputText1(CoreInputText inputText1) {
this.inputText1 = inputText1;
}
public CoreInputText getInputText1() {
return inputText1;
}
public void setCommandButton1(CoreCommandButton commandButton1) {
this.commandButton1 = commandButton1;
}
public CoreCommandButton getCommandButton1() {
return commandButton1;
}
Binds the component to the corresponding bean property using an EL expression as the value for the binding attribute, as shown in this code snippet:
<af:inputText binding="#{backing_SRDemopage.inputText1}"
<af:commandButton binding="#{backing_SRDemopage.commandButton1}"
When you turn off the Auto Bind feature for a page, JDeveloper removes the special comments from the JSF page and faces-config.xml. The binding EL expressions on the page and the associated backing bean code are not deleted.
Tip:
When Auto Bind is turned on and you delete a UI component from a page, JDeveloper automatically removes the corresponding property and accessor methods from the page's backing bean.Managed beans are any application JavaBeans that are registered in the JSF faces-config.xml file. Backing beans are managed beans that contain logic and properties for some or all UI components on a JSF page. If you place, for example, validation and event handling logic in a backing bean, then the code has programmatic access to the UI components on the page when the UI components are bound to properties in the backing bean via the binding attribute.
In this guide, the term backing bean might be used interchangeably with the term managed bean, because all backing beans are managed beans. You can, however, have a managed bean that is not a backing bean—that is, a JavaBean that does not have properties and property getter and setter methods for UI components on a page, but the bean is configured in faces-config.xml, and has code that is not specific to any single page. Examples of where managed beans that are not backing beans are used in the SRDemo application include beans to:
Access authenticated user information from the container security
Create the navigation menu system (such as menu tabs and menu bars).
Expose String resources in a bundle via EL expressions
Managed bean properties are any properties of a bean that you would like populated with a value when the bean is instantiated. The set method for each declared property is run once the bean is constructed. To initialize a managed bean's properties with set values, use the <managed-property> element in faces-config.xml. When you configure a managed property for a managed bean, you declare the property name, its class type, and its default value, as shown in Example 11-13.
Example 11-13 Managed Bean Property Initialization Code in the faces-config.xml File
<managed-bean>
<managed-bean-name>tax</managed-bean-name>
<managed-bean-class>com.jsf.databeans.TaxRateBean</managed-bean-class>
<managed-bean-scope>application</managed-bean-scope>
<managed-property>
<property-name>rate</property-name>
<property-class>java.lang.Float</property-class>
<value>5</value>
</managed-property>
</managed-bean>
In Example 11-13, the rate property is initialized with a value of 5 (converted to a Float) when the bean is instantiated using the EL expression #{tax.rate}.
Managed beans and managed bean properties can be initialized as lists or maps, provided that the bean or property type is a List or Map, or implements java.util.Map or java.util.List. The default types for the values within a list or map is java.lang.String.
Example 11-14 shows an example of a managed bean that is a List.
Example 11-14 Managed Bean List in the faces-config.xml File
<managed-bean>
<managed-bean-name>options</managed-bean-name>
<managed-bean-class>java.util.ArrayList</managed-bean-class>
<managed-bean-scope>application</managed-bean-scope>
<list-entries>
<value>Text Only</value>
<value>Text + HTML</value>
<value>HTML Only</value>
</list-entries>
</managed-bean>
When the application encounters the EL expression #{options.text}, a List object is created and initialized with the values from the declared list-entries' values. The managed-property element is not declared, but the list-entries are child elements of the managed-bean element instead.
Tip:
Managed beans can only refer to managed properties in beans that have the same scope or a scope with a longer lifespan. For example asession scope bean cannot refer to a managed property on a request scoped bean.When you create databound UI components by dropping items from the Data Control Palette on your JSF page, JDeveloper does many things for you, which are documented in Section 12.2.3, "What Happens When You Use the Data Control Palette". The databound UI components use ADF data binding EL expressions, such as #{bindings.ProductName.inputValue}, to reference the associated binding objects in the page's binding container, where bindings is the reference to the ADF binding container of the current page.
In the backing bean of a page that uses ADF data bindings, sometimes you might want to reference the binding container's binding objects. To reference the ADF binding container, you can resolve a JSF value binding to the #{bindings} EL expression and cast the result to an oracle.binding.BindingContainer interface. Or for convenience, you can add a managed property named bindings that references the same #{bindings} EL expression, to the page's managed bean configuration in faces-config.xml so that the backing bean can work programmatically with the ADF binding container at runtime. Example 11-15 shows the bindings managed property in the backing_SRMain managed bean for the SRMain page.
Example 11-15 Bindings Managed Property in the faces-config.xml File
<faces-config xmlns="http://java.sun.com/JSF/Configuration">
...
<managed-bean>
<managed-bean-name>backing_SRMain</managed-bean-name>
<managed-bean-class>oracle.srdemo.view.backing.SRMain</managed-bean-class>
<managed-bean-scope>request</managed-bean-scope>
<managed-property>
<property-name>bindings</property-name>
<value>#{bindings}</value>
</managed-property>
</managed-bean>
...
</faces-config>
In the backing bean, add the getter and setter methods for the binding container. Example 11-16 shows the part of SRMain.java that contains the relevant code for bindings.
Example 11-16 Bindings Getter and Setter Methods in a Backing Bean
...
import oracle.binding.BindingContainer;
private BindingContainer bindings;
public BindingContainer getBindings() {
return this.bindings;
}
public void setBindings(BindingContainer bindings) {
this.bindings = bindings;
}
...
At runtime, when the application encounters an ADF data binding EL expression that refers to the ADF binding container, such as #{bindings.bindingObject.propertyName}, JSF evaluates the expression and gets the value from the binding object.
For more information about ADF data binding EL expressions and ADF binding properties, see Section 12.6, "Creating ADF Data Binding EL Expressions".
For an overview of how you might use JSF backing beans with ADF Model and ADF Business Components, see Chapter 1, "Introduction to Oracle ADF Applications".
Consider the following best practices when developing with ADF Faces:
While both JSP documents (.jspx) and JSP pages (.jsp) can be used, Oracle recommends working with JSP documents (.jspx) when using ADF Faces components in your JSF pages because JSP documents are well-formed XML documents. The XML standard offers many benefits such as validating against a document type definition, and parsing to create documentation or audit reports.
Use token-based client-side state saving instead of server-side state saving by setting the value of javax.faces.STATE_SAVING_METHOD in web.xml to client (which matches the default server-side behavior that will be provided in JSF 1.2).
While server-side state saving can provide somewhat better performance, client-side state saving is recommended as it provides better support for failover and the back button, and for displaying multiple windows simultaneously. Token-based client-side state saving results in better server performance because CPU and I/O consumption is lower.
Note that javax.faces.STATE_SAVING_METHOD must be set to server for ADF Telnet applications because the Industrial Telnet Server does not currently support saving state on the client.
Remove or disable debug features to improve the performance of deployed applications:
In web.xml, disable oracle.adf.view.faces.CHECK_FILE_MODIFICATION. By default, this parameter is false. If it is set to true, ADF Faces automatically checks the modification date of your JSPs, and discards saved state when they change. For testing and debugging in JDeveloper's embedded OC4J, you don't need to explicitly set this parameter to true because ADF Faces automatically detects the embedded OC4J and runs with the file modification checks enabled. But when you deploy the application, you should set the parameter to false.
For testing and debugging in JDeveloper's embedded OC4J, you don't need to explicitly set this parameter to true because ADF Faces automatically detects the embedded OC4J and runs with the file modification checks enabled.
In web.xml, disable oracle.adf.view.faces.DEBUG_JAVASCRIPT. The default value of this parameter is false. This means that by default, ADF Faces obfuscates JavaScript and removes comments and whitespace to reduce the size of the JavaScript download to the client. During application development, you might set the parameter to true (to turn off obfuscation) so that you can debug JavaScript easier, but when you deploy the application, you should set the parameter to false.
In adf-faces-config.xml, set <debug-output> to false. ADF Faces enhances debugging output when <debug-output> is true, by adding automatic indenting and extra comments, and detecting for malformed markup problems, unbalanced elements, and common HTML errors. The enhanced debug output is not necessary in deployed applications.
ADF Faces input components provide support for automatic form submission via the autoSubmit attribute. When the autoSubmit attribute is set to true, and an appropriate action takes place (such as a value change), the input component automatically submits the form it is enclosed in through a partial page submit. Thus you can update a portion of a page without having to redraw the entire page, which is known as partial page rendering. For information about using partial page rendering, see Section 19.4, "Enabling Partial Page Rendering".
ADF Faces performs client-side and server-side validation upon an auto submit execution. But if both autoSubmit and immediate attributes on ADF Faces input components are set to true, then ADF Faces doesn't perform client-side validation.
When laying out ADF Faces input components inside panelLabelAndMessage components, you must set the simple attributes on the input components to true. For accessibility purposes, set the for attribute on panelLabelAndMessage to the first input component. For proper alignment, place multiple panelLabelAndMessage components in a panelForm.
Although ADF Faces ignores label and message attributes on "simple" input components, you must set the label attribute on a "simple" component in this version of ADF Faces for component-generated error messages to display correctly.
If both styleClass and styleUsage attributes are set on a component, styleClass has precedence over styleUsage.
ADF Faces provides three levels of page accessibility support, which is configured in adf-faces-config.xml using the <accessibility-mode> element. The acceptable values for <accessibility-mode> are:
default: By default ADF Faces generates HTML code that is accessible to disabled users.
screenReader: ADF Faces generates HTML code that is optimized for the use of screen readers. The screenReader mode facilitates disabled users, but it may degrade the output for regular users. For example, access keys are disabled in screen reader mode.
inaccessible: ADF Faces removes all code that does not affect sighted users. This optimization reduces the size of the generated HTML. The application, however, is no longer accessible to disabled users.
Images that are automatically generated by ADF Faces components have built-in descriptions that can be read by screen readers or nonvisual browsers. For images generated from user-supplied icons and images, make sure you set the shortDesc or searchDesc attribute. Those attributes transform into HTML alt attributes. For images produced by certain ADF Faces components such as menuTabs and menuButtons, make sure you set the text or icon attribute on commandMenuItem because ADF Faces uses those values to generate text that describes the menu name as well as its state.
Similarly for table and outputText components, set the summary and description attribute, respectively, for user agents rendering to nonvisual media. If you use frames, provide links to alternative pages without frames using the alternateContent facet on frameBorderLayout. Within each frame set the shortDesc and longDescURL attributes.
Specify an access key for input, command, and go components such as inputText, commandButton, and goLink.
Typically, you use the component's accessKey attribute to set a keyboard character. For command and go components, the character specified by the attribute must exist in the text attribute of the component instance. If it does not exist, ADF Faces does not display the visual indication that the component has an access key
You can also use labelAndAccessKey on input components, or textAndAccessKey on command and go components. Those attributes let you set the label or text value, and an access key for the component at the same time. The conventional ampersand notation to use is & in JSP documents (.jspx). For example, in this code snippet:
<af:commandButton textAndAccessKey="&Home"/>
... the button text is Home and the access key is H, the letter that is immediately after the ampersand character.
Using access keys on goButton and goLink components may immediately activate them in some browsers. Depending on the browser, if the same access key is assigned to two or more go components on a page, the browser may activate the first component instead of cycling among the components that are accessed by the same key.
If you use a space as the access key, you need to provide a way to tell the user that Alt+Space or Alt+Spacebar is the access key because there is no good way to present a blank or space visually in the component's label or textual label. For example, you could provide some text in a component tooltip using the shortDesc attribute.
Access keys are not displayed if the accessibility mode is set to screen reader mode.
Enable application view caching by setting the value of oracle.adf.view.faces.USE_APPLICATION_VIEW_CACHE in web.xml to true.
When application view caching is enabled, the first time a page is viewed by any user, ADF Faces caches the initial page state at an application level. Subsequently, all users can reuse the page's cached state coming and going, significantly improving application performance.
While application view caching can improve a deployed application's performance, it is difficult to use during development and there are some coding issues that should be considered. For more detailed information about using application view caching, see "Configuring ADF Faces for Performance" in the "Configuring ADF Faces" section of the ADF Faces Developer's Guide.
For ADF Faces deployment best practices, see Chapter 34, "Deploying ADF Applications".
Increase throughput and shorten response times by caching content with the ADF Faces Cache tag library. Caching stores all or parts of a web page in memory for use in future responses. It significantly reduces response time to client requests by reusing cached content for future requests without executing the code that created it. For more information, see Chapter 23, "Optimizing Application Performance with Caching".
