FoldingPanel


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 allowing the user to switch between the states.

Key Features

Defining the Content

To add the FoldingPanel component to a page, use the <q: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 the "caption" facet.

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

<q:foldingPanel>
  <f:facet name="caption">
    <h:outputText value="Panel for color selection"/>
  </f:facet>
  <h:outputText value="Select color:"/>
  <q:dropDownField>
    <q:dropDownItems value="#{ColorBean.items}"/>
  </q:dropDownField>
</q:foldingPanel>

Customizing the Appearance

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.

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.

You can specify the placement of the toggle button relative to the caption by using the buttonPlacement attribute. It can take a value of "left" or "right", which places the button to the left or to the right of the caption, respectively. By default, the buttonPlacement attribute is set to "right".

The appearance of the toggle button can be customized using the following attributes:

Attribute Description
collapsedImageUrl Image that is shown as a button, when the FoldingPanel component is expanded.
collapsedPressedImageUrl Image that is shown as a button in the pressed state, when the FoldingPanel component is expanded.
collapsedRolloverImageUrl Image that is shown as a button in the rollover state, when the FoldingPanel component is expanded.
expandedImageUrl Image that is shown as a button, when the FoldingPanel component is collapsed.
expandedPressedImageUrl Image that is shown as a button in the pressed state, when the FoldingPanel component is collapsed.
expandedRolloverImageUrl Image that is shown as a button in the rollover state, when the FoldingPanel component is collapsed.

To specify text for the tool tip that appears when the user places the mouse pointer over the button, use the buttonHint attribute.

The following example shows the use of the attributes described above.

<q:foldingPanel
        expanded="false"
        buttonPlacement="left"
        foldingDirection="up"
        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"
        buttonHint="Click here to fold/unfold the panel">
  <f:facet name="caption">
    <f:verbatim>Panel for color selection</f:verbatim>
  </f:facet>
  <h:outputText value="Select color:"/>
  <q:dropDownField>
    <q:dropDownItems value="#{ColorBean.items}"/>
  </q:dropDownField>
</q:foldingPanel>

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 comnponent. Depending on the value of the loadingMode attribute, the FoldingPanel component either submits the page to re-render itself in the expanded state (loadingMode="server") or transparently retrieves the embedded content from the server (loadingMode="ajax") or renders all content on first loading regardless of the FoldingPanel's 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 and styleClass
Caption captionStyle and captionClass
Container contentStyle and 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).

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.

QuipuKit