4.4 Laying Out a Web Page

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 4-5 shows an example of a page created by using a panelPage component.

Figure 4-5 Page Layout Created with a PanelPage Component

Page layout showing menu tabs and bar, and global buttons

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.

4.4.1 How to Add UI Components to a JSF Page

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

To insert UI components into a JSF page:

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.

You create your input or search forms, tables, and other page body contents inside the panelPage component.

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.

af:panelPage and PanelPage facet folders in Structure window

For more information about panelPage and its facets, see Section 4.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 4.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 5, "Displaying Data in a User Interface".

4.4.2 What Happens When You First Insert an ADF Faces Component

Figure 4-6 shows the Application Navigator view of the ViewController project after adding your first ADF Faces component in a page.

Figure 4-6 ViewController Project in the Navigator After You Insert the First ADF Faces Component

Expanded WEB-INF folder in Application Navigator

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

Imports the ADF Faces Core and HTML tag libraries (if not already inserted) into the page. See Example 4-4.
Replaces the html, head, and body tags with afh:html, afh:head, and afh:body, respectively. See Example 4-5.
Adds the ADF Faces filter and mapping configuration settings to web.xml. See Section 4.4.2.1, "More About the web.xml File".
Adds the ADF Faces default render kit configuration setting to faces-config.xml. See Section 4.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 4.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 4-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>

4.4.2.1 More About the web.xml File

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 4-6 shows the web.xml file after you add the first ADF Faces component.

Example 4-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.8.1, "Tasks Supported by the web.xml File".

Tip:

If you use multiple filters in your application, make sure that they are listed in web.xml in the order in which you want to run them. At runtime, the filters are called in the sequence listed in that file.

4.4.2.2 More About the faces-config.xml 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 4-7.

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

4.4.2.3 Starter adf-faces-config.xml File

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 4-8 shows the starter adf-faces-config.xml file.

Example 4-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. 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 14.3.1, "How to Use Skins".

4.4.2.3.1 Editing the adf-faces-config.xml File

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:
1. Right-click any element to choose from the Insert before or Insert after menu, and click the element you wish to insert.
2. Double-click the newly inserted element in the Structure window to open it in the properties editor.
3. 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.11, "adf-faces-config.xml".

Typically, you would want to configure the following in adf-faces-config.xml:

Level of page accessibility support (See Section 4.6, "Best Practices for ADF Faces")
Skin family (See Section 14.3, "Using Skins to Change the Look and Feel")
Time zone (See Section 14.4.2, "How to Configure Optional Localization Properties for ADF Faces")
Enhanced debugging output (See Section A.11.1.3, "Configuring For Enhanced Debugging Output")
Oracle Help for the Web (OHW) URL (See Section A.11.1.11, "Configuring the Help Site URL")

You can also register a custom file upload processor for uploading files. For information, see Section 11.6.5, "Configuring a Custom Uploaded File Processor".

4.4.2.3.2 Retrieving Configuration Property Values from the adf-faces-config.xml File

Once you have configured elements in the adf-faces-config.xml file, you can retrieve property values using one of the following approaches:

Programmatically using the AdfFacesContext class.

The AdfFacesContext class is a context class for all per-request and per-web application information required by ADF Faces. One instance of the AdfFacesContext class exists per request. Although it is similar to the JSF FacesContext class, the AdfFacesContext class does not extend FacesContext.

To retrieve an ADF Faces configuration property programmatically, first call the static getCurrentInstance() method to get an instance of the AdfFacesContext object, then call the method that retrieves the desired property, as shown in the following code snippet:
```
// Get an instance of the AdfFacesContext object
AdfFacesContext context = AdfFacesContext.getCurrentInstance();

// Get the time-zone property
TimeZone zone = context.getTimeZone();

// Get the right-to-left property
if (context.isRightToLeft())
{
  ...
}
```
For the list of methods to retrieve ADF Faces configuration properties, refer to the Javadoc for oracle.adf.view.faces.context.AdfFacesContext.
Using a JSF EL expression to bind a component attribute value to one of the properties of the ADF Faces implicit object (adfFacesContext).

