⁠11.6. <rich:togglePanel>

The <rich:togglePanel> component is used as a base for the other switchable components, the <rich:accordion> component and the <rich:tabPanel> component. It provides an abstract switchable component without any associated markup. As such, the <rich:togglePanel> component could be customized to provide a switchable component when neither an accordion component or a tab panel component is appropriate.
The <rich:togglePanel> component acts as a wrapper for multiple <rich:togglePanelItem> components. Each child component is displayed after being activated with the <rich:toggleControl> behavior.
Refer to Section 11.6.7, “<rich:toggleControl>” and Section 11.6, “<rich:togglePanel>” for details on how to use the components together.

⁠11.6.1. Basic usage

The initial state of the component can be configured using the activeItem attribute, which points to a child component to display. Alternatively, if no activeItem attribute is defined, the initial state will be blank until the user activates a panel component with a connected <rich:toggleControl> behavior.
The child components are shown in the order in which they are defined in the view, as shown in Example 11.4, “Basic usage”.

Note

All <rich:tabPanel> components should be wrapped in a form element when using either ajax or server mode, as usual for submitting components.
⁠

Example 11.4. Basic usage

​<rich:togglePanel id="layout" activeItem="item1">
​   <rich:togglePanelItem name="item1">
​      <!--content-->
​   </rich:togglePanelItem>
​   <rich:togglePanelItem name="item2">
​      <!--content-->
​   </rich:togglePanelItem>
​</rich:togglePanel>
​<h:commandButton>
​   <rich:toggleControl targetPanel="layout"/> <!--cycles through the states-->
​</h:commandButton>

⁠11.6.2. Dynamic panel item generation

All the switchable components (<rich:togglePanel>, <rich:accordion> component and the <rich:tabPanel>) can leverage the <a4j:repeat> tag to dynamically create child components. This can be useful when the definition of the panel items is determined at run-time from a backing bean list.

⁠11.6.3. Toggling between components

The switching mode for performing submissions is determined by the switchType attribute, which can have one of the following three values:
server
The default setting. Activation of a child component causes the parent <rich:togglePanel> component to perform a common submission, completely refreshing the page. Only one child at a time is rendered to the client side.
ajax
Activation of a child component causes the parent <rich:togglePanel> component to perform an Ajax form submission, and the content of the panel is refreshed. Only one child at a time is rendered to the client side.
client
Activation of a child component causes the parent <rich:togglePanel> component to update on the client side. All the items are rendered to the client side during the initial page render. JavaScript changes the styles such that one child component becomes hidden while the other is shown.

⁠11.6.4. JavaScript API

The <rich:togglePanel> component can be controlled through the JavaScript API. The JavaScript API provides the following functions, which are common to all switchable panels:
getItems()
Return an array of the items contained in the toggle panel.
getItemsNames()
Return an array of the names of the items contained in the toggle panel.
switchToItem(itemName)
Switch to and display the item identified by the itemName string passed as a parameter.
firstItem(), prevItem(), nextItem(), lastItem()
Get the name of the first item, the previous item, the next item, or the last item.

⁠11.6.5. Reference data

  • component-type: org.richfaces.TogglePanel
  • component-class: org.richfaces.component.UITogglePanel
  • component-family: org.richfaces.TogglePanel
  • renderer-type: org.richfaces.TogglePanelRenderer
  • handler-class: org.richfaces.view.facelets.html.TogglePanelTagHandler

⁠11.6.6. <rich:itemChangeListener>

Use the <rich:itemChangeListener> tag to register an ItemChangeListener class on a parent panel component. The class provided as a listener must implement the org.richfaces.event.ItemChangeListener interface. The processItemChange method accepts an org.richface.event.ItemChangeEvent event as a parameter.
The <rich:itemChangeListener> tag can be used with any of the switchable panel components:

⁠11.6.7. <rich:toggleControl>

The <rich:toggleControl> behavior can be attached to any interface component, whether inside or outside the controlled panel itself. It works with a <rich:togglePanel> component to switch between different <rich:togglePanelItem> components. Refer to Section 11.6, “<rich:togglePanel>” and Section 11.6.8, “<rich:togglePanelItem>” for details on how to use the components together.
The <rich:toggleControl> implements the JSF BehaviorHolder component, which provides events to attached components and behaviors.

