Skip to content

WCollapsible

Jump to bottom
Mark Reeves edited this page Jan 3, 2018 · 27 revisions

WCollapsible is a component for adding a section of content which is able to be collapsed down to a label.

Why use WCollapsible

WCollapsible allows a chunk of optional UI to be moved out of the way. Whether this is a good thing is a matter of debate. Some possible uses of WCollapsible include:

  • hiding optional search criteria if the common use-case is for a simple search but there is a need for possible refinements;
  • hiding filter criteria or initial search criteria when showing a result set so that t he user can refer back to and potentially refine a search without having the search controls clutter the results view;
  • putting too much stuff into a single page.

Using several WCollapsible components to simply place a whole lot of application information or controls into a single view is not uncommon but is not a good design paradigm. Using LAZY ajax mode can help improve performance in cases where much of the UI is unnecessary for most common uses.

If a UI design calls for a number of consecutive WCollapsible controls in a view it may be more appropriate to use an accordion tabset.

Creating a WCollapsible

A WCollapsible must have a content component when being instantiated. It is highly recommended that this component be a WContainer unless specific layout is required within the WCollapsible's content. In this latter case it may be approporiate to use a WPanel. If a WPanel is used as the WCollapsible's content container it is highly recommended that the WPanel not have its type set.

A WCollapsible also requires a heading. This can be a String or a WDecoratedLabel. If the WCollapsible has a String heading this is converted to a WDecoratedLabel with the String content forming the body segment. In both cases the WDecoratedLabel may be obtained for further manipulation.

// container may be added to later.
WContainer collapsibleContent = new WContainer();
// assume a string label for now
WCollapsible collapsible = new WCollapsible(collapsibleContent, "Further details");

The WCollapsible may also be created with a specified Mode.

// container may be added to later.
WContainer collapsibleContent = new WContainer();
// lazy mode is useful if we expect the probability the collapsible will be opened is low.
WCollapsible collapsible = new WCollapsible(collapsibleContent, "Further details",
    CollapsibleMode.LAZY);

If the view contains a CollapsibleGroup then the WCollapsible may be added to it during construction.

CollapsibleGroup group = new CollapsibleGroup();
// probably want to attach a WCollapsibleToggle to the group at some stage.

//...

// container may be added to later.
WContainer collapsibleContent = new WContainer();
// lazy mode is useful if we expect the probability the collapsible
// will be opened is low.
WCollapsible collapsible = new WCollapsible(collapsibleContent,
    "Further details", CollapsibleMode.LAZY, group);

Accessibility

Keyboard control

The open state of a WCollapsible may be toggled from the keyboard using the SPACE bar. If the user agent has no native support for details/summary then the summary element has a role of button and the open state of the details element is reflected in the aria-expanded attribute.

The summary content may be exposed as a heading using the headingLevel property which may help some user agents and assistive technologies provide landmarks and navigation cues for complex interfaces.

The summary element content is generated from WDecoratedLabel so could contain complex content. This should be avoided and the summary content must comply with the content model of the summary element. More importantly: the summary should stand as a brief and meaningful summation of the WCollapsible's content.

Labelling

The WCollapsible's labelling element must comply with the following requirements:

  • the content must provide an adequate short summary of or caption for the WCollapsible's content;
  • the content must include palpable content;
  • the content must include content which is available to assistive technologies, for example if the labelling element contains only an image then that image must have an appropriate 'alt' attribute which indicates the intent and purpose of the WCollapsible's labelling element and content;
  • the content must contain only phrasing content;
  • the content must be suitable for a HTML summary element.

It is recommended that the labelling element should not contain any interactive content as this may lead to usability problems when the interactions with the labelling element which is also the controller for the open state of the WCollapsible may conflict with or be perturbed by the interactions for the added interactive content.

Headings

The [HeadingLevel] property allows the WCollapsible's labelling component to be exposed as a HTML heading element h1-h6. This can improve accessibility for views which contain many WCollapsibles with repeated content. This scenario could be considered a design flaw. This property must be used with caution though as it can lead to the creation of other accessibility problems. Note that if the browser does not implement native details element support then the summary will be given a role of "button" and several aria-* attributes. THe button role overrides the native semantics of any descendant element, which will make the heading level completely pointless and possibly make applications less accessible.

If the headingLevel is set then the appropriate [HeadingLevel] must be used. A WCollapsible does not create a sectioning root. Therefore the [HeadingLevel] should almost certainly not be HeadingLevel.H1. The heading must be sequential within the nearest ancestor sectioning root. See specifying the HeadingLevel for more information.

