Skip to content

WTree

Jump to bottom
Mark Reeves edited this page Jan 4, 2018 · 11 revisions

help required please complete this page with code snippets, screen captures and other examples.

WTree is a selection component with the appearance of a branching tree.

When to use WTree

WTree is a complex selection tool. It is useful for selecting from a large heirarchic set of options. For most applications a WTree is over-kill and other selection tools should be investigated first.

WTree is a selection component with the appearance of a branching tree. The closest analog to WTree with which many people may be familiar is the tree structure found in a file manager such as windows explorer or OX X finder app. The tree in these applications is used to select a file or directory, the act of selection then determines what happens with the selected item.

It is not incorrect to use a tree as a navigation tool so long as the state of the tree reflects the selected node: navigation is a consequence of selection.

Why is WTree a selection tool?

A tree is a selection tool because that is what it is. In common web use a tree may be used as a navigation tool, but this is a side effect. WTree is exposed as a compound widget with a WAI-ARIA role of tree. This role is a subclass of the select role which is:

A form widget that allows the user to make selections from a set of choices. http://www.w3.org/TR/2011/CR-wai-aria-20110118/roles#select

Each item in a WTree is exposed with the WAI-ARIA treeitem role.

When not to use

WTree should not be used if the options from which selection is to be made do not form a natural hierarchy. It is probably inappropriate to use a WTree to select from a small number of options which have a single level of grouping where the groups themselves are not appropriate for selection. For this purpose a WMultiSelect or WSingleSelect with option groups would probably be more appropriate.

Even use cases in which a tree selection tool may be appropriate may be better served by other means. Take, for example, the common trope of selecting a motor vehicle for insurance purposes. One would usually select a brand, then a model, then a sub-type and possibly even a fourth level. This could be a tree but the usual arrangement is to use a set of ajax-powered single selection tools where each level is determined by the selection in the previous one.

So when is it appropriate to use WTree? Almost never.

Creating WTree

to be written

Accessibility

Access without a mouse

All of the interactions of a tree are able to be driven from a keyboard or other device. The interactions are based on the WAI-ARIA authoring practices for a tree view

For keyboard users a WTree provides a single focus point and focus within the tree is generally driven from the ARROW keys. In VERTICAL orientation pressing TAB will exit the tree, in HORIZONTAL orientation TAB will first move to the last branch resize handle (if any) then the next TAB will exit the tree.

When in HORIZONTAL tree orientation the branches may be resized by tabbing to the resize handles and using the ARROW keys.

Pressing an alpha-numeric key when a tree has focus will move the selection cursor to the next available item which starts with a case-insensitive match of the key pressed (if any) and select that item.

Labeling a WTree

All WTree in a UI must be associated with a label or otherwise have their usage and intent exposed to all users.

If visual context is obvious then this is best done by using the WTree's [accessibleText|WComponents accessibleText property]] property, noting, though, that the assumption of obvious is a dangerous one.

For all other cases labelling may be done using (in order of preference):

Note that the order of preference between toolTip and accessibleText as optional methods for labelling is the reverse of that for simple form controls.

When designing a UI containing a WTree and a visible label the WLabel must be placed immediately before the WTree. This is done automatically by WFieldLayout.

Additional labelling text

WTree may have accessible text applied as the sole labelling text (if context is obvious to non-AT users) or as information additional to the visible label text. This should be used with care and restraint as it may result in less accessible applications.

// with WTree `field`
field.setAccessibleText("Some further context to this selection");

Setting a toolTip

See toolTip. A WTree may use the toolTip property if it is not possible to include a label in the UI. This should be a last resort.

// given WTree `field`
field.setToolTip("context for this selection");

Default focus

A WTree in an enabled, interactive state may be set as the default focus point for a page. If this is specified it must comply with accessibility principles regarding focus and not put users into a position where they may skip content required for full understanding of the current view. See Setting focus for more information. When a WTree acquires focus the first enabled treeitem will gain the focus.

Appearance

The appearance of a WTree depends on its Type - either VERTICAL or HORIZONTAL.

todo get illustrations of each.

Type

This property determines whether the tree is a vertical tree view (default) or a horizontal tree. This property has a significant effect on how the component renders and how it is used. The available values for this property are:

  • Type.VERTICAL will create a vertical tree; and
  • Type.HORIZONTAL will create a horizontal tree.

Selection modes

WTree may be a single select component or a multi-select component. The selection mode is set on the tree and applies to all branches and leaves of that tree. The details of the selection vary between vertical and horizontal trees when in multi-selection mode.

A WTree must have a selection mode. The default is SINGLE which allows only one item to be selected at a time. In this state a tree is a complex analog of a group of radio buttons. The options for this property are:

  • SelectMode.SINGLE; and
  • SelectMode.MULTIPLE.

When in multiple selection mode the WTree is a complex and hard-to-use analog of a group of related check boxes.

Vertical tree multi selection

In a vertical tree non-contiguous items may be selected from many open branches. Opening a branch is distinct from selecting the branch.

Horizontal tree multi selection

When in multi-selection mode items may only be selected from a single branch and selecting and opening a branch are initially synonymous (in that opening a branch will select it and selecting a branch will open it if there is no other selection of that branch's siblings). If a branch is selected it will be open. If another branch or leaf sibling of that branch is then selected the open branch will close. Only one branch path may be open at a time: a single branch and its branch ancestors consist a branch path.

HTML output

WTree will output a HTML div element. This precludes a WTree from being placed in the content of WComponents which must only contain phrasing content. The tree will also contain button elements so must not be placed in any context which precludes interactive elements.

Disabling

A WTree may be disabled on page load. When disabled the WTree will not respond to user input or interaction. All items will be disabled and will not be able to be selected or deselected. Branching items will not be able to be expanded or collapsed.

If the WTree is not disabled individual items may be disabled to prevent the selected or expanded state from being changed.

This property may be used in conjunction with WSubordinateControl controls to enable or disable the tree without making another server call. It is currently not possible to use a simple WSubordinateControl to change the disabled state of individual items in the tree.

Hiding

A WTree may be hidden on page load. When hidden the WTree 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.

Expansion mode

The expansion mode determines how the content of branches is loaded. For more information about Modes, performance implications, and determining the correct mode to specify see Ajax modes. The following modes are available:

  • ExpandMode.CLIENT;
  • ExpandMode.LAZY;
  • ExpandMode.DYNAMIC.

Sending state to the application

WTree will, if not disabled, send the following state items to the application during a POST (through AJAX or a https form POST):

  • the row identifier of each selected item;
  • the row identifier of each expanded item.

If the expansion mode is either LAZY or DYNAMIC then each request for new items will only report the row identifier of the item currently being expanded.

AJAX and WTree

WTree may be a trigger for a WAjaxControl. In this case the full state of the tree is reported along with the state of the rest of the current view and may be used to update other sections of the UI. The AJAX action will be undertaken on selection and deselection of items, not on expand/collapse.

Triggering a WAjaxControl is not undertaken on expand/collapse as branch expansion should not be tied to any extraneous event: when a user expands a tree branch she expects the action to be expanding the branch and not changing random other stuff in the UI. Note, however, that if the type is Type.HORIZONTAL then expansion is always linked to selection and the only way to collapse a branch is to select an item which is neither in the branch nor is the branch's parent item, and therefore collapsing a branch is always associated with selection, though not the selection of the branch's parent item. Clear as mud.

todo Need info about applying an Action to a WTree - selection action and expand action as appropriate.

Related Components

Alternative multi selection components

Alternative single selection components

Further information

Some start pages

Clone this wiki locally