Skip to content

WPanel

Jump to bottom
Mark Reeves edited this page Mar 21, 2018 · 17 revisions

Type.WPanel is a layout and container component. It has options which determine the HTML output element, the appearance of the container and its content load behaviour.

Why use WPanel

WPanel is a generic container component which has a UI artefact (unlike WContainer). It may be used to hold parts of a UI for the purposes of layout, as an ajax target or as a target for a WSubordinateControl.

There are some common in-built styles attached to certain WPanel Type settings and some Types are reserved for specific use within a UI. Type.HEADER and Type.FOOTER are both extremely specific, though Type.HEADER has been mis-used and mis-styled for historical reasons and there is an argument to swap the implementations of Type.HEADER and Type.BANNER so that Type.HEADER becomes a generic HTML header element and Type.BANNER is reserved for page-level banner headers.

When not to use

It is not necessary to use a WPanel to wrap general content or as a wrapper for targeting by a WAjaxControl or WSubordinateControl as many other components are already target for these. One does not need, necessarily, to use a WPanel as layout or container if one is using WFieldLayout, WColumn (in WRow), WCollapsible, WFigure, WTable or WTemplate for example. Though it is recognised that WPanel may provide a useful component within these. It is almost never necessary to wrap any of these other layout components in a WPanel for layout or target purposes.

More of an issue is the use of WPanel Layouts. These abstract layouts work for the types of scenarios for which WComponents was originally built but suffer from being too abstract to be efficient. They, for example, show excess HTML element depth and even simple things like creating CSS selectors for in-application styling overrides may be difficult.

One common use of WPanel from past use which is completely superfluous is the use of a WPanel as a generic component wrapper. This results in deeply nested div elements and UIs which are tricky to debug and are rather inefficient. This is exacerbated if each panel has a Layout and each Layout contains exactly one more component - itself wrapped in another WPanel. Yes, we see this rather a lot - I blame Java AWT!

Creating WPanel

WPanel has two reasonably simple constructors. The default constructor create a WPanel of Type.PLAIN. The other constructor takes a Type argument. The Type is not final so may be changed within the user context, though why this would be necessary is difficult to justify.

// a WPanel Type.PLAIN
WPanel plainPanel = new WPanel();
// a WPanel Type.BOX
WPanel boxPanel = new WPanel(Type.BOX);

Accessibility

WPanel is a generic layout component therefore has few accessibility concerns. If a WPanel is of Type.ACTION or Type.CHROME, however, it must have an appropriate value set for its title.

Appearance

WPanel creates a block of content. It will always fill its available width. Other than this the appearance is determined by the theme in use, though some appearance hints appear in the JavaDoc for each Type and these hints should be honoured in the theme.

In the default theme the panel appearance is purposely plain to allow for easy extension with a minimum of CSS overrides.

The appearance of decorated Types such as Type.HEADER, is a primary differentiator of applications from different themes. The theme appearance is all determined in CSS through the theme Sass source and is adjustable at theme build time and within an application using any theme. This section is concerned only with theme build-time options. For information about extending the appearance in a theme see Creating a theme and for application level changes see Adding custom CSS. In both cases the Theme class name conventions may prove useful.

Sass

The core CSS for WPanel is in src/main/sass/components/_wpanel.scss and there is not much of it. The structural styles for the various layouts is found in src/main/sass/components/_layout.scss and should not usually need to be changed. There are a few constructs which straddle structure and style and these may be modified using Sass variables as shown below.

Sass var Purpose default
$wc-panel-feature-padding Padding of Types FEATURE and BOX $wc-gap-normal
$wc-column-list supported column widths supported 16,33,34,66,67,83
$wc-column-widths-include-fives add multiples of 5 to the list of supported column widths true
$wc-list-layout-dot-spacing space between items in a flat dotted list 1.5rem
$wc-list-layout-ordered-spacing space between marker and items in a flat numbered list 2rem
$wc-list-layout-bar-width-offset space to allow for marker in a vertical bar separated list 1rem

Type

The Type property determines how the container will appear and it is used to determine the HTML element output into the web page. It is the single most important property for determining the appearance of a section of content contained in a WPanel. The Type is set in the WPanel constructor (even in the default constructor) but may be amended.

// create a PLAIN WPanel
WPanel contentPanel = new WPanel();

// ...

// but at some point we need to
// make the content stand out from the crowd:
contentPanel.setType(Type.FEATURE);

Type.ACTION

This Type is deprecated in favour of WSection.

An action panel is similar to Type.CHROME but with a different appearance. It is intended to be used once per screen to highlight the main area of activity.

For more information see WPanel Type ACTION.

Type.BANNER

This Type is not currently implemented in the default WComponents theme.

Type.BLOCK

This Type is deprecated in favour of Type.PLAIN and Margin.

A 'block' type panel has padding around the edges.

The padding is fixed and is determined by the theme in line with any available design standards. The 'border' in the illustration below is a WHorizontalRule the same width as the WPanel to demonstrate the padding.

WPanel type BLOCK

