Contextual help

Notes for developers

Context help blocks work by the addition of a link icon with a supporting data-module="a-context-help" data-module-load="true" attribute. As with modals and other components which use Javascript to recreate their content, the main body of the content for the tooltip/modal should be positioned at the bottom of the page (ie, after the rest of the main page content). The contextual help content should begin with a heading which contains the same copy as the link text, so that a user will know the right content has been activated; this is especially important for the non-JavaScript fallback, which will send people to the bottom of the page where there may be several contextual help content blocks.

The modal variant is created the same way as the toolip version, with the addition of the data-variant="modal" attribute. The same rules apply with regard to content placement, headings and so on.

If the text content of a tooltip variant exceed the limit specified in the usage guidelines, the modal variant will be forced anyway. Equally, if a tooltip is incorrectly placed within the normal flow of paragraph content, a modal variant will be forced to prevent the page breaking visually.

For uses with form rows, content is set up as per explanatory text, with the addition of the data-module="a-context-help" data-module-load="true" attribute and a unique id value; this MUST be unique, regardless of whether the same content is used for multiple instances, as it is converted into an id/href pair. If JavaScript is not available, this variant will fall back to a simple explanatory text atom. Be sure to also complete the data-accessible-text content as well; this is converted to hidden text which screen readers will use to apply additional contextual information as to what activating the module will do. This can be as simple as "Help about..." and a repeat of the label, but try to make it as meaningful and as helpful as possible. If this attribute is not completed, the fall back will simply be "Help".

Aria usage for errors and help text

To aid screen reader users in completing forms without error and also with understanding and fixing any errors that have occured, some additional aria attributes are now recommended to be applied across all form fields/rows.

All form row help, explanatory text, form row instructions and form row errors must have a unique id assigned to them and be appropriately linked to either the individual form input or the form row using aria-describedby. This ensures that the help text is read out immediately on focus of the form input/fieldset. When there is more that one item that requires referencing within the aria-describedby attribute the id values must be supplied in the form of a space separated list. For example if there is an error with id of 'err1' and help text with id of 'help1' the value for the aria-describedby attribute would be 'err1 help1'.

All inline form error messages should start with the hidden text 'Error: ' so that when read by out by a screen reader it is immediately clear that the text being read is an error message.

All erroring form fields (or fieldset if a group or radios/checkboxes) must have aria-invalid="true" set on them, ensuring that when a user focus' on an errored form field, the field will be announced as invalid, so the user is then aware that there in an issue that requires fixing.

When linking help or errors, or even adding aria-invalid to the markup careful consideration must be taken as to where it is most appropriate to apply the value. The following rules should be used to decide where the attribute(s) should be applied.

• Single form field - All attributes should be applied directly to that form field
• Group of form fields but only one in error or help text applies to only one - Apply the attribute(s) to the only field in error or where the help text applies
• Group of form field where all in error or the help text applies to all - Apply the attribute(s) to the groups surrounding fieldset (form row)

There may situations where more than one of these rules applies to the overall form row for example a date range where the instruction text applies to both fields so should be linked to the fieldset for the date range but one of the two fields is in error so the error should be linked to just that field not to the fieldset.

Controling the contextual help programatically

Contextual help can be controlled programatically to close the contextual help box/modal. The following method is available for use:

For example:

										document.addEventListener( 'frameworkready', function () {
											FRAMEWORK.require([ 'blocks/a-context-help' ], function ( aContextHelpModule ) {
												var aContextHelpEl = document.querySelector( '#multiselectId' ),
													aContextHelpInstance = aContextHelpModule.initInstance( aContextHelpEl );		aContextHelpInstance.close();
											});
										});
									

Changing locale settings

Default text for contextual help can be changed for a particular locale.

										
											en: {
												aContextHelp : {
													formText : 'Help',
													closeText : 'Close',
												},
											},
										
									

For more information on this, see our page on how to change locale settings within JavaScript.

---

Notes for testers

• Ensure that all instances of context help icons have matching content.
• Ensure that all instances of context help has an associated heading as part of the main content.
• Ensure that all instances of context help within form rows have a unique href value.
• Ensure users can use both the x icon and the close button within the tooltip/modal to dismiss the contextual help.
• Ensure users can open/close contextual help instances using both mouse/touch and keyboard.

---

Classes overview

The following table gives you a quick overview of the CSS classes that can be applied.

---

Keyboard operations

TAB

Tabbing to an checkbox input should make the input clearly visually different so that the focus point on the page is obvious to the user.

CURSOR KEYS

With focus on the checkbox, pressing SPACE will select/deselect the checkbox.