RichFaces 4.x switchable panels

Common part

http://anonsvn.jboss.org/repos/richfaces/root/ui-sandbox/panels/trunk/docs/taglib-toggle 1.2 - UML diagram for all switchable panels. All the components attributes was revised and unified for switchable panels.

https://jira.jboss.org/browse/RF-7945 - jira for markups.

http://anonsvn.jboss.org/repos/richfaces/management/design-4x/ - placement for markups in SVN.

 

tabPanel component [forum thread]

Overview

 

RichFaces switchable panels set is provided in order to organize some categorized content on the page and allow to switch between parts in different modes. The set includes:

  • TabPanel component
  • ToggleLayout component
  • Accordion

 

NOTE: collapsiblePanel (former simpleTogglePanel) will be described separatelly and not all rules from that document should not be applied to that component.

 

In common part I will use pseudocode with switchable and switchablePanel components which should be changed with for example Tab and TabPanel or Accordion and Accordion Panel for specific components. Exception - togglePanel uses three components for that:  switchablePanel mean togglePanel and toggleControl pair for that component.

Switching modes

All the panels should provide three switching modes defined with switchType attribute.

  • ajax(Default)
  • server
  • client

subpanels(controls) should be able to redefine general mode. E.g. whole tabPanel could be possible to define as switchable by Ajax and one specific tab - on client. So all the tabs will be loaded during switching and the specific tab will be always on the client and switching to it should be possible without ajax request.

 

Form requirements

The components which switches in ajax or server mode - should be enclosed into form.

 

TabPanel exclusion: If the component is not enclosed into form in server or ajax mode but the tabs has set of forms for every tab - the form encoded by default around the tab controls set in order to perform switching.

Accordion exclusion: if the component is not enclosed into form in server or ajax mode but the tabs has set of forms for every accordionItem - forms should be encoded by the component around the headers controls.

 

Selected panel

It should be possible to manage the currently selected panel in user actions. Two requirements should be applied to all the components:

 

  • all the children panels components should provide name attribute which could be defined with some String value unique within switchable panel children.
  • any switchable panel should provide selectedItem attribute which should store currently selected panel by it's name.

 

Ajax updates and Metacomponents

1) Update of the whole component should be available by it's id as usually.

2) Update of some child panel together with it's control should be available by child panel id as usually:

 

<switchable>
<switchablePanel id="p1">
...
<a4j:command render="p1"/>
...

 

3) Update of the controls list should be possible by using @controls metacomponent at parent component. All the switching controls (all the tabs or all the headers of accordion) updated using next code:

<switchable id="s">
<switchablePanel>
...
</switchablePanel>
<switchablePanel>
....
</switchablePanel>
...
<a4j:command render="s@controls"/>
...

4) Update of the concrete child panel switching control should be available by using @control metacomponent for child component. p1 control updated using next code:

<switchable id="s">
<switchablePanel id="p1">
...
</switchablePanel>
<switchablePanel>
....
</switchablePanel>
...
<a4j:command render="p1@control"/>
...

5) Update the content of specific child panel should be available by using @content metacomponent at child panel component. p1 panel content updated using next code:

<switchable id="s">
<switchablePanel id="p1">
...
</switchablePanel>
<switchablePanel>
....
</switchablePanel>
...
<a4j:command render="p1@content"/>
...

Conversion/Validation

Proposed to extend the component from UIoutput instead of UIInput in 4.x. Component will not have much unnesessary properties in that case. As it's just panel with some active content group(and not real input) - validator, immediate and some other properties looks unnesessary for it.

 

Server Side change Event

We propose to create new SelectedItemChangeEvent - common for al the switchable panels and provide selectedItemChangeListener attribute to all the panels in order to handle panel switch.

 

Future: need to provide separate listener tag in order to define set of listeners declarativelly.

 

Moving all the switching logic to Panels components(IMPORTANT)

Thats one of the biggest differences from 3.3.x implementation that we proposing after design. As you could see from UML diagram(link at the page top) - all the attributes of ajax request and standard immediate attribute - were moved to panels from children tags.

 

That's caused by the fact that according to curent proposal - panel should handle switching. And the controls - ony call the panel to change the selected pane via client API.

 

So as the panel actually manages switching type and creates requests in server or ajax modes - all the request attributes moved to the panel itself.

 

Note: action and actionListener - removed at all in this design - as the panel is actually not UICommand.

Note: immediate at panel defined as true - will cause selectedItemChange event to be processed at early phase(and not value applying itself as it was before when panels was UIInput)

 

Client Side Events

any switchable panel child should rise leave and enter events and the component should provide onleave and onenter attribute to handle them.

 

any switchable panel should provide itemchange and beforeitemchange event and provide onitemchange and onbeforeitemchange in order to handle them.

 

