Oracle® Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework 11g Release 1 (11.1.1) B31974-03 |
|
![]() Previous |
![]() Next |
This chapter describes the steps you may need to take before using the Data Controls panel to create databound UI components on JSF pages.
This chapter includes the following sections:
Section 19.1, "Introduction to Developing a Web Application with ADF Faces"
Section 19.4, "Using a Managed Bean in a Fusion Web Application"
Most of what you need to know to get started with your web interface is covered in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework. However, using the ADF Model layer for data binding instead of JSF managed beans provides additional functionality, such as the ability to declaratively bind components to your business services (for more information on what ADF Model can provide, see Section 1.2.2, "ADF Model Layer"). This chapter provides a high-level overview of the web interface development process as detailed in the Faces guide, and also provides information about the additional functionality available when you use ADF Model data binding.
Following the development process outlined in Chapter 1, "Introduction to Building Fusion Web Applications with Oracle ADF", developing a web application with ADF Faces and using ADF Model for data binding involves the following steps:
Creating ADF Faces templates for your pages (optional)
Creating the individual pages and page fragments for regions to be used within a page
Creating any needed managed beans
Additionally, the lifecycle of a Fusion web application is different from that of a standard JSF or ADF Faces application. For more information about how the lifecycle works, see Chapter 20, "Understanding the Fusion Page Lifecycle".
As you design the flow of your application, you can begin to think about the design of your pages. To ensure consistency throughout your application, you use ADF page templates. These templates provide structure and consistency for other developers building web pages. Templates typically contain static areas which cannot be changed when they are used, and dynamic areas, where developers can place content specific to the page they are building.
For example, the StoreFront module of the Fusion Order Demo application contains a template that provides a top area for branding and navigation, a bottom area for copyright information, and a center area for the main content of the page. Page developers do not need to do anything to the branding and copyright information when they use the template. They need only to develop the main content area.
In addition to using ADF Faces components to build a template, you can add attributes to the template definition. These attributes provide placeholders for specific information that the page developer needs to provide when using the template. For example, the template in the StoreFront module application contains an attribute for a welcome message. When page developers use this template, they can add a different welcome message for each page.
You can also add facet references to the template. These references act as placeholders for content on the page. Figure 19-1 shows a rendition of how the StoreFrontTemplate
template used in the StoreFront module application uses facet references.
In this template, facet references are used inside four different panelSplitter
components. When the home page was created using this template, the navigational links were placed in the Header facet and the accordion panels that hold the navigation trees and search panels were placed in the Start facet. The cart summary was placed in the End facet, and the main portion of the page was placed in the Center facet. The copyright information was placed in the Bottom facet.
When you choose to add databound components to a page template, an associated page definition file and the other metadata files that support ADF Model layer data binding are created. Each component is bound in the same fashion as for standard JSF pages, as described in Chapter 12, "Using Oracle ADF Model in a Fusion Web Application". You can also create model parameters for the template. The values for these parameter can then be set at runtime by the calling page.
For example, if you wanted a list of products to appear on each page that uses the template, you could drag and drop the ProductName
attribute of the Products
collection as a list. Or, if you wanted the pages to display the currently selected product ID, you could create a model parameter for the template that would evaluate to that product's ID.
Note: Templates are primarily a project artifact. While they can be reused between projects and applications, they are not fully self-contained and will always have some dependencies to external resources, for example, any ADF data binding,Strings from a message bundle, images, and managed beans. |
Creating a page template for use in an application that uses ADF Business Components and ADF Model layer data binding is the same as creating a standard ADF Faces page template, as documented in the "Using Page Templates" section of the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework. Once you create the template, you can drag and drop items from the Data Controls panel. JDeveloper automatically adds the page definition file when you drag and drop items from this panel.
The Create JSF Page Template wizard also allows you to create model parameters for use by the template.
To add model parameters to a template:
Create a page template following the instructions in the "How to Create a Page Template" section of the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework. However, do not complete the dialog.
In the Create JSF Page Template dialog, select Create Associated ADFm Page Definition.
Note: You only need to select this checkbox if you wish to add parameters. JDeveloper automatically adds the page definition file when you drag and drop items from the Data Controls panel. |
Click the Model Parameters tab.
Click the Add icon.
Enter the following for the parameter:
Id: Enter a name for the parameter.
Value: Enter a value or an EL expression that can resolve to a value. If needed, click the Invoke Expression Builder (...) button to open the Expression Builder. You can use this to build the expression. For more information about EL expressions and the EL expression builder, see Chapter 12, "Creating ADF Data Binding EL Expressions".
Option: Determines how the parameter value will be specified. Enter optional
if the value does not need to be specified. Enter final
if the parameter value cannot be supplied from the usage, and must have some default value or other means of obtaining the value, for example from an EL expression. Enter mandatory
if the value must be specified by the usage.
Read Only: Select if the parameter's value is to be read-only and should not be overwritten
Create more parameters as needed. Use the order buttons to arrange the parameters into the order in which you want them to be evaluated.
You can now use the Data Controls panel to add databound UI components to the page, as you would for a standard JSF page, as described in the remaining chapters in this part of the book.
When you add ADF databound components to a template or create model parameters for a template, a page definition file is created for the template, and any model parameters are added to that file. Example 19-1 shows what the page definition file for a template for which you created a productId
model parameter might look like.
Example 19-1 Model Parameters in a Page Definition for a Template
<parameters> <parameter id="productID" readonly="true" value="#{bindings.productId.inputValue}"/> </parameters> <executables/> <bindings/>
Parameter binding objects declare the parameters that the page evaluates at the beginning of a request (for more information about binding objects and the ADF lifecycle, see Chapter 12, "Using Oracle ADF Model in a Fusion Web Application"). However, since a template itself is never executed, the page that uses the template (the calling page) must access the binding objects created for the template (including parameters or any other type of binding objects created by dragging and dropping objects from the Data Controls panel onto the template).
In order to access the template's binding objects, the page definition file for the calling page must instantiate the binding container represented by the template's page definition file. As a result, a reference to the template's page definition is inserted as an executable into the calling page's page definition file, as shown in Example 19-2.
Example 19-2 Reference to Template's Page Definition as an Executable
<executables> <page path="oracle.foddemo.storefront.pageDefs.templates_MyTemplatePageDef" id="pageTemplateBinding"/> </executables>
In this example, the calling page was built using the MyTemplate
template. Because the page definition file for the MyTemplate
template appears as an executable for the calling page, when the calling page's binding container is instantiated, it will in turn instantiate the MyTemplatePageDef
's binding container, thus allowing access to the parameter values or any other databound values.
Because there is an ID for this reference (in this case, pageTemplateBinding
), the calling page can have components that are able to access values from the template. When you create a JSF page from a template, instead of you having to repeat the code contained within the template, you can use the af:pageTemplate
tag on the calling page. This tag contains the path to the template JSF page.
Additionally, when the template contains any ADF data binding, the value of that tag is the ID set for the calling page's reference to the template's page definition, as shown in Example 19-3. This binding allows the component access to the binding values from the template.
When a page is created using a template that contains ADF data binding, the following happens:
The calling page follows the standard JSF/ADF lifecycle, as documented in Chapter 20, "Understanding the Fusion Page Lifecycle". As the page enters the Restore View phase, the URL for the calling page is sent to the binding context, which finds the corresponding page definition file.
During the Initialize Context phase, the binding container for the calling page is created based on the page definition file.
During the Prepare Model phase, the page template executable is refreshed. At this point, the binding container for the template is created based on the template's page definition file, and added to the binding context.
The lifecycle continues, with UI components and bindings from both the page and the template being processed.
Creating a web page for an application that uses ADF Model layer data binding is no different than described in the "Creating a JSF Page" section in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework. You can create pages either by double-clicking a view activity in a task flow or by using the New Gallery. When creating the page (or dropping a view activity onto a task flow), you can choose to create the page as a JSF JSP or as a JSF JSP fragment. JSF fragments provide a simple way to create reusable page content in a project, and are what you use when you wish to use task flows as regions on a page. When you modify a JSF page fragment, the JSF pages that consume the page fragment are automatically updated.
When you begin adding content to your page, you typically use the Component Palette and Data Controls panel of JDeveloper. The Component Palette contains all the ADF Faces components needed to declaratively design your page. Once you have the basic layout components placed on the page, you can then drag and drop items from the Data Controls panel to create ADF Model databound UI components. The remaining chapters in this part of the book explain in detail the different types of databound components and pages you can create using ADF Model data binding.
Managed beans are Java classes that you register with the application using various configuration files. When the JSF application starts up, it parses these configuration files, and the beans listed within them are made available. The managed beans can be referenced in an EL expression, allowing access to the beans' properties and methods. Whenever a managed bean is referenced for the first time and it does not already exist, the Managed Bean Creation Facility instantiates the bean by calling the default constructor method on it. If any properties are also declared, they are populated with the declared default values.
Often, managed beans handle events or some manipulation of data that is best handled at the front end. For a more complete description of how managed beans are used in a standard JSF application, see the Java EE 5 tutorial on Sun's web site (http://java.sun.com
).
In an application that uses ADF data binding and ADF task flows, managed beans are registered in different configuration files from those used for a standard JSF application. In a standard JSF application, managed beans are registered in the faces-config.xml
configuration file. In a Fusion web application, managed beans can be registered in the faces-config.xml
file, the adfc-config.xml
file, or a task flow definition file. Which configuration file you use to register a managed bean depends on what will need to access that bean, whether or not it needs to be customized at runtime, what the bean's scope is, and in what order all the beans in the application need to be instantiated. Table 19-1 describes how registering a bean in each type of configuration file affects the bean.
Note: Registering managed beans within thefaces-config.xml file is not recommended in a Fusion web application.
Managed beans accessed within the task flow definition must be registered in that task flow's definition file. |
Table 19-1 Effects of Managed Bean Configuration Placement
Managed Bean Placement | Effect |
---|---|
|
|
Task flow definition file |
|
|
|
As a general rule for Fusion web applications, a bean that may be used in more than one page or task flow, or one that is used by pages within the main unbounded task flow (adfc-config
), should be registered in the adfc-config.xml
configuration file. A managed bean that will be used only by a specific task flow should be registered in that task flow's definition file. There should be no beans registered in the faces-config.xml
file.
Note: If you create managed beans from dialogs within JDeveloper, the bean is registered in theadfc-config.xml file, if it exists. |
For example, in the StoreFront module, the myOrdersBean
managed bean is used by the myOrders.jspx
page to handle the case where a user decides to cancel editing an order, and the edits have already been committed to the model but have not yet been persisted to the database. Because this bean is used by a page within the adfc-config
unbounded task flow, it is registered in the adfc-config.xml
file. The custRegBasicInformationBean
is a managed bean used by the basicInformation
JSF fragment to handle the selections in the shuttle component on that page. Because it is used solely within the customer-registration
task flow, it is registered in the customer-registration-task-flow
definition file.
This section describes how to create a managed bean for use within a task flow (either the default adfc-config
flow or any bounded task flow). For more information regarding managed beans and how they are used as backing beans for JSF pages, see the "Creating and Using Managed Beans" section in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.
Within the editors for a task flow definition, you can create a managed bean and register it with the JSF application at the same time.
To create a managed bean for a task flow:
In the Application Navigator, open either the adfc-config.xml
file or any other task flow definition file.
At the bottom of the window, select the Overview tab.
In the navigation list on the left, select the Managed Beans tab. Figure 19-2 shows the editor for the adfc-config.xml
file.
Click the Add icon to add a row to the Managed Beans table.
In the Property Inspector, enter the following:
managed-bean-name: A name for the bean.
managed-bean-class: If the corresponding class has already been created for the bean, use the browse (...) button for the managed-bean-class field to search for and select the class. If a class does not exist, enter the name you'd like to use. Be sure to include any package names as well. You can then use the drop-down menu to choose Generate Class, and the Java file will be created for you.
managed-bean-scope: The bean's scope. For more information about scope values, see Section 20.3, "Object Scope Lifecycles".
Note: You can also set the scope tonone . While not technically a scope, none means that the bean will not live within any particular scope, but will instead be instantiated each time it is referenced. You should set a bean's scope to none when it is referenced by another bean. |
You can optionally add needed properties for the bean. With the bean selected in the Managed Beans table, click the Add icon for the Managed Properties table. In the Property Inspector, enter a property name (other fields are optional).
Note: While you can declare managed properties using this editor, the corresponding code is not generated on the Java class. You will need to add that code by creating private member fields of the appropriate type and then using the Generate Accessors menu item on the context menu of the source editor to generate the corresponding getter and setter methods for these bean properties. |
When you use the configuration editor to create a managed bean and elect to generate the Java file, JDeveloper creates a stub class with the given name and a default constructor. Example 19-4 shows the code added to the MyBean
class stored in the view package.
Example 19-4 Generated Code for a Managed Bean
package view; public class MyBean { public MyBean() { } }
You now need to add the logic required by your task flow or page. You can then refer to that logic using an EL expression that refers to the managed-bean-name
value given to the managed bean. For example, to access the myInfo
property on the bean, the EL expression would be:
#{my_bean.myInfo}
JDeveloper also adds a managed-bean
element to the appropriate task definition file. Example 19-5 shows the managed-bean
element created for the MyBean
class.