WMultiTextField
WMultiTextField is a component for creating a multi-input tool from a sequence of single line text fields.
- Why use WMultiTextField
- Accessibility
- Input constraints
- HTML output
- Disabling
- Hiding
- Read-only
- Appearance
- Related components
- Further information
WMultiTextField allows the collection of a list of user-entered free-text values. This differs from a multi-line text input (such as WTextArea) in that the values are discrete and do not rely on any attempt to parse a block of text into discrete values.
The value(s) added to a WMultiTextField are not guaranteed to retain their order therefore WMultiTextField should not be used if the order of the values added is important. The user interactions of WMultiTextField do not conform with any common paradigm therefore it may be better to use a group of individual WTextField components than a single WMultiTextField for some simple use-cases.
Each text input and the add/remove buttons in WMultiTextField are currently individual controls accessed using the TAB key. This is an unfortunate state of affairs as it leads to excessive key presses when navigating through the control. This is currently under investigation but it may be difficult to group the controls and allow ARROW navigation due to the lack of a standard WAI-ARIA construct for this type of group.
All operations (add, remove, update) are available from a standard keyboard.
All WMultiTextField in a UI must be associated with a label. This may be done using:
- WLabel (preferred) this is required if the label must be visible in the UI; or
- using the toolTip property if the label does not have to be visible in the UI; or
- using the accessibleText property of WMultiTextField.
A WMultiTextField which is not appropriately labelled may display an unlabelled control warning.
When designing a UI containing a WMultiTextField the WLabel must be placed immediately above the control unless the control is in a WFieldLayout with layout LAYOUT_FLAT in which case it should be immediately before the control.
A label for a WMultiTextField is implemented as a HTML legend element immediate child of the WMultiTextField's fieldset.
If the WMultiTextField is associated with a WLabel (including by being added to a WField) then the content of the label is also output in-situ as a HTML span element. This span is then marked as aria-hidden="true" to prevent double reading in PC mode but has scripted helpers to ensure it behaves in a manner equivalent to a legend (for access key support) and a label (for mouse users). Under most circumstances, using the default theme CSS, the pseudo-label will be hidden from all users and AT and the legend will be visible. When in a WFieldLayout with LAYOUT_FLAT, however, this is changed and the pseudo-label is made visible and the legend moved out of viewport (not hidden). This keeps the label for a WMultiTextField consistent with WLabels for simple inputs.
Where a WMultiTextField has its toolTip property set but is not associated with a WLabel the content of the toolTip is placed in the legend and may be rendered out of viewport.
If the WMultiTextField has a input constraints then there must be an indication of these constraints somewhere in the UI and available to all users. The appropriate place for this information is in the WLabel hint.
If the control is mandatory this indication is automatically generated within the legend element and the legend (if visible) and pseudo-label (if present) are both decorated accordingly.
See toolTip. A WMultiTextField may use the toolTip property if it is not possible to include a label in the UI. This should be a last resort.
// with WMultiTextField field
field.setToolTip("Some further context to this field.");WMultiTextField may have accessible text applied as information additional to the visible label text. This should be used with care and restraint as it may result in less accessible applications.
// with WMultiTextField field
field.setAccessibleText("Some further context to this field.");A WLabel for a WMultiTextField may be given an access key to provide rapid keyboard access.
A WMultiTextField in an enabled, interactive state may be set as the default focus point for a page. 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. When focussed the first input element will receive focus.
A WMultiTextField may be constrained to be mandatory and/or accept a maximum number of values and each value may be constrained by length (minimum or maximum).
A WMultiTextField may be marked as being a mandatory field in the UI. The primary indicator of this is the presence of the required attribute on the HTML select element. The WLabel for the component is decorated with a visual indicator that the component is mandatory as a secondary indicator.
// make WMultiTextField `field` mandatory
field.setMandatory(true);A WMultiTextField may be constrained to a maximum number of unique values which may be entered. If this is set then an indication of the maximum number of allowed entries should be given to the user within the associated WLabel. It is completely inappropriate to set the maximum values to 1: for this use case use WTextField and stop being silly.
Note that multiple occurrences of the same string are treated as separate values for determining whether this maximum has been reached. This may be considered a bug but no-one has complained yet.
// make WMultiTextField `field` accept no more than 3 values
field.setMaxInputs(3);The text inputs within a WMultiTextField may be constrained to accept a maximum number of characters. When this value is reached the input will not accept any further characters until at least one character is deleted. This is based on characters, not on bytes, and is character set dependent.
// make WMultiTextField `field` accept no more than 10 characters per input
field.setMaxLength(10);The text inputs within a WMultiTextField may be constrained to accept a minimum number of characters which is acceptable if any content is entered at all. This will not make the component mandatory as this constraint is not checked if no characters are entered.
// make WMultiTextField `field` accept no fewer than 10 characters per input
field.setMinLength(10);The inputs within a WMultiTextField may be constrained to accept a specified format. This is expressed as a JavaScript regular expression. If this property is set then there must be an indication what for required format is in a form which is available to and understandable by users; this indication may be included in the WLabel hint or the component's toolTip. Note that when a pattern is set the title has special semantics and is the 'preferred' means for exposing the natural language equivalent of the pattern:
When an input element has a pattern attribute specified, authors should include a title attribute to give a description of the pattern. User agents may use the contents of this attribute, if it is present, when informing the user that the pattern is not matched, or at any other suitable time, such as in a tooltip or read out by assistive technology when the control gains focus.
WMultiTextField outputs a HTML fieldset element. The text input elements are then placed inside this fieldset. WMultiTextField outputs non-phrasing content and form-related interactive content and must not be used in any context which forbids these content categories. The WLabel (or content of the toolTip) for a WMultiTextField is output as the fieldset's legend.
A WMultiTextField may be disabled on page load. When disabled the WMultiTextField will not respond to user input or interaction and all text fields will be disabled. This property may be used in conjunction with WSubordinateControl controls to enable or disable content without making another server call.
A WMultiTextField may be hidden on page load. When hidden the WMultiTextField 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. When a WMultiTextField is hidden a WLabel associated with it is also hidden.
The read-only state changes the output rendering of the WMultiTextField so that it appears as a text representation of the control. The control is not able to be interacted with by the user and does not return any value back to the application. Only those values which were entered according to the last submitted state of the control are output in read-only mode.
A WMultiTextField in a read-only state may be the target of a WSubordinateControl or WAjaxControl. If it is the target of an AJAX action its state may be changed to remove the read-only setting.
WMultiTextField looks like a normal text input element followed by a button to add another option. When more than one option is entered the appearance is a vertical list of input elements and all but the first are followed by a button to remove the selection.
The text inputs within a WMultiTextField may be specified to be a particular width. The actual width is determined by the user agent based on this property. This property has no default and if not specified the user agent will determine the width of the text field. This property is not enforced when in a read-only state. In addition the width of the text fields will not exceed the width of the total component and that is constrained by its container. The width of the component may be further constrained when in a WFieldLayout using the WField inputWidth property.
