-
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.