// given a WCollapsible collapsible
// set it's label content to be in a H2 element.
collapsible.setHeadingLevel(HeadingLevel.H2);

Note that the labelling component of a WCollapsible will remain a HTML summary element. If the heading level is set then the content of the labelling component must comply with the content requirements and restrictions of both the summary element and a heading element.

Usability

You should refrain from putting mandatory form controls into the content of a WCollapsible which is not open by default. All input controls should be perceivable by the user. If a section of a UI is optional then it may be a candidate to inclusion in a WCollapsible but it also may be a candidate for removal.

A view which has several or nested WCollapsibles may be too complex and be a candidate for redesign. Any view which contains nested WCollapsibles or more than approximately 3-5 WCollapsibles should undergo further user testing.

Open state

The collapsed state of a WCollapsible will reflect the last used state in the current session: but what if there is a new session? The open state can be set using the collapsed property. The default is to be collapsed, therefore when specifying a WCollapsible one should indicate the conditions under which it should be open on page load.

// given a WComponent collapsibleContent,
// a WDecoratedLabel or String label
WCollapsible collapsible = new WCollapsible(collapsibleContent, label);
// to set the WCollapsible to be open on first use:
collapsible.setCollapsed(false);

To determine the open state of a WCollapsible:

// given a WCollapsible collapsible
collapsible.isCollapsed()
    ? /* do something if not open */
    : /* do something if open */;

Expansion modes

WCollapsible has a mode property which indicates how the WCollapsible's content is loaded, including Ajax modes. This is important in ensuring optimal performance of your applications and the mode should be explicitly specified for every WCollapsible. All modes outlined in Ajax modes are available to WCollapsible.

Appearance

The default appearance of a WCollapsible is very simple to allow for themeing. A screenshot of WCollapsibles

  • when in a collapsed state:

    A screenshot of WCollapsible which is closed

  • when in an open state:

    A screenshot of WCollapsible which is open

Headings

The default theme styles all heading levels so that they appear exactly as a WCollapsible with no heading level set. This is done to ensure consistent UIs and to make theme overrides easier. The setting of a heading level is generally done to aid users of some assistive technologies by providing landmarks within a complex UI. As mentioned previously: this scenario could be considered a design flaw. The first illustration below shows a WCollapsible with heading level set to HeadingLevel.H2, the second is a closed WCollapsible with no heading level as a comparison.

A screenshot of WCollapsible which is closed and has heading level H2

A screenshot of WCollapsible which is closed

HTML output

WCollapsible outputs a HTML details element. The WCollapsible's labelling element outputs a HTML summary element.

Any WComponent may be added to the content of a WCollapsible.

Hiding

A WCollapsible may be hidden on page load. When hidden the WCollapsible is not available to any compliant user agent. It is present in the source and is not obscured in any way. This property is determined by a WSubordinateControl. When a WCollapsible is hidden all of its content is hidden.

Grouping

WCollapsibles may be grouped so that they can be controlled by a WCollapsibleToggle. This is done by adding each WCollapsible to a CollapsibleGroup. The important part of this for UI analysts and designers is that if a WCollapsibleToggle is included in your UI you must indicate every WCollapsible included in the group. For more information see CollapsibleGroup.

A WCollapsible may be grouped by:

  • adding the CollapsibleGroup during construction;

    // given a WComponent collapsibleContent,
// a WDecoratedLabel or String label
// a CollapsibleMode mode
// and a CollapsibleGroup group
WCollapsible collapsible = new WCollapsible(collapsibleContent,
  label, mode, group);

  • Setting the CollapsibleGroup on the WCollapsible;

    // given a WComponent collapsibleContent,
// a WDecoratedLabel or String label
WCollapsible collapsible = new WCollapsible(collapsibleContent, label);
// assuming a CollapsibleGroup group
collapsible.setGroup(group);

    or

  • Adding the WCollapsible to a CollapsibleGroup.

    // given a WComponent collapsibleContent,
// a WDecoratedLabel or String label
WCollapsible collapsible = new WCollapsible(collapsibleContent, label);
//...
// assuming a CollapsibleGroup group
group.addCollapsible(collapsible);

Grouped behaviour for nested WCollapsibles

A WCollapsibleToggle will only act on WCollapsibles explicitly added to its group. If a WCollapsible in a CollapsibleGroup has WCollapsibles in its content they will not be affected by the WCollapsibleToggle unless they are also in the same group.

Naming contexts

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

Related components

Further information

Some start pages

Clone this wiki locally