Nesting Components Inside Components That Allow Stretching

8-12 Web User Interface Developers Guide for Oracle Application Development Framework Components that can be stretched but do not stretch their children are considered transition components. Transition components must always be used between a component that stretches its children and a component that does not stretch.

8.2.3 Using Quick Start Layouts

When you use the New Gallery Wizard to create a JSF JSP page or a page fragment, you can choose from a variety of predefined quick start layouts. When you choose one of these layouts, JDeveloper adds the necessary components and sets their attributes to achieve the look and behavior you want. You can choose from one-, two-, and three-column formats. Within those formats, you can choose how many separate panes will be displayed in each column, and if those panes can stretch or remain a fixed size. Figure 8–5 shows the different layouts available in the two-column format. Figure 8–5 Quick Layouts Along with adding layout components, you can also choose to apply a theme to the chosen quick layout. These themes add color styling to some of the components used in the quick start layout. To see the color and where it is added, see Appendix D, Quick Start Layout Themes. For more information about themes, see Section 20.3.4, How to Apply Themes to Components. In addition to saving time, when you use the quick layouts, you can be sure that layout components are used together correctly to achieve the desired outcome. For more information about creating pages using the quick layouts, see Section 2.4, Creating a View Page.

8.2.4 Tips for Using Geometry-Managed Components

To ensure your page is displayed as expected in all browsers, use one of the quick layouts provided by JDeveloper when you create a page. These ensure that the correct Organizing Content on Web Pages 8-13 components are used and configured properly. For more information, see Section 8.2.3, Using Quick Start Layouts. However, if you wish to create your layout yourself, follow these tips for creating a layout that includes both stretched and flowing components: ■ Place the page contents inside a root component that performs geometry management, either panelStretchLayout, panelSplitter, panelAccordion with a showDetailItem, or panelTabbed with a showDetailItem. ■ Never specify a height value with percent units. Instead, build a component structure out of components that support being stretched and that stretch their child components. ■ Inside this stretchable structure, create islands of nonstretched or flowing components by using transition components, such as the panelGroupLayout component with the layout attribute set to scroll. This component will provide the transition between stretched and flowing components because it supports being stretched but will not stretch its child components. ■ Never try to stretch something vertically inside a nonstretched or flowing container because it will not act consistently across web browsers. ■ For components contained in a parent flowing component that is, a component that does not stretch its children, do not set widths greater than 95. If you do, you may get unexpected results. ■ If the parent component is 768 pixels or greater, set the styleClass attribute on the component to be stretched to AFStretchWidth. This style will stretch the component to what appears to be 100 of the parent container, taking into account different browsers and any padding or borders on the parent. ■ If the parent component is 768 pixels or less, set the styleClass attribute on the component to be stretched to AFAuxiliaryStretchWidth. This style will stretch the component to what appears to be 100 of the parent container, taking into account different browsers and any padding or borders on the parent. ■ Never use the position style. ■ Ensure that the maximized attribute on the document tag is set to true this is the default. For more information about setting the attribute, see Section 8.2.5, How to Configure the document Tag. The remainder of this chapter describes the ADF Faces layout components and how they can be used to design a page. You can find information about how each component handles stretching in the respective What You May Need to Know About Geometry Management sections. Best Practice: Use quick start layouts to avoid layout display issues. Note: The two different styles are needed due to how Microsoft Internet Explorer 7 computes widths inside scrolling containers this has been resolved in Internet Explorer 8. Unless you can control the version of browser used to access your application, you should use these styles as described. 8-14 Web User Interface Developers Guide for Oracle Application Development Framework

8.2.5 How to Configure the document Tag

The document tag contains a number of attributes that you can configure to control behavior for the page. For example, you can configure the tag so that one component has focus when the page is first rendered. You can also configure the tag to display a warning message if a user attempts to navigate off the page and the data has not been submitted. You can also set the document to use a different state saving method than the rest of the application. To configure the document tag: 1. In the Structure window, select the af:document node. 2. In the Property Inspector, expand the Common section and set the following: ■ InitialFocusId : Use the dropdown menu to choose Edit. In the Edit Property dialog, select the component that should have focus when the page first renders. Because this focus happens on the client, the component you select must have a corresponding client component. For more information, see Section 3.4, Instantiating Client-Side Components. ■ Maximized : Set to true if you want the root component to expand to fit all available browser space. When the document tag’s maximized attribute is set to true, the framework searches for a single visual root component, and stretches that component to consume the browsers viewable area, provided that the component can be stretched. Examples of components that support this are panelStretchLayout and panelSplitter. The document tag’s maximized attribute is set to true by default. For more information, see Section 8.2.1, Geometry Management and Component Stretching. ■ Title : Enter the text that should be displayed in the title bar of the browser.

3. Expand the Appearance section and for the FailedConnectionText attribute, enter

the text you want to be displayed if a connection cannot be made to the server. 4. Expand the Other section and set the following: ■ UncommitedDataWarning : Set to on if you want a warning message displayed to the user when the application detects that data has not been committed. This can happen because either the user attempts to leave the page without committing data or there is uncommitted data on the server. By default, this is set to off. ■ StateSaving : Set to the type of state saving you want to use for a page. For ADF Faces applications, it is recommended to have the application use client state saving with tokens, which saves page state to the session and persists a token to the client. This setting affects the application globally, such that all pages have state saved to the session and persist tokens with information regarding state. However, there may be a page for which you which you want the state saved differently. For example, when a user posts back to a login page after an extended period of time, you do not want the session time out error to be displayed. By changing the stateSaving attribute on the page to client, then when the user posts back to the login page, the time out error will not display. You can override the global setting in web.xml to one of the following for the page: Organizing Content on Web Pages 8-15 – client : The state is saved fully to the client, without the use of tokens. This setting keeps the session expired messages from being displayed. – default : The state of the page is based on whatever is set in web.xml. – server : The state of the page is saved on the server. For more information about state saving, see Appendix A.2, Configuration in web.xml.

8.3 Arranging Contents to Stretch Across a Page

Use the panelStretchLayout component to arrange content in defined areas on a page and when you want the content to be able to stretch when the browser is resized. The panelStretchLayout component is one of the components that can stretch components placed in its facets. Figure 8–6 shows the component’s facets. Figure 8–6 Facets in the panelStretchLayout Component When you set the height of the top and bottom facets, any contained components are stretched up to fit the height. Similarly, when you set the width of the start and end facets, any components contained in those facets are stretched to that width. If no components are placed in the facets, then that facet does not render. That is, that facet will not take up any space. If you want that facet to take up the set space but remain blank, insert a spacer component. See Section 8.13, Separating Content Using Blank Space or Lines. Child Components components in the center facet are then stretched to fill up any remaining space. For more information about component stretching, see Section 8.2.1, Geometry Management and Component Stretching. Instead of setting the height of the top or bottom facet, or width of the start or end facet to a dimension, you can set the height or width to auto. This allows the facet to size itself to use exactly the space required by the child components of the facet. Space will be allocated based on what the web browser determines is the required amount of space to display the facet content. Note: Figure 8–6 shows the facets when the language reading direction of the application is configured to be left-to-right. If instead the language direction is right-to-left, the start and end facets are switched.