WFieldSet
WFieldSet is a component for grouping WComponents which output form controls into semantic sets. An example use of a WFieldSet would be to group all of the controls in an address block or credit card details block.
- Creating a WFieldSet
- HTML output
- Display and interaction
- UI Properties
- Access Keys
- Margins
- Using WFieldSet
- Why use WFieldSet
- When not to use a WFieldSet
- Related components
- Further information
WFieldSet has two constructors. The argument in each is the labelling component of the WFieldSet and should comply with the requirements for a HTML legend element.
The first constructor takes a String argument. This String is the content of the fieldset's legend.
WFieldSet fset = new WFieldSet("Address");The alternate constructor takes a WComponent argument. This WComponent must be one which outputs content suitable for use in a legend element. It should have perceptible content and preferably text content. The legend must contain only text or phrasing content. It is recommended that this labeling element should not include any interactive content, though this is not currently an error state if contravened.
// Create a fieldset in which the 'legend' has text content and an image.
// Assume WImage `icon` and WText `labelText`:
WDecoratedLabel legend = new WDecoratedLabel(icon, labelText, null);
WFieldSet fset = new WFieldSet(legend);WFieldSet outputs a HTML fieldset element. This is not able to be used in any component which can contain only phrasing content. A fieldset will occupy the full width of the notional content box of its parent element.
The WDecoratedLabel labeling component of a WFieldSet is output as the fieldset's HTML legendHTML legend element. It is recommended (though not enforced) that this component not include any interactive content.
WFieldSet has a frame property which allows you to remove the fieldset decoration.
Judicious use of this property allows you to make a fieldset less visually obtrusive without losing the accessibility benefits. Many of the benefits of a fieldset are visual so this property should not be set as a matter of course.
Complex form controls with their own automatic fieldset have a frameless property which can be used to remove the fieldset decoration. To move the legend out of the viewport the label of the component must be either a WLabel for the component specified as hidden or set using the component's toolTip property.
The display of the legend of a WFieldSet is determined by the frame property. If this property is NO_TEXT or NONE then the labeling element is moved out of the viewport; otherwise it is displayed as a fieldset legend. The normal position for a legend is in the upper left of the fieldset and inset into the frame.
The legend must contain only text or phrasing content. It is recommended that this labeling element should not include any interactive content, though this is not (yet) an error state if contravened.
If a WFieldSet has an access key then triggering this access key will cause the first focusable element in the fieldset's content to gain focus. This is default behaviour in common user agents.
- If that component is a button or link then some user agents will automatically fire that button/link.
- If that component is a radio button then the selected radio button (if any) will get focus.
- If there is no selected radio button then the first radio button will be focused and it may become selected.
- If there are no focusable elements in the fieldset then the access key behaviour is undefined but a fieldset is used only to group form controls so if your design includes this condition then the design is wrong!
The following are the properties of WFieldSet which are available for manipulation within an application and which have a UI consequence.
This property determines the appearance of the fieldset's border and other decoration and the location or appearance of the labeling element. The available settings are
-
not set: the fieldset will have a border and background decoration and the legend will appear in the default position and style for a legend;
-
NO_TEXT: the fieldset will have a border and background decoration but the legend element will be moved out of the viewport;
-
NO_BORDER: the fieldset will have no decoration, the legend will appear in the default position and style for a legend;
-
NONE: the fieldset will have no decoration, the legend will be moved out of the viewport.
This property allows you to move the legend out of the viewport without making the fieldset inaccessible, remove the fieldset decoration, or both. Judicious use of this property allows you to make a fieldset less visually obtrusive without losing the accessibility benefits. Many of the benefits of a fieldset are visual so this property should not be set as a matter of course.
The WFieldSet must have an appropriate legend even if the frame property is NO_TEXT or NONE.
The hidden property
A WFieldSet may be hidden on page load. When hidden the WFieldSet 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 marks a WFieldSet as being mandatory in the UI. The fieldset itself is not an interactive control and therefore being mandatory is not intrinsically meaningful. When a WFieldSet is marked as mandatory it means that at least one field within the WFieldSet must be completed without any one field being explicitly mandatory in its own right.
This is best illustrated with an example. Given a set of fields to ascertain a telephone number there may be three options: home, work or mobile. A valid response is to provide at least one of these but no individual field is absolutely required. In this case the fields should be encapsulated in a WFieldSet since they are a semantic group which all provide an answer to the question "what is your telephone number?". To mark this group as requiring an answer the WFieldSet has its required property set true.
A WFieldSet may be given an access key as a keyboard shortcut to its content. When used this access key will focus the first form control within the WFieldSet. See Using Access Keys for more information.
If interactive content is added to the labeling element then this is part of the fieldset's content and will gain focus from using the access key, even though it is not part of the WFieldSet's content. You should note, however, that it may be a significant accessibility failure to do this.
WFieldSet is a marginable component.
WFieldSet is a component which is not used as widely as it ought. This is almost entirely due to it not being specified as often as it ought.
A fieldset represents a group of form controls grouped under a common description. The labeling element of a fieldset (a legend) is used to give the user a context for completing the data input controls inside the fieldset.
A fieldset is used to group multiple input controls into a single block representing all required information to complete a particular task such as:
- fields to complete a credit card details section;
- date ranges;
- multiple fields to complete an address block;
- grouping otherwise identical sets of fields to provide context such as Home, Business and Postal addresses;
- grouping selection controls (checkboxes or radio buttons) to provide one or more 'answers' to a common question.
The HTML5 specification states:
The fieldset element represents a set of form controls optionally grouped under a common name.
This statement implies that a fieldset should contain two or more interactive form controls (not in a read-only state). In theory, however, a set may consist of zero or more elements. A primary position in number theory is the definition of the counting numbers starting at zero which is defined as the set of all items which are not in any set. This is, indeed a set but it is a set with zero members.
It is advised that a fieldset ought to consist of at least two form controls which are not in a read-only state but this advice will not be enforced.
Some single WComponents output compounds of several form-bound controls. Each of these components use a HTML Fieldset element as their root output element. This has the following implications:
- you must not use a WFieldSet as a container for exactly one of these components: the fieldset is part of the component; and
- if the content of a WFieldSet includes one or more of these components in conjunction with other components you will have a nested fieldsets which may cause issues for some users.
A fieldset performs several important tasks:
- It provides context to the user, including providing valuable information to users of assistive technologies which may not be provided by using a heading. This is especially important in the case of multiple blocks of otherwise identical form fields;
- It can provide a visual separation of form sections which aid in cognitive assimilation of the form;
- It can provide a means by which the user's eye can 'rest' on a particular section of a complex form;
- It provides the only means to semantically group a set of form controls into a single compound control;
- WCAG 2.0 Guideline 1.3.1 makes specific note that fieldsets should be used to provide a description for form controls H71.
If your UI contains a group of individual input controls which form a semantic group they must to be placed into a WFieldSet. If the controls are a compound control output from a WComponent which outputs a complex form control then it does not need to be added to an explicit WFieldSet but you should still specify if it is to have its fieldset decoration removed (using the frameless property). Note, however, that if a compound control is the only component in the group then it must not be added to an explicit WFieldSet.
- If you group all of your components and you end up with a single fieldset then you probably do not need to use one.
- If you have a single fieldset and the fieldset forms the only content of a WSection, WPanel of Type
CHROME, WPanel of TypeACTIONor a block of content headed by a WHeading then you probably do not need the WFieldSet. - Do not use a WFieldSet as a wrapper if the fieldset content would consist of exactly one WComponent which outputs a complex form control.
- Do not use a WFieldSet as a container for controls which are not form controls or are form controls in a read-only state.