-
Notifications
You must be signed in to change notification settings - Fork 18
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.
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 legend element. It is recommended (though not enforced) that this component not include any interactive components.
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 controls, though this is not 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 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.
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.
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.
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.
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.
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.
Some single WComponents output several form-bound controls. Each of these components use a HTML fieldset element as their root output element. This has the following implications:
- you should 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.
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.
- 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 Type ACTION or a section 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.