WComponents without UI artefacts

tl;dr

The list of WComponents below: don't add them by themselves or stuff could look weird.

Contents

• tl;dr
• Contents
• What it is all about
• List of WComponents
• Rendering problems
  • Empty containers
    • How to add these components
    • Special condition for BorderLayout
  • Empty content
    • Avoiding this issue
  • "Empty" repeated controls
    • Avoiding empty repeated controls
• Hint: use WContainer
• Special conditions for WLabel
• Hidden components
• Difference between imperceptible and no in-situ artefact
• Further information

What it is all about

Some WComponents do not output an in-situ UI artefact in the rendered screen. This is different from components which may not be "visible" or "palpable" in a given view and does not include WComponents which are not output by the renderer (by using setVisible(false)).

A component which has no in-situ artefact is never specifically rendered to a perceptible HTML element in the place in which it is added to the component tree. This is usually because the element is transformed to JavaScript. These components can cause unusual, unexpected or unwanted UI rendering under some circumstances.

These components must be added to the component tree to have any effect. Care must be taken in determining where they are added.

List of WComponents

These components do not have any in-situ UI artefacts:

• RadioButtonGroup;
• WAjaxControl;
• WContent;
• WDialog;
• WLabel which is hidden (see below);
• WMessages when no messages are available for display;
• WPopup;
• WSubordinateControl;
• a WLabel for a WCheckBox, WRadioButton, any WComponent which outputs a complex form control or a WSelectToggle in CONTROL mode (see below for more details);
• WContainer containing any combination of one or more of these components without containing any other UI component which is not in this list.

In addition any WComponent in a hidden state (though see below) will seem to not have an in-situ UI artefact whilst it is hidden, this differs from not having any in-situ UI artefact in that a gap in the UI caused by the artefact being hidden may be filled if the component is made visible.

Rendering problems

Empty containers

None of the listed components (or any number in any combination) should never be added directly to:

• a WPanel with any layout:
  • WPanel BorderLayout;
  • WPanel ColumnLayout;
  • WPanel FlowLayout;
  • WPanel GridLayout;
  • WPanel ListLayout;
• a WDecoratedLabel, as part of the constructor or as the sole content of any of its segment sub-components;
• a data component of a WDefinitionList.

The reason for this is that the no-UI-component will reserve a cell for itself in each of these layouts or a segment of WDecoratedLabel. Therefore the rendered layout will have an empty wrapper where that component was added. In the case of a WPanel FlowLayout this may not have any visible impact (unless gap, hgap or vgap is applied). For the other layouts the present but empty wrapper element will cause an obvious change in the UI: for WPanel ColumnLayout or WPanel GridLayout for example there will be an empty grid cell (row-column intersection) for each of these components added to the layout.

Note that this issue does not arise if adding such a component to a WPanel which has not had a layout set on it nor to a named region of WPanel BorderLayout (for example BorderLayout.NORTH) if another WComponent which does have an in-situ UI artefact is also added to the same named region.

How to add these components

WContainer is transparent in the UI so it will appear to the client rendering that the two (or more) components are both in the same wrapper and there will not be any empty wrappers.

If your non-UI-component requires that any of these components be added to a layout (or part of WDecoratedLabel) which would be affected as described above and that container has other content then the non-UI-component and any other WComponent which is not also one of these components can both be added to a WContainer and that WContainer added to the tree in the position of the perceptible WComponent.

Special condition for BorderLayout

WPanel BorderLayout has up to five named regions (for example BorderLayout.NORTH). Any of these components may be added directly to any one of these named regions if and only if at least one WComponent with a perceptible, in-situ UI artefact is also added to that same named region.

Empty content

None of the listed components (or any number in any combination) should be the sole content of a WDialog or any WComponent with a UI artefact including:

• WCollapsible;
• WDecoratedLabel
• WLabel;
• WList;
• WPanel with no layout;
• WSection; or
• WTab.

In these cases a UI artefact will be created for the wrapping component but it will have no content which makes them a bit pointless and may cause an accessibility error if the containing element is expected to have palpable content. A WLabel, for example, must have palpable content, therefore a WLabel containing only one or more of these components will cause an accessibility failure.

In the case of WPanel with no layout this would only result in no visible UI issue if the WPanel is also of WPanel.Type.PLAIN and has no Margin. Any other WPanel.Type will create a visible ui artefact (even WPanel.Type.BLOCK creates a padded box which will effect the spacing above and below it) and a WPanel with a Margin may cause unexpected spacing on any side to which the Margin is applied.

