How to Use the panelTabbed Component

8-62 Web User Interface Developers Guide for Oracle Application Development Framework ■ StretchChildren : When set to first, stretches a single child component. However, the child component must allow stretching. For more information, see Section 8.9.4, What You May Need to Know About Geometry Management and the showDetailItem Component. For example, the File Explorer application uses showDetailItem components to display contents in the navigator panel. Because the Search Navigator requires more space when both navigators are expanded, its flex attribute is set to 2 and the showDetailItem component for the Folders Navigator uses the default flex value of 1. This setting causes the Search Navigator to be larger than the Folders Navigator when it is expanded. The user can change the panel heights at runtime, thereby changing the value of the flex and inflexibleHeight attributes. Those values can be persisted so that they remain for the duration of the user’s session. For information, see Chapter 31, Allowing User Customization on JSF Pages. Note the following additional information about flexible accordion panel contents: ■ There must be two or more panes showDetailItem components with flex values larger than 0 before ADF Faces can enable flexible contents. This is because ADF Faces uses the flex ratio between two components to determine how much space to allocate among the panel contents. At runtime, two or more panes must be expanded before the effect of flexible contents can be seen. ■ If the showDetailItem component has only one child component and the flex value is nonzero, and the stretchChildren attribute is set to first, ADF Faces will stretch that child component regardless of the discloseMany attribute value on the panelAccordion component. ■ When all showDetailItem components have flex values of 0 zero and their panel contents are disclosed, even though the disclosed contents are set to be inflexible, ADF Faces will stretch the contents of the last disclosed showDetailItem component as if the component had a flex value of 1, but only when that showDetailItem component has one child only, and the stretchChildren attribute is set to first. If the last disclosed panel has more than one child component or the stretchChildren attribute is set to none, the contents will not be stretched. Even with the flex attribute set, there are some limitations regarding geometry management. For more information, see Section 8.9.4, What You May Need to Know About Geometry Management and the showDetailItem Component.

6. Expand the Behavior section. Set DisclosureListener to the

disclosureListener method in a backing bean you want to execute when this panel or tab is selected by the user. For information about server disclosure events and event listeners, see Section 8.8.4, What You May Need to Know About Disclosure Events. Note: Instead of directly setting the value for the flex attribute, the File Explorer application uses an EL expression that resolves to a method used to determine the value. Using an EL expression allows you to programmatically change the value if you decide at a later point to use metadata to provide model information. Organizing Content on Web Pages 8-63

7. Set Disabled to true if you want to disable this panel or tab that is, the user will

not be able to select the panel or tab.

8. Set Disclosed to true if you want this panel or tab to show its child components.

By default, the disclosed attribute is set to false. This means the contents for this panel or tab are hidden. If none of the showDetailItem components has the disclosed attribute set to true, ADF Faces automatically shows the contents of the first enabled showDetailItem component except when it is a child of a panelAccordion component, which has a setting for zero disclosed panes. 9. For showDetailItem components used in a panelAccordion component, expand the Other section, and set DisplayIndex to reflect the order in which the showDetailItem components should appear. If you simply want them to appear in the order in which they are in the page’s code, then leave the default, -1. 10. If you chose to allow tab removal for a panelTabbed component, expand the Other section and set Remove to one of the following: ■ inherit : The corresponding tab can be removed if the parent panelTabbed component is configured to allow it. This is the default. ■ no : The corresponding tab cannot be removed, and will not display a close icon. ■ disabled : The corresponding tab will display a disabled close icon. Set ItemListener to an EL expression that resolves to a handler method that will handle the actual removal of a component. 11. To add toolbar buttons to a panel supported in the panelAccordion component only, in the Component Palette, from the Common Components panel, insert a Note: Note the difference between the disclosed and rendered attributes. If the rendered attribute value is false, it means that this accordion header bar or tab link and its corresponding contents are not available at all to the user. However, if the disclosed attribute is set to false, it means that the contents of the item are not currently visible, but may be made visible by the user because the accordion header bar or tab link are still visible. Note: While the user can change the value of the disclosed attribute by displaying or hiding the contents, the value will not be retained once the user leaves the page unless you configure your application to allow user customization. For information, see Chapter 31, Allowing User Customization on JSF Pages. Tip: If some showDetailItem components have -1 as the value for displayIndex, and others have a positive number, those with the -1 value will display after those with a positive number, in the order they appear in the page’s code. Tip: This value can be changed at runtime if the parent panelAccordion component is configured to allow reordering. 8-64 Web User Interface Developers Guide for Oracle Application Development Framework Toolbar into the toolbar facet of the showDetailItem component that defines that panel. Then, insert the desired number of commandToolbarButton components into the toolbar component. Although the toolbar facet is on the showDetailItem component, it is the panelAccordion component that renders the toolbar and its buttons. For information about using toolbar and commandToolbarButton, see Section 14.3, Using Toolbars. 12. To add contents to the panel, insert the desired child components into each showDetailItem component.

