Purpose

There are two main purposes for this requirement:

First:  If there are multiple errors or other validation messages on a page after submitting a form, provide users with an "advance organizer" summary, letting them know how many there are. The human brain needs to build a sense of the overall "landscape" first, before diving down into details.  If the design doesn't enable this, users feel less oriented to the task ahead of them (the task of correcting the problems) and project that the task will be bigger, more overwhelming.

Make it easy to navigate from the error summary to the individual errors to fix them.  Research shows that leaving users to locate each individual error, without providing them with this type of a "macro" view, makes them feel more lost in the "micro" specifics - and less certain they have located and fixed all errors, before re-submitting. 

This summary view and ease of navigating is needed for all users, and is needed in particular for non-sighted users who may be using screen-readers and keyboard-only access.

Second:  Place the validation error indication and the error text (applies to warnings and informational messages also) as close as possible to the field that is in error -- to make it easier for all users to locate and then fix the fields in question.  This proximity and visual signalling is helpful for all users, and is needed in particular for low-vision users who may be using screen magnification.

Detailed Description

See sections below and these slide decks:

Usage Scenarios

Usage Scenario One:

Mocks and Diagrams

Note: Consider the below to be "low-fidelity" mockups - these are not intended to specify the precise visual styling, relative placement, wording or branding.  Those details will come later, in specifications. These are intended to convey the task flow and UI architectural constructs to support, only. 

Example Validation Message treatments added to Titles and Headers:

Titles and headers include the validation message icon that is associated with the highest severity message included in the set. In addition, text is appended to the title or header text, indicating how many messages are associated with that set (page, section, etc.).   See example below:

If there are all 3 types of messages, the number of errors is identified, and the aggregate number of other messages is identified.

Example Page-Level Validation Message Summary:

Each of the four lines below are links, to the specific section in question.

  

With the heading text-variable filled in:  

<h2 id="pageSummaryHeading" class="errorSummaryHeading">14 errors in form submission</h2>

Example section-level Validation Messaging:

Example Field-level Validation Messaging:

There is additional visual indication on the appropriate field itself when the user hovers over the specific error message link in the group-level summary.  This helps to locate the appropriate field, among other competing information in the user's field of view.  See the example below, where the user is hovering on the first link (or has moved to the link via keyboard):

There is also a different visual indication-state on the field itself when the user selects it and can enter data.  The tooltip that contains the error message text is also displayed, contiguous with the field, when that field is selected.  The example below shows the placement of the tooltip to be immediately above the field, with its left margin beginning at the center of the field, but the default placement algorithm and the visual treatment details will be determined in the specifications to come later.  Consider this simply a 'low fidelity' mockup and proof-of-concept, with the exact rendering to be determined. 

The fundamental requirement is that the tooltip's default placement be contiguous with the field while not occluding it.   See example below:

The other aspect that is fundamental to the tooltip construct is that it remains visible with the field while the user enters the data. 

Example field-level tooltip content:

If there are multiple messages associated with the same field, they are included in the single tooltip associated with the field, with the highest level severity messages first:

Below is an example of a client-side validation tooltip, which will be visually distinct from a server-side validation tooltip, since the behavior differs (the precise visual treatment tbd).   A client-side validation tooltip pops up immediately upon exiting the field in question, so the user can correct it immediately, before submitting the form:

It is possible that after a page is returned with server-side validation errors, a user could create a new client-side error in trying to fix a field.  In this case, the client-side validation error will be added to the top of the server-side tooltip that is already associated with the field:

When users have made a change to a field that has server-side validation messages associated with it, the tooltip changes slightly, in recognition that the user has already made changes to it, that might resolve the problem(s).  However, because we can't tell until the form is resubmitted whether the change resolves the problem(s), the tooltip content remains associated with the field (when the user focuses on the field, the tooltip pops up):

Mocks and Diagrams summary:

The strategy outlined above addresses the need for a summary of errors (when there are multiple) and the need to place the error indication and text as close to the field as possible -- helpful for all users and also needed particularly for low-vision users.

The tooltip strategy outlined above also solves the formatting problems we otherwise create when we place error message text within each field (whether immediately below or to the right), requiring other space to be pushed aside or down.  Associated challenges include:

This type of tooltip display of error text associated with form fields will be KRAD's default handling and is the recommended practice.  However, KRAD is an open architecture, and will enable applications to turn off this default and turn on their own defined default (for example, an application could define their default to be placing the field-level error text directly below the field, thereby pushing down and aside all other content on the page.)

Code Snippet Example:

You can try out an interactive example code snippet with this behavior here (thanks to Hans Hillen from The Paciello Group for this working prototype!): 

Error message handling - code snippet example  (Click the submit button toward the top left in the prototype, to see example behavior.)

Performance

If applicable, list expectations for performance (optimal and worst cases would be fine, give time in seconds):

References

See tooltip requirement.

Requirements Listing

The following applies to server-side validation messaging:

Off-screen Validation Message Summary with link

The browser window title (e.g. HTML “Page Title”)

Page level summary

Section Level summary

Subsection level summary

The following applies to both server-side and client-side field-level validation messaging:

Field Level  - both server-side and client-side treatments

Dependencies