⁠11.6.7.1. Basic usage

If the <rich:toggleControl> component is positioned inside a <rich:togglePanel> component, no panel attachment attributes need to be defined, as the control is assumed to switch through the <rich:togglePanelItem> components of its parent <rich:togglePanel> component.
A <rich:toggleControl> component can be located outside the <rich:togglePanel> component it needs to switch. Where this is the case, the <rich:togglePanel> is identified using the targetPanel attribute.

⁠11.6.7.2. Specifying the next state

The <rich:toggleControl> component can switch the attached <rich:togglePanel> component in multiple ways:
  • By default, the <rich:toggleControl> component will cycle through <rich:togglePanelItem> components in the order they are defined within the view.
    ⁠

    Example 11.5. Default switching

    ​<rich:togglePanel id="layout">
​   <rich:togglePanelItem>
​      <!--content-->
​   </rich:togglePanelItem>
​   <rich:togglePanelItem>
​      <!--content-->
​   <rich:togglePanelItem>
​</rich:togglePanel>
​<h:commandButton>
​   <rich:toggleControl targetPanel="layout"/> <!--cycles through the states-->
​</h:commandButton>
  • The next item to switch to can be explicitly defined by including a <rich:toggleControl> component within a <rich:togglePanelItem> component. Point the targetItem to the <rich:togglePanelItem> to switch to when the state is next changed.
    ⁠

    Example 11.6. Explicit switching

    ​<rich:togglePanel activeItem="item1">
​   <rich:togglePanelItem id="item1">
​      <!--content-->
​      <h:commandButton>
​         <rich:toggleControl targetItem="item2"> <!--switches to item2 -->
​      </h:commandButton>
​   </rich:togglePanelItem>
​   <rich:togglePanelItem id="item2">
​      <!--content-->
​      <h:commandButton>
​         <rich:toggleControl targetItem="item1"> <!--switches to item1 -->
​      </h:commandButton>
​   <rich:togglePanelItem>
​</rich:togglePanel>
  • Alternatively, use the targetItem attribute with keywords to switch items. The @first, @prev, @next, and @last keywords switch to the first item, the previous item, the next item, and the last item respectively.
    ⁠

    Example 11.7. Keyword-based switching

    ​<rich:togglePanel activeItem="item1">
​   <rich:togglePanelItem id="item1">
​      <!--content-->
​      <h:commandButton>
​         <rich:toggleControl targetItem="@next"> <!--switches to next item (item2)-->
​      </h:commandButton>
​   </rich:togglePanelItem>
​   <rich:togglePanelItem id="item2">
​      <!--content-->
​      <h:commandButton>
​         <rich:toggleControl targetItem="@prev"> <!--switches to previous item (item1)-->
​      </h:commandButton>
​   <rich:togglePanelItem>
​</rich:togglePanel>

⁠11.6.7.3. Reference data

  • client-behavior-renderer-type: org.richfaces.component.behavior.ToggleControl
  • behavior-id: org.richfaces.component.behavior.ToggleControl
  • handler-class: org.richfaces.view.facelets.html.CustomBehaviorHandler
  • behavior-class: org.richfaces.component.behavior.ToggleControl
  • client-behavior-renderer-class: org.richfaces.renderkit.html.ToggleControlRenderer

⁠11.6.8. <rich:togglePanelItem>

The <rich:togglePanelItem> component is a switchable panel for use with the <rich:togglePanel> component. Use the <rich:togglePanelItem> component to define the content for a panel using nested components. Switching between <rich:togglePanelItem> components is handled by the <rich:toggleControl> behavior.

⁠11.6.8.1. Reference data

  • component-type: org.richfaces.TogglePanelItem
  • component-class: org.richfaces.component.UITogglePanelItem
  • component-family: org.richfaces.TogglePanelItem
  • renderer-type: org.richfaces.TogglePanelItemRenderer