In the case of the content of a WDialog the opened dialog would have no content - again it seems a bit pointless. We do not allow nested dialogs for reasons of usability and accessibility therefore one should never add a WDialog to the content of a WDialog even if that containing WDialog also has other palpable content.

Avoiding this issue

One can add multiple WComponents to the content of these container components, therefore the components with no UI artefact can be added alongside other WComponents. In the case of the content of WCollapsible and WTab which requires a WComponent at instantiation the WComponent should almost always be a WContainer.

"Empty" repeated controls

None of the listed components (or any number in any combination) should be the repeated component in a WList, WRepeater or WTableColumn. The repeated component will generate a row/wrapper for each iteration of the repeater. This would, for example, result in a completely empty table column.

Avoiding empty repeated controls

Just don't do it! Really: what is the expected outcome?

Hint: use WContainer

The implication of the above is that any of these components may always be added to a WContainer along with any other WComponent with a perceptible, in-situ UI artefact with no ill-effects on the rendered view. Given this safety valve it should be a rule of thumb that any of these components should be added to a WContainer with something else and the WContainer added to the tree where the "something else" should go.

Special conditions for WLabel

When a WLabel is in a hidden state its UI artefact is taken out of flow and moved out of the viewport. So long as the label has palpable content it is considered perceptible but it does not necessarily appear to have an in-situ UI artefact.

In the case of the label segment of WField this is all taken care of by the theme. If a WLabel in a hidden state is added anywhere else it will have the same effect as if it did not generate a UI artefact. This includes generating what appear to be empty wrappers as in the cases described above.

When a WLabel is for a labellable component and that labellable component is in a hidden state then the Wlabel will also be in a hidden state (not merely moved out of view). Note that if the labellable component is shown (using a WSubordinateControl action) then the WLabel will also be shown. If the WLabel is independently hidden (using WLabel.setHidden(true)) then even when it is made palpable as the labellable component is shown it will be out of viewport and may still result in the sort of rendering issues discussed on this page.

There are conditions under which WLabel may leave an empty Layout cell.

• If the WLabel is for a WCheckBox, WRadioButton or WSelectToggle in CONTROL mode then the WLabel will be output immediately following the labelled WComponent. If the WLabel was placed anywhere else in the UI then there may be an empty container left where the WLabel was originally added to the WComponent tree.
• If the WLabel is for a WSelectToggle in the TEXT state then it will be output as part of the WSelectToggle and, if it was part of a WPanel Layout, will always leave an empty container where the WLabel was originally added to the WComponent tree if it was placed in any such container.
• If the WLabel is for a WComponent which outputs a complex form control then the WLabel will be output in-situ and as the legend of the control's fieldset wrapper. The in-situ rendering though wil be hidden (not out of viewport) unless the label:control pair is used to create a WField itself a child of a WFieldLayout with LAYOUT_FLAT and not responsive to a narrow viewport.

Hidden components

Any WComponent in a hidden state (except WLabel as described above) will have the same UI consequence as any component with no UI artefact whilst in the hidden state. If the hidden WComponent is subsequently shown using a WSubordinateControl then the component will no longer have this UI impact. This obviously has ramifications when the WComponent is added to a WPanel layout etc. but these ramifications are not necessarily a cause of error.

If a WComponent in a hidden state is the sole content of another WComponent then that outer WComponent may suffer from being empty and may be causing an accessibility error in the application.

Difference between imperceptible and no in-situ artefact

A component is imperceptible if it is not currently available to any user. This includes any component (other than WLabel which is hidden by a WSubordinateControl and any content of:

• a collapsed WCollapsible;
• a closed WTab;
• a closed WSubMenu; and
• a collapsed WTable expandable row's sub-row(s).

When an imperceptible component is added to a layout (this would only be the case if the component is in a hidden state) then there may be a layout rendering issue but that would be resolved when the component is made perceptible.

Some components may be imperceptible to some users (and therefore may not be palpable content) if it has not been created in a way which conforms with expected accessibility standards. Some examples of this condition would be:

• a WButton with an empty string content in which case the button suffers from being empty or
• a WButton with a WImage as content but no way to calculate a text alternative (by having neither text content nor its toolTip property set) in which case the img element does not translate to palpable content as it has no text alternative; or
• a WPanel Of Type.CHROME with a title property set to an empty string in which case the heading artefact of the panel suffers from being empty.

Components in this state are considered to be in an error state. The theme will try to indicate this for some common, lost-cost conditions but cannot do so for all conditions. More checks are added using JavaScript based accessibility testing when in client side debug mode.

Further information

• WContainer;
• List of WComponents.