-
Notifications
You must be signed in to change notification settings - Fork 18
WTree
WTree is a selection component with the appearance of a branching tree. It is a common UI construct which is often mis-applied to navigation in web systems. 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?
- HTML output
- Accessibility
- UI Properties
- The Type property
- Sending state to the application
- AJAX and WTree
- Related Components
- Further information
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.
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.
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 WMenu provides a single focus point and focus within the menu is generally driven from the ARROW keys. In all cases pressing TAB will exit the menu.
All WTree in a UI must be associated with a label or otherwise have their usage and intent exposed to all users. This may be done using (in order of preference):
-
WHeading or using the WTree as the only content of
- WCollapsible with a HeadingLevel set, or
- WSection, or
- [WPanel] of
WPanel.Type.CHROMEorWPanel.Type.ACTION;
- WLabel or by using the WTree in a WFieldLayout; or, if the label does not have to be visible in the UI,
- using the toolTip property; or
- using the accessibleText property.
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.
The following properties of WTree impact how the tree appears and functions in the UI.
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.
This property indicates the item selection model for all of the tree's items including branching items. 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.
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.
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.
This property 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.
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.
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.