except those - there should be handlers to all standard mouse events as shown at diagram.

 

also ajax events handlers should be available at panels components.

Client Side API

All the panels should provide API to control state on the client. Instance of component should be get according to RF standard #{rich:component} definition.

 

Methods:

getSelectedItemName();

getAllItemsNames();

next();

previous();

first();

last();

switchToItem(name);

TabPanel

 

Overview

 

The components provides functionality of UI tabbed pane.

 

Tags Set

 

rich:tabPanel - panel container which supports set of rich:tabs defined as child components or/and iterated using a4j:repeat.

rich:tab - tab component. Tab layout defined with nested content.

layout

 

The component should provides various types of layouts which could be defined using headerPosition(to which side all the tabs should be bound) and headerAlignment (how them should be aligned relativelly to the side). headerPosition attribute shoud have next possible values: top(default), bottom, right, top. And headerAligment should has the same ones(left is default) + center value.

 

Facets

header facet should be available on tab. It could be used instead of label attribute in order to defined custom content in tab header. (if used together with attribute - both should be encoded)

 

Other Additions to 3.3.x - CONSIDER DURING MARKUPS REVIEW AND IMPL and plan to M1 or later

I believe all the points which will be listeed there - should be added after initial migration in M1:

  • posibility to display "scrollable" list of tabs if tabs count more that could be placed in tabs header according to size(e.g. similar to firefox tabs list).
    • scrolling tabs with just additional arrows controls at the opposite sides(also similar with browser analogous).
  • possiblity to have multiline tabs instead of scrollable line in the same case.

This both points should be configured by single attribute like

multipleTabsPresentationType="dropDown | scroll | multiline | stretch"

dropDown - menu to choose tab from hidden ones should be added, and visible ones shown in single line(width of tabPanel considered)

scroll - scroll controls used to reach invisible tabs(width of tabPanel considered)

stretch - tabPanel header stretched horizontally to show all the tabs into single line.

multiline - tabs shown all in multiple lines(width of tabPanel considered)

 

Features postponed from M3/M4

TogglePanel

 

Overview

Toggle components designed to allow the developer to implement abstract content grouping in some panels and design switching between them.

Toggle component set should provide way to implement such switchable layouts with any markup customer need. So opposite to two other component it's nothave any predefined layout.

 

Tags set:

rich:toggleLayout - wrapper component for all switchable panels (togglePanel)

rich:togglePanel - defines one of the panels in set within rich:toggleLayout

rich:toggleControl - behavior which manipulates with the rich:toggleLayout state.

 

rich:toggleLayout component

Component should support only some set of togglePanels defined inside or dynamicall adding of them by using a4j:repeat.

 

Component should be encoded as just div without any styling which encoses currently active panel or all the panels (with only one visible) in which defines client switchType.

TogglePanel

togglePanel defines one of the panels among the layout. It should be encoded as div with all the nested components markup.

Nothing selected (Proposal - to be approved additionally)

In 3.3.x for such implementation developers were need to define panel facet and nest empty panel group inside.

For 4.x I propose to allow null or empty string value in selectedItem of togglePanel to define that there are no active panels to be shown.

 

Switching between states

There should be two options for selected panel change.

  • switching to concrete state defined at activated toggleControl
  • cycled switching
Switching to specified state

It should be possible to switch the state by activation of some toggleControlBehavior which defines switchTo attribute defined with some togglePanel name

 

Cycled switching

As we not using facets by current proposal is to have set of togglePanel components defined inside toggleLayout - we not need ordering attribute anymore and could switch them just in order in which them defined.

 

Examples of usage:

<toggleLayout id="layout" selectedItem="short" selectedItemChangeListener="#{fooBean.switchListener}">

     <togglePanel name="short">

          //content

          <h:commandButton>

               <togglrControl targetItem="details"> // switches to details state

          </h:commandButton>

     </togglePanel>

     <togglePanel name="details">

          //content

          <h:commandButton>

               <toggleControl targetItem="short"> //switches to short state

          </h:commandButton>

     <togglePanel>

</toggleLayout>

<h:commandButton>

     <toggleControl for="layout"/> // the control just changes states cycling

</h:commandButton>

Accordion (aka panelBar)

 

Tags set:

 

rich:accordion - panel container which supports set of accordionItems defined inside or/and iterated via a4j:repeat.

rich:accordionItem - child panel which layout defined with nested content.

 

Layout

 

Remains the same as was for 3.x.x.

 

Switching

As it was defined in common section - starting from 4.x accordion should be provided with different switchType's. (only client in 3.3.x)

 

Client Effects (Post M1?)

accordion panels switching could be done with aplying "sliding" effect on the client.