BorderLayoutPanel 2.x
TOCSTART
TOCEND
The BorderLayoutPanel component is a container used to layout groups of components by container's edges. The separators between component groups can either be fixed to introduce a static layout, or can be made draggable and/or collapsible to make a dynamic layout.
- Static border layout
- Side panel resizing
- Side panel collapsing
- Side panel captions
- Nesting BorderLayoutPanels for complex layouts
The <o:borderLayoutPanel> tag can be used to add the BorderLayoutPanel component to a page. You can create a group of components aligned within a BorderLayoutPanel component using a SidePanel.
SidePanel is a container that can be placed inside of BorderLayoutPanel to layout one or more components near one of BorderLayoutPanel's edges. The user can change SidePanel's size by dragging its splitter if SidePanel is configured to be resizable (see the Resizing section below). A SidePanel is created by placing the <o:sidePanel> tag inside of the <o:borderLayoutPanel> tag and specifying its alignment attribute to specify the BorderLayoutPanel's edge where this panel should be placed. It is possible to place several SidePanels with the same alignment, which will result placing these components side by side in the specified alignment area (see SidePanel Placement Rules section below).
You can also add any content to the area in the center of BorderLayoutPanel that is not occupied by any SidePanels by adding child components right into the <o:borderLayputPanel> tag.
In the example below, the BorderLayoutPanel component is split into two parts by placing one SidePanel and specifying child components of BorderLayoutPanel component.
<o:borderLayoutPanel><o:sidePanel alignment="left" size="50%"> <h:outputText value="Left side content area"/> </o:sidePanel>
<h:outputText value="Right side content area"/>
</o:borderLayoutPanel>
You can specify the caption of SidePanel component using by using the caption attribute for text caption or "caption" facet for more complex caption content.
<o:sidePanel caption="SidePanel caption"><h:outputText value="SidePanel content">
</o:sidePanel>
The <o:sidePanel> tag has two special attributes: alignment and size.
The alignment attribute specifies an edge of BorderLayoutPanel to which this SidePanel
should be aligned. It can take one of the following values: "left", "right", "top" or "bottom".
By default, it is set to "left".
The size attribute specifies width of SidePanel when its alignment is
"left" or "right" or height when its alignment is "top" or "bottom". You can
specify size attribute in any CSS units including percent values. The SidePanel's size
can also be limited using minSize or maxSize attributes, which is useful for resizable panels (see the
Resizing section below). By default, size is set to "50%",
maxSize is set to "100%" and minSize is equal to zero.
Here's an example of using these attributes:
<o:borderLayoutPanel><o:sidePanel alignment="top" size="150px" minSize="300px" maxSize="50%"> ... </o:sidePanel>
</o:borderLayoutPanel>
Each SidePanel can optionally be configured to have resizing capability by dragging the panel's separator, and/or expanding/collapsing capability by clicking on the separator.
By default, resizing capability is turned on, so no additional actions are required if you intend to make a dynamic
layout. Though if you're creating a static layout, you can disable the resizing capability by setting the SidePanel's
resizable attribute to "false".
The expanding/collapsing capability is turned on by default as well. Though you can disable this feature by
specifying the SidePanel's collapsible attribute to "false".
Here's an example of how to create "collapsible only" and "fixed size" SidePanels:
<o:borderLayoutPanel><o:sidePanel resizable="false"> This is a collapsible, but non-resizable SidePanel </o:sidePanel>
<o:sidePanel resizable="false" collapsible="false"> This is a fixed size SidePanel </o:sidePanel> </o:borderLayoutPanel>
The BorderLayoutPanel is a container for SidePanel components, and here are the SidePanel placement rules:
- Any BorderLayoutPanel can contain any number of SidePanels.
- "top" and "bottom" aligned SidePanel components have a priority over the "left" and "right" aligned ones, so they occupy 100% of BorderLayoutPanel inner width, whereas "left" or "right" aligned SidePanel components will occupy BorderLayoutPanel's space that remained after placing the top and bottom-aligned areas.
- In a case when several SidePanel components with the same alignment were placed into the same BorderLayoutPanel the SidePanel that are declared earlier in the list of BorderLayoutPanel children will be placed closer to the appropriate edge of the BorderLayoutPanel component.
The BorderLayoutPanel component provides an ability to create quite common kind of layouts where components are aligned by container's edges, though in some cases this basic layout is not enough. An example is a typical layout of desktop mail reading applications, where a screen is separated onto three parts: the left area contains the list of mail folders, and the right area is vertically separated onto two areas, where the the top one lists e-mails in the current folder, and the bottom one displays the selected e-mail. These use cases can be addressed using the feature of nested BorderLayoutPanel components.
Here's an example demonstrating the E-mail reader layout described above:
<o:borderLayoutPanel><o:sidePanel id="folderList" alignment="left" size="35%"> ... </o:sidePanel>
<o:borderLayoutPanel> <o:sidePanel id="emilList" alignment="top"> ... </o:sidePanel>
<f:panelGroup id=<span class="code-quote">"emailPreview"</span>> ... </f:panelGroup></o:borderLayoutPanel>
</o:borderLayoutPanel>
This way you can place <o:borderLayoutPanel> tags inside of SidePanes to make an arbitrary hierarchy of BorderLayoutPanel components.
You can customize a style for any element of SidePanel or BorderLayoutPanel using the following attributes:
| BorderLayoutPanel attributes | Description |
|---|---|
| style and styleClass | A style used for theentire BorderLayoutPanel. |
| rolloverStyle and rolloverClass | A style used for the entire BorderLayoutPanel in the rollover state. |
| contentStyle and contentClass | A style used for a content area – an area not occupied by the SidePanels. |
| SidePanel Attributes | Description |
|---|---|
| style and styleClass | A style used for the SidePanel. |
| rolloverStyle and rolloverClass | A style used for a SidePanel in a rollover state. |
| splitterStyle and splitterClass | A style used for a SidePanel's splitter. |
| splitterRolloverStyle and splitterRolloverClass | A style used for a splitter in a rollover state. |
| captionStyle and captionClass | A style used for the SidePanel's caption area. |
| contentStyle and contentClass | A style used for the SidePanel's content area. |
The both of SidePanel and BorderLayoutPanel components support the following standard client-side events: onclick, ondblclick, onmousedown, onmouseover, onmouseup, onmouseout, onmousemove, onkeydown, onkeyup, onkeypress. In additional it provides follow component-specific events:
| BorderLayoutPanel Event | Discription |
|---|---|
| oncontentresize | Occurs when the BorderLayoutPanel's content size is changed, i.e. when entire BorderLayoutPanel or one of its SidePanels is resized. |
| SidePanel Event | Discription |
|---|---|
| onresize | Occurs when the SidePanel's splitter is dragging by user. |
| oncollapse | Occurs when the SidePanel is collapsed. |
| onrestore | Occurs when the SidePanel is restored from a collapsed state. |