The AdfFacesContext class contains an EL implicit variable, called adfFacesContext, that exposes the context object properties for use in JSF EL expressions. Using a JSF EL expression, you can bind a component attribute value to one of the properties of the adfFacesContext object. For example in the EL expression below, the currency-code property is bound to the currencyCode attribute value of the JSF ConvertNumber component:
```
<af:outputText>
  <f:convertNumber currencyCode="#{adfFacesContext.currencyCode}"/>
</af:outputText>
```

4.4.3 What You May Need to Know About Creating JSF Pages

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

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

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

Other non-JSF tags may be used with JSF tags but only with great care. For example, if you use c:if and c:choose, the id attributes of nested JSF tags must be set; if you nest non-JSF tags within JSF tags, you must wrap the non-JSF tags in f:verbatim; if you dynamically include JSP pages that contain JSF content, you must use f:subview and also wrap all included non-JSF content in f:verbatim.
In the SRDemo user interface, all String resources (for example, page titles and field labels) that are not retrieved from the ADF Model are added to a resource properties file in the ViewController project. If you use a resource properties file to hold the UI strings, use the f:loadBundle tag to load the properties file in the JSF page. For more information about resource bundles and the f:loadBundle tag, see Section 14.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 11.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 4.6, "Best Practices for ADF Faces".

4.4.3.1 Editing in the Structure Window

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

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

Horizontal line with upward pointing arrow in center

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.

Horizontal line with downward pointing arrow in center

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.

af:panelPage surrounded with box outline

Tip:

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

4.4.3.2 Displaying Errors

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 12.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 4-9), or specify the error page using the JSP page directive (as shown in Example 4-10).

Example 4-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 4-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"/>
```

4.4.4 Using the PanelPage Component

The SRDemo pages use panelPage as the main ADF Faces layout component, which lets you lay out an entire page with specific areas for navigation menus, branding images, and page body contents, as illustrated in Figure 4-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 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.
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. 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 11.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 4-7 and Figure 4-8.

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

4.4.4.1 PanelPage Facets

Figure 4-7 shows panelPage facets (numbered 1 to 12) for laying out branding images, global buttons, menu tabs, bars, and lists, and application-level text.

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

Page layout. See Table 4-3 for descriptions.

Table 4-3 shows the panelPage facets (as numbered in Figure 4-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 4-3 PanelPage Facets for Branding Images, Navigation Menus, and Application-Level Text

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

Tip:

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

Figure 4-8 shows panelPage facets (numbered 1 to 7) for laying out page-level actions and text.

Figure 4-8 Basic Page Layout with Page-Level Actions and Informational Text

Page layout. See Table 4-4 for descriptions.

Table 4-4 shows the panelPage facets (as numbered in Figure 4-8), and the preferred children components that you could use in them.

Table 4-4 PanelPage Facets for Page-Level Actions and Informational Text

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

Tip:

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

4.4.4.2 Page Body Contents

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

http://www.oracle.com/technology/products/jdev/htdocs/partners/addins/exchange/jsf/doc/tagdoc/core/imageIndex.html

Table 4-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	`panelForm`
Arrange components horizontally, optionally specifying a horizontal or vertical alignment	`panelHorizontal`
Arrange components consecutively with wrapping as needed, horizontally in a single line, or vertically	`panelGroup`
Create a bulleted list in one or more columns	`panelList`
Lay out one or more components with a label, tip, and message	`panelLabelAndMessage` Place multiple `panelLabelAndMessage` components in a `panelForm` When laying out input component, the `simple` attribute on the input component must be set to `true`.
Place components in a container offset by color	`panelBox` Typically use a single child inside `panelBox` such as `panelGroup` or `panelForm`, which then contains the components for display
Place components in predefined locations using facets	`panelBorder`
Lay out a series of buttons	`panelButtonBar`
Display additional page-level or section-level hints to the user	`panelTip`
Create page sections and subsections with headers	`panelHeader`, `showDetailHeader`
Add quick links to sections in long pages	Set the `quickLinksShown` attribute on `panelPage` to `true`
Let the user toggle a group of components between being shown (disclosed) and hidden (undisclosed)	`showDetail`
Let the user select and display a group of contents at a time	A ShowOne component with `showDetailItem` components ShowOne components include `showOneTab`, `showOneChoice`, `showOneRadio`, and `showOnePanel`
Insert separator lines or space in your layout	`objectSeparator`, `objectSpacer`