Skip to content

FoldingPanel 2.x

Jump to bottom
RomanPerin edited this page Aug 27, 2014 · 3 revisions

TOCSTART

TOCEND

The FoldingPanel component is a container for other components that can be collapsed or expanded by the user. It consists of a bar displaying the caption, an expandable/collapsible container, and a toggle button. User is allowed to switch between the states by click on toggle button and/or click on caption.


Online Demo

Key Features

Defining the Content

To add the FoldingPanel component to a page, use the <o:foldingPanel> tag. You can add any child components inside the FoldingPanel component to display them in the container. To specify the caption for the FoldingPanel component, use either the caption attribute to set caption text or the "caption" facet if you'd like to create a more complex caption content specified with components.

In the example below, the FoldingPanel component has a caption and the DropDownField component as its child component.

<o:foldingPanel caption="A panel for color selection">
  <h:outputText value="Select color:"/>
  <o:dropDownField>
    <o:dropDownItems value="#{ColorBean.items}"/>
  </o:dropDownField>
</o:foldingPanel>

The state of the FoldingPanel component is specified by the boolean expanded attribute. By default, its value is set to "true", which displays the FoldingPanel component in the expanded state, where all its child components are visible. In the collapsed state, only the caption of the FoldingPanel component is visible.

User can switch between the states of FoldingPanel by toggle button or/and by click on the caption area. By default, only toggle button switches FoldingPanel's state. To switch states by clicking on caption you can set toggleOnCaptionClick attribute to "true".

By default, the FoldingPanel component expands downwards. However, you can specify different folding directions by using the foldingDirection attribute. It can take one of the following values: "up", "down", "left" or "right". Currently, in case of left-hand and right-hand folding directions, the component displays only the toggle button to expand the container.

Customizing Caption Buttons

By default FoldingPanel component displays the toggle button on the right side of its caption, though a flexible way of customizing caption buttons is provided. Here are some of the scenarios that can be addressed:

  • changing the appearance of the toggle button;
  • specifying custom caption buttons near the toggle button;
  • moving the caption button(s) to the left side of a caption.

The basis for these customizations is the <o:captionArea> tag, which can be placed into the <o:foldingPanel> tag to customize the set of buttons displayed in the caption. This tag has an alignment attribute, which defines the caption side where the area should be placed. It can take two values: "right" (the default value), and "left".

Adding the <o:captionArea> tag removes the default toggle button and allows you to customize the set of buttons by placing components inside of this tag. It is possible to place the following components into caption area tags:

  • <o:expansionToggleButton/> tag – displays the FoldingPanel's expansion toggle and allows customizing its appearance.
  • <o:captionButton/> tag – displays a custom caption button that can be configured according to user's needs.
  • Any JSF component tags can also be placed into <o:captionArea>, which adds the flexibility of specifying virtually any controls in caption areas.

Both <o:expansionToggleButton/> and <o:captionButton/> components support the following common attributes:

Attribute(s) Description
style, styleClass Define the general style applied to the button.
rolloverStyle, rolloverClass Define the style that is applied to the button when mouse cursor moves over it. If toggleOnCaptionClick is "true" this style is applied to the button when cursor also moves over caption area.
onclick, ondblclick, onmousedown, onmouseover, onmouseup, onmouseout, onmousemove The standard mouse events.
hint Specifies text for the tool tip that appears when mouse hovers over the button

In addition they have the following attributes of their own. For <o:expansionToggleButton/>:

Attribute(s) Description
expandedImageUrl, expandedRolloverImageUrl, expandedPressedUrl Specify URLs for button's image when FoldingPanel is in expanded state: the general image, image that is shown when mouse hovers over the button, and image that is shown when mouse is pressed over the button but not released yet.
collapsedImageUrl, collapsedRolloverImageUrl, collapsedPressedUrl Specify URLs for button's image when FoldingPanel is in collapsed state: the general image, image that is shown when mouse hovers over the button, and image that is shown when mouse is pressed over the button but not released yet.

For <o:captionButton/> tag:

Attribute(s) Description
action Server action that should be executed when the button is pressed. Similar to the action attribute of the standard <h:commandButton> component.
render Specifies which component(s) should be reloaded with Ajax when the button is clicked. If the action attribute is also specified, then the action is also executed in the Ajax request instead of form submission. This attribute is similar to the render attribute of the
execute This attribute is effective only when the render attribute is specified. The execute attribute allows specifying the set of components whose data should be submitted for processing to the server during the Ajax request. This attribute is similar to the render attribute of the <o:commandButton> tag (see the CommandButton documentation for details).
imageUrl, rolloverImageUrl, pressedUrl Specify URLs for button's image: the general image, image that is shown when mouse hovers over the button, and image that is shown when mouse is pressed over the button but not released yet.

Here's an example of moving the customized expansion toggle button to the left caption side and placing an additional caption button besides:

