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.

• Why use WFieldSet
  • Grouping fields
  • How many fields make a set?
  • When not to use a WFieldSet
    • WFieldSet and compound form components
• Creating a WFieldSet
• Accessibility
  • Labelling WFieldSet
  • Empty fieldsets
  • Access Keys
  • Default focus
• Mandating a WFieldSet
• HTML output
• Appearance
  • Configuring appearance
  • Margins
  • Customising based on HTML class
• Hiding
• Related components
• Further information

Why use WFieldSet

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 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 a UI contains a group of individual input controls which form a semantic group they should 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. Note, however, that if a compound control is the only component in the group then it must not be added to an explicit WFieldSet.

Grouping fields

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.

How many fields make a set?

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.

When not to use a 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 Type.ACTION or 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.

WFieldSet and compound form components

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.

Creating a WFieldSet

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);

Accessibility

WFieldSet is used to enhance application accessibility by grouping form controls into semantic units. See WCAG H71. A WFieldSet must itself be accessible.

Labelling WFieldSet

The labelling component for WFieldSet is WDecoratedLabel. There are limitations on the content which can be added to the WDecoratedLabel, and the properties set on the WDecoratedLabel which are needed if the legend produced from the WDecoratedLabel is to be accessible.

• The WDecoratedLabel must not be put into a hidden state. If the legend is required to be removed from the view for design purposes (which is not recommended) then the WFieldSet frame property should be set. This will result in the legend being moved out of view but remaining accessible.
• The content of the WDecoratedLabel must consist of any combinations of text, WComponents which output phrasing content, or HTML elements which are in the phrasing category; and must consist of at least one piece of content which produces palpable content.
• The content should not include interactive form control components.

Empty fieldsets

A WFieldSet can be considered empty if it has zero WComponent form controls which are editable, enabled and visible.

A fieldset is, nominally, a set of fields. It is considered a poor practice to have a set of fields containing zero interactive form controls. Now, anyone who knows their number theory or some basic Russell will know that an empty set is still a set. That is all well and good but it is not a good design or accessibility practice to have fieldsets which do not contain interactive controls so it should be avoided.

Access Keys

A WFieldSet may be given an access key as a keyboard shortcut to its content. When used this access key will focus the first focusable element within the WFieldSet. See Using access keys for more information.

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 in the group will be focused. 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 a design includes this condition then the design is wrong!

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 doing this may cause a significant accessibility issue.

Default focus

A WFieldSet may be set as the default focus point for a page and if the focus request is able to be honoured the first focusable element within the WFieldSet will receive focus.

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.

Mandating a WFieldSet

A WFieldSet may be marked as 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 is set to be mandatory.

// with WFieldSet fs
fs.setMandatory(true);

A mandatory WFieldSet takes part in default validation scenarios of a ValidatingAction (see WValidationErrors) and Client side validation (if implemented).

HTML output

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

Appearance

The appearance of a fieldset is dependent on the user agent and the theme in use. Typically a fieldset will be bound by a border and have a visible legend inset into the top border as shown in the illustration of the top of a sample fieldset below:

Configuring appearance

WFieldSet has a mechanism which allows one to remove the fieldset decoration and/or move the legend out of view (but still available to AT).

Judicious use of this property allows you to make a WFieldSet 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.

// with WFieldSet fs
// remove the border but leave the legend visible:
fs.setFrameType(WFieldSet.FrameType.NO_FRAME);
// remove the border and move the legend out of view:
fs.setFrameType(WFieldSet.FrameType.NONE);
// move the legend out of view but leave the border:
fs.setFrameType(WFieldSet.FrameType.NO_TEXT);
// reset the fieldset to show the border and legend:
fs.setFrameType(null);

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.

  

The WFieldSet must have an appropriate label component even if the FrameType property is NO_TEXT or NONE.

Margins

WFieldSet is a marginable component.

Customising based on HTML class

WFieldSet may have one or more values to be added to the component's wrapper element. This can be used for fine-grain styling of specific components but should be used with care.

For more information see WComponents HTML class property.

Hiding

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.

Related components

• WFieldLayout
• WComponent form controls

Further information

• JavaDoc;
• H71: Providing a description for groups of form controls using fieldset and legend elements
• List of WComponents.