Since this Type has been deprecated it is no longer implemented in the default theme but the Sass source file includes commentary on how a theme may choose to implement it.

Type.BOX

A box panel has a border.

A box panel has a border and an internal pad to keep the content off of the border. The border style is determined by the theme in line with any available design standards.

WPanel type BOX

Type.CHROME

This Type is deprecated in favour of WSection.

A panel with a title displayed in a border.

For more information see WPanel Type CHROME.

Type.FEATURE

The feature panel is highlighted by a background colour and border.

Internal padding is used to move the content off of the border.

WPanel type FEATER

Type.FOOTER

The footer panel is only intended for use at the very bottom of an application.

Type.FOOTER outputs a footer element.

WPanel type FOOTER

The default theme applies no specific style to this Type.

Type.HEADER

The header panel is only intended for use at the very top of an application.

Type.HEADER outputs a header element with a role of "banner" and is only intended for use at the very top of an application.

WPanel type HEADER

Type.PLAIN

A plain panel.

The panel is a block container with no specified UI impact. In effect this is a plain div element. This is the default type if no Type is specified.

Layouts

WPanel has a number of options for content layout. These options make WPanel a fundamental layout component along with WRow, WColumn and WFieldLayout.

The available layout are:

  • ColumnLayout which splits the content into a predetermined set of columns. The content added to the panel is then allocated one component to each column. When the number of components added to the panel exceeds the number of columns a new row is created containing the same number of columns. Each column may be set to a specific size and alignment.
  • FlowLayout which allows for horizontal and vertical flows of components with optional gaps between each added component.
  • BorderLayout which allocates content to specific regions of the panel.
  • GridLayout which makes an n × m grid of components where each cell in the grid has the same width and each cell in any rows of the grid will be equal in height to all other cells in that row. The width of the cells is determined by the number of columns in the grid.
  • ListLayout which makes a list element (OL or UL) and makes each added component into a list item. The lists are able to be styled to appear vertical or horizontal and the item separators are able to be adjusted.

The WPanel may also contain simple content in which case all components added to the panel are arranged according to their theme determined or native HTML layout.

Title

The title property sets a text title for a WPanel. Whilst it is available on any WPanel it is only output on those WPanels which are indicated as having a visible title in the JavaDoc comments of the Type - i.e. Type.ACTION and Type.CHROME.

In effect it is only used if the WPanel.Type is CHROME or ACTION, and in these cases the title is mandatory as it forms the content of the section header as a h1 element. If the WPanel.Type is CHROME or ACTION and the WPanel does not have a title (or its title os set to an empty or whitespace-only string) then it will have a placeholder for the title. You will not want this placeholder. It is an accessibility failure to have a WPanel of Type.CHROME or Type.ACTION without a title.

WPanel mainPanel = new WPanel(WPanel.Type.CHROME);
mainPanel.setTitle("My application content");

Margins

WPanel is a marginable component.

Responsive design

The in-built responsive design for WPanels is concerned with adjusting in-built spacing such as the padding of [Type.BOX] and [Type.FEATURE] for better use of narrow screens. There are some opt-in responsive design features and some which are inbuilt without a need for opt-in by the applications using the theme. Note that these feature will only be available if the theme in use is built with support for the in-built responsive design. For more information see Responsive Design.

HTML output

All WPanels output a single block element. This element may then contain other elements depending upon the layout of the WPanel and/or the Type].

Determining the top level HTML element

WPanel must not be placed in any container WComponent which may only contain phrasing content.

Hiding

A WPanel may be hidden on page load. This property is determined by a WSubordinateControl. If a WPanel has an AJAX Mode of LAZY then its content will be fetched only if it is made visible.

Default button

A WPanel may have a default submit button which applies to all submittin input controls (such as text inputs) within that WPanel. This default submit WButton can be overridden by a nested WPanel or by any individual WComponent which also has a defaultSubmitButton set. This is discussed in more detail in Implicit form submission.

It is recommended that a default submit button be added to the outermost WPanel which contains all form control components in an application. If the application has no default submit WButton then the first WButton or submitting WMenuItem in source order will be triggered if the user presses the ENTER key in a text input field. This will rarely be the expected control.

// Given WPanel `panel` and WButton `button`
panel.setDefaultSubmitButton(button);

Content mode

The mode is used to set the AJAX content loading mode for the WPanel. For information about performance optimisation using modes see Ajax modes. The modes which are available to WPanel are:

  • Mode.LAZY

    In LAZY mode the content of the WPanel is requested from the server when the panel is made visible in the client. If the panel is visible on page load the content will form part of the original page and no AJAX request will be made.

  • Mode.EAGER

    In EAGER mode the content of the WPanel is requested as soon as the page loads and is added to the panel as soon as it is available. This will occur whether or not the panel is visible in the client UI.

// with WPanel `sometimesContentPanel`
// which is hidden by a WSubordinateControl when not needed
sometimesContentPanel.setMode(WPanel.PanelMode.LAZY);

Naming context

WPanel may be used to create a naming context rather than using a separate WNamingContext.

Alternatives to WPanel

Related components

Further information

Some start pages

Clone this wiki locally