8.9.4 What You May Need to Know About Geometry Management and the showDetailItem Component

Both the panelAccordion or panelTabbed components can be configured to stretch when they are placed inside a component that uses geometry management to stretch its child components. However, for the panelAccordion component, the showDetailItem component will stretch only if the discloseMany attribute on the panelAccordion component is set to true that is, when multiple panes may be expanded to show their inflexible or flexible contents, the showDetailItem component contains only one child component, and the showDetailItem component’s stretchChildren attribute is set to first. By default, panel contents will not stretch. The showDetailItem component will allow stretching if: ■ It contains only a single child ■ Its stretchChildren attribute is set to first ■ The child has no width, height, border, and padding set ■ The child must be capable of being stretched When all of the preceding bullet points are true, the showDetailItem component can stretch its child component. The following components can be stretched inside the showDetailItem component: ■ inputText when configured to stretch ■ decorativeBox when configured to stretch ■ panelAccordion when configured to stretch ■ panelBox ■ panelCollection ■ panelDashboard when configured to stretch ■ panelGroupLayout only when the layout attribute is set to scroll or vertical ■ panelSplitter when configured to stretch ■ panelStretchLayout when configured to stretch ■ panelTabbed when configured to stretch Note: When an accordion panel is collapsed, ADF Faces does not display the toolbar and its buttons. The toolbar and its buttons are displayed in the panel header only when the panel is expanded. Organizing Content on Web Pages 8-65 ■ region ■ table when configured to stretch ■ tree when configured to stretch ■ treeTable when configured to stretch The following components cannot be stretched when placed inside a showDetailItem component: ■ panelBorderLayout ■ panelFormLayout ■ panelGroupLayout only when the layout attribute is set to default or horizontal ■ panelHeader ■ panelLabelAndMessage ■ panelList ■ tableLayout MyFaces Trinidad component You cannot place components that cannot stretch as a child to a component that stretches its child components. Therefore, if you need to place one of the components that cannot be stretched as a child of a showDetailItem component, you need to wrap that component in different component that does not stretch its child components. For example, if you want to place content in a panelList component and have it be displayed in a showDetailItem component, you might place a panelGroupLayout component with its layout attribute set to scroll as the chid of the showDetailItem component, and then place the panelList component in that component. For more information, see Section 8.2.1, Geometry Management and Component Stretching.

8.9.5 What You May Need to Know About showDetailItem Disclosure Events