List any functional or technical work that must be completed before work on this item can begin:

  1. Reseach tooltip plug-ins (see tooltip requirement)
  2. Research and think through what should happen when ajax calls refresh a portion of a page and return server-side errors for just that sub-section/section of the page.  Assume the default is field-level treatment, and summary for just that sub-section or section of the page - with the focus returned to that summary.

Issues

List any issues that need to be resolved before work on this item can begin:

Functional:
  1. item
  2. item
Technical:
  1. item
  2. item

QA or Regression Testing Plan

Plan to test on: 

Required basic test:  Go through steps 1 and 2 using the typical, preferred navigation style (typical GUI users = selecting items and scrolling with mouse, entering data with keyboard).

  1. Select a form to complete and submit: (Note 1:  Should we specify which form, and where in the build?  We need to make sure we test with forms that have both client-side and server-side validation messages created for the fields, and have all 3 types of messages: errors, warnings, and informational messages.)
    1. Try leaving a required field blank and moving on to the next field.  (Correct any client-side validations you get.)
    2. Try putting incorrect data into any field(s).  (Correct any client-side validations you get.)
    3. Complete all required fields and correct any client-side validations you may have.
    4. Save the form.  Submit the form.  (Note 2:  Should we specify which fields in which form to fill out with which values?  We need to make sure we exercise a case which passes all client-side validations and has all required fields completed, but which will have errors, warnings, and informational messages on the form, with some but not all on the same field.  Must have fields with messages in multiple sections.)
  2. After submitting a form that returns with multiple validation messages, review and correct each field that has an associated validation message(s).  When there are no client-side validation messages and all fields that have server-side validation messages have been changed (to try to fix them), resubmit the form:
    1. Check the navigation:
      1. From the page-level summary, try out each link in the list to ensure it goes to the appropriate section header.  (Come back to top of page using any method you choose, after following and checking each link.)
      2. From each section-level summary, try out each link in the list to ensure it goes to the appropriate sub-section header (if there are sub-sections) or to the appropriate field (if there are no sub-sections).
      3. (If there are sub-sections) From each sub-section level summary, try out each link in the list to ensure it goes to the appropriate field.
    2. Check the behavior of a client-side validation message added to the tooltip of any of the fields flagged with server-side validation messaging:
      1. Enter an invalid response into the field (e.g. numeric if only character data is valid and vice versa).  
        1. Make sure the client-side validation message is added to the top of the tooltip for that field, upon moving out of the field.
        2. Make sure the client-side validation message is added to the appropriate message summaries (sub-section, section, page).
      2. Enter a valid response into the field (correcting the original server-side error as well as the client-side error you introduced):
        1. Make sure the client-side validation message is deleted from the tooltip for that field.
        2. Make sure the client-side validation message is deleted from the appropriate message summaries (sub-section, section, page).
        3. Make sure the server-side tooltip's and the field border's visual treatment are changed (colors changed to grey/black), to signal that you have made a change to this field that might correct the server-side message condition (we can't tell for sure until re-submit).
    3. Fix all remaining fields that have validation messages associated with them, and re-submit the form.

Additional tests:

Second: (This should be done by the devs before checking their code in for the milestone.  It can also be included in QA testing.)  Run a code-standards checker.  See list of code-checker alternatives (Note - if this second test is run and checks well, the following checks may be redundant.)

Third: Select large fonts through the browser's settings (200%) and the browser setting to ignore the web page's font settings.  Visually inspect the UI while repeating steps 1 and 2, to ensure that all UI elements inherit well the larger font size.  If there are any problems, return the settings to their prior, normal state, and then set the screen to lower resolution, e.g., 800x600, or change the DPI to 200% via the operating system settings.  Visually inspect the UI while repeating steps 1 and 2, to ensure that all UI elements inherit well these larger size settings. 

Fourth:  Select high contrast through the browser's settings as well as the browser setting to ignore the web page's color settings.  Visually inspect the UI while repeating steps 1 and 2, to ensure that all UI elements inherit well the high contrast settings.  If there are any problems, return the browser settings to their prior, normal state, and then select a high contrast theme in the operating system settings.  Visually inspect the UI while repeating steps 1 and 2, to ensure that all UI elements inherit well the high contrast settings.

Fifth (Not testable yet in M1):  Keyboard-only test.  After completing these above, repeat steps 1 and 2, but without using the mouse, using only the keyboard.  Unplug your mouse if you tend to forget and find yourself switching back and forth.

Sixth:  Assistive technologies test:  Repeat steps 1 and 2, using a screen-reader (NVDA, Jaws, and/or Voice-Over).  Turn off your monitor if you tend to forget and find yourself using your vision to supplement the cues you are hearing.  Note:  it is not expected that every dev or every QA resource would do this.  More efficient for 1 or 2 people to invest the time to become more skilled with screen readers' shortcut keys, etc., than for everyone to do so.  But everyone is welcome to do so, using NVDA (free download for Windows), JAWS (free timed download for Windows) and Voiceover (comes free on the MAC).  JAWS still has market share among screen-reading users.

Checkoff

Functional Analysis Complete? No (completed by SME)

Needs Review by KAI? No (completed by SME)

Technical Analysis Complete? No (completed by DM)

Needs Review by KTI? No (completed by DM)

Estimate: 30 hours (completed by DM)

Technical Design: Link Here (completed by DM)

Jira: KULRICE-6672 (completed by SME)

Final Documentation: Link Here (completed by DM)