<o:foldingPanel caption="Caption">
  <o:captionArea alignment="left">
    <o:expansionToggleButton
        collapsedImageUrl="/custom_collapsed.png"
        collapsedPressedImageUrl="/custom_collapsed_pressed.png"
        collapsedRolloverImageUrl="/custom_collapsed_rollover.png"
        expandedImageUrl="/custom_expanded.png"
        expandedPressedImageUrl="/custom_expanded_pressed.png"
        expandedRolloverImageUrl="/custom_expanded_rollover.png"
        hint="Click here to fold/unfold the panel">
    />
    <o:captionButton action="#{BackingBean.customAction}" imageUrl="customAction.gif"/>
  </o:captionArea>
  ...
</o:foldingPanel>

You can also place more than one <o:captionArea> tags, which allows specifying custom areas on both caption sides.

Using Dynamic Loading

It is possible to control how the FoldingPanel component loads its child components from the server when it needs to be expanded. If the FoldingPanel component is loaded in the expanded state for the first time, it can be collapsed and expanded again on the client side without making any requests to the server. However, if it is initially loaded in the collapsed state, then a request to the server occurs when the user expands the FoldingPanel component. The loadingMode attribute specifies the way that FoldingPanel's content is loaded in this case. This attribute can take the following values:

  • "client" - makes FoldingPanel's content to be preloaded when the page is loaded so that expanding the FoldingPanel shows the preloaded content without additional server requests.
  • "ajaxLazy" (default) - loads the embedded content from the server with Ajax request. Once loaded, it will be cached on the client and shown without additional server requests on further expansions.
  • "ajaxAlways" - loads the embedded content from the server with Ajax request. Unlike the "ajaxLazy" mode, this mode doesn't cache the loaded content and reloads the content each time the FoldingPanel is expanded.
  • "server" - the FoldingPanel component submits the page to re-render itself in the expanded state.

Customizing Styles

You can customize a style for the entire FoldingPanel component, its caption and/or container by using the following attributes:

Part of component Attributes
Entire component style/styleClass
Caption captionStyle/captionClass, rolloverTogglableCaptionStyle/rolloverTogglableCaptionClass
Container contentStyle/contentClass

To set an explicit height to the FoldingPanel component, split it into two parts and set the one part to the captionStyle attribute and the other to the contentStyle attribute or declare these parts in the captionClass and contentClass classes. Setting the height to the FoldingPanel's style or styleClass attributes may have an unpleasant effect. The same rule is true for the width when the FoldingPanel component has the "left" or "right" folding direction. In this case, set the width only for the contentStyle or contentClass attributes.

To set the text-align property for the caption of the FoldingPanel component, you should specify it in the captionStyle attribute. If you specify it in the style attribute, it will affect only the container. But if the container consists of another HTML <table> element, you should set text alignment in the contentStyle attribute instead. Text alignment will not work properly if it is declared in classes (styleClass, captionClass, contentClass).

If toggleOnCaptionClick attribute is set to "true", then rolloverTogglableCaptionClass and rolloverTogglableCaptionStyle attributes are applied to caption when mouse cursor moves over it.

Keyboard Support

The expansion state of the FoldingPanel component can be controlled with keyboard when it has a keyboard focus with the +/- keys (to expand and collapse the FoldingPanel respectively), and the spacebar key (to toggle the expansion state). The FoldingPanel can be made non-focusable and thus not having keyboard control by assigning false to its focusable attribute. Note that disabling focusability affects only the FoldingPanel itself, but not its children, which retain their usual keyboard support in any case.

The FoldingPanel has the following attributes that allow customizing its look in the focused state:

Attribute Description
focusedStyle/focusedClass A style for the entire FoldingPanel in the focused state.
focusedCaptionStyle/focusedCaptionClass A style for the FoldingPanel's caption in the focused state.
focusedContentStyle/focusedContentClass A style for the FoldingPanel's content area in the focused state.

Specifying User Events

The FoldingPanel component supports the following standard client-side events: onclick, ondblclick, onmousedown, onmouseover, onmouseup, onmouseout, onmousemove, onfocus, onblur, onkeydown, onkeyup, onkeypress. In addition, the FoldingPanel provides one component-specific event called onstatechange. This event occurs when the FoldingPanel's state is changed, i.e. when it is collapsed or expanded by the user.

Client-Side API

All client-side API methods are listed in the following table:

Method Description
expand() Expands the FoldingPanel component on which this method is invoked.
collapse() Collapses the FoldingPanel component on which this method is invoked.
isExpanded() Returns true if the FoldingPanel is expanded.
setExpanded(expanded) Sets expansion state of the FoldingPanel according to the boolean expanded parameter.
focus() Gives the keyboard focus to the component on which this method is invoked.
blur() Removes the keyboard focus from the component on which this method is invoked.
Clone this wiki locally