The showDetailItem component inside of panelAccordion and panelTabbed components supports queuing of disclosure events so that validation is properly handled on the server and on the client. In general, for any component with the disclosed attribute, by default, the event root for the client AdfDisclosureEvent is set to the event source component: only the event for the panel whose disclosed attribute is true gets sent to the server. However, for the showDetailItem component that is used inside of panelTabbed or panelAccordion component, the event root is the panelTabbed or panelAccordion component that is, the event source parent component, not the event source component. This ensures that values from the previously disclosed panel will not get sent to the server. For example, suppose you have two showDetailItem components inside a panelTabbed or panelAccordion component with the discloseMany attribute set to false and the discloseNone attribute set to false. Suppose the showDetailItem 1 component is disclosed but not showDetailItem 2. Given this scenario, the following occurs: ■ On the client: – When a user clicks to disclose showDetailItem 2, a client-only disclosure event gets fired to set the disclosed attribute to false for the 8-66 Web User Interface Developers Guide for Oracle Application Development Framework showDetailItem 1 component. If this first event is not canceled, another client disclosure event gets fired to set the disclosed attribute to true for the showDetailItem 2 component. If this second event is not canceled, the event gets sent to the server; otherwise, there are no more disclosure changes. ■ On the server: – The server disclosure event is fired to set the disclosed attribute to true on the showDetailItem 2 component. If this first server event is not canceled, another server disclosure event gets fired to set the disclosed attribute to false for the showDetailItem 1 component. If neither server event is canceled, the new states get rendered, and the user will see the newly disclosed states on the client; otherwise, the client looks the same as it did before. For the panelAccordion component with the discloseMany attribute set to false and the discloseNone attribute set to true, the preceding information is the same only when the disclosure change forces a paired change that is, when two disclosed states are involved. If only one disclosure change is involved, there will just be one client and one server disclosure event. For the panelAccordion component with the discloseMany attribute set to true and any discloseNone setting, only one disclosure change is involved; there will just be one client and one server disclosure event. For additional information about disclosure events, see Section 8.8.4, What You May Need to Know About Disclosure Events.

8.10 Displaying Items in a Static Box

You can use the panelHeader component when you want header type functionality, such as message display or associated help topics, but you do not have to provide the capability to show and hide content. You can use the decorativeBox component when you need to transition to a different look and feel on the page. The decorativeBox component uses themes and skinning keys to control the borders and colors of its different facets. For example, depending on the skin you are using, if you use the default theme, the decorativeBox component body is white and the border is blue, and the top-left corner is rounded. If you use the medium theme, the body is a medium blue. For information about using themes and skins, see Chapter 20, Customizing the Appearance Using Styles and Skins The panelHeader component offers facets for specific types of components and the ability to open a help topic from the header. The following are the facets supported by the panelHeader component: ■ context: Displays information in the header alongside the header text. ■ help: Displays help information. Use only for backward compatibility. Use the helpTopicId attribute on the panelHeader component instead. ■ info: Displays information beneath the header text, aligned to the right. ■ legend: If help text is present, displays information to the left of the help content and under the info facets content. If help text is not present, the legend content will be rendered directly under the header. ■ toolbar: Displays a toolbar, before the menu bar. ■ menuBar: Displays a menu bar, after the toolbar. Organizing Content on Web Pages 8-67 Figure 8–40 shows the different facets in the panelHeader component. Figure 8–40 panelHeader and Its Facets When there is not enough space to display everything in all the facets of the title line, the panelHeader text is truncated and displays an ellipsis. When the user hovers over the truncated text, the full text is displayed in a tooltip, as shown in Figure 8–41 . Figure 8–41 Text for the panelHeader Is Truncated When there is more than enough room to display the contents, the extra space is placed between the context facet and the toolbar, as shown in Figure 8–42 . Figure 8–42 Extra Space Is Added Before the Toolbar You can configure panelHeader components so that they represent a hierarchy of sections. For example, as shown in Figure 8–43 , you can have a main header with a subheader and then a heading level 1 also with a subheader. Figure 8–43 Creating Subsections with the panelHeader Component Create subsections by nesting panelHeader components within each other. When you nest panelHeader components, the heading text is automatically sized according to the hierarchy, with the outermost panelHeader component having the largest text. For information about using the panelHeader component, see Section 8.10.1, How to Use the panelHeader Component. Note: While you can force the style of the text using the size attribute where 0 is the largest text, the value of the size attribute will not affect the hierarchy. It only affects the style of the text.