Over a million developers have joined DZone.

Calling Accessible Context-Sensitive Help with Unobtrusive DOM/JavaScript - Part 1

· Web Dev Zone

This article was contributed by my good friend, accessible designer and co-founder of The South African Web Standards and Accessibility Group, Frank Palinkas. This is part one of a two part series that explores a new accessible way of providing context sensitive help to both form fields and a complete form (Coming in part 2).

Field Help Method

Our Objectives

  1. Contain all Context-Sensitive help within the markup of the web form, placed below each field label.
  2. Control the open/close display state of the help by user action through unobtrusive DOM/JavaScript.
    1. Open help by activating/clicking the help icon image on the right side of a field label.
    2. Close help by activating/clicking the help icon image a second time.
  3. If scripting is turned off in the browser:
    1. Automatically display the help content beneath each field label.
    2. Disable the anchor links applied to all help icon images.

Below is a screen shot of the final form we are working towards. Alternatively, you can follow this link to a working instance of the form. (Opens in a new window/tab)

Sample screen shot of the finished form

 

The Field Help HTML Structural Markup

What are the benefits of this method?

  1. Help is contained within the same web page as the form. It is not external to it as in the Form Help Method.
  2. No pop-up or new window is needed to show the help. This is an important factor regarding web accessibility and standards.
  3. If JavaScript is turned off in the user agent/browser, the Context-Sensitive help will automatically show below each field name.
  4. The anchor elements attached to the help icon image elements that open and close the help will be removed, since there is no action needed to trigger its display.
  5. Important Note: This method also allows users dependant on keyboards to tab through each field and easily activate the help. This is an important useability and accessibility component of the technique.

Unobtrusive DOM/JavaScript Cross-Referencing / Related Container Method (as designed by Gez Lemon of The Paciello Group)

The DOM/JavaScript cross-referencing technique produces a relationship between two markup elements.

  • In this case, it associates the image element (holds the help icon image open/close trigger) with the div help container element (holds the help content).
  • A relationship is created between each field image id attribute and value and its corresponding div help container id attribute and value.
  • Each of these id attributes and their values work together with the external fieldhelp.js file to produce the behavior of opening and closing the help.
Definitions to the highlighted code in the following code block:
<img id="subjecthelp"> The help icon image id attribute with its value of subjecthelp.
<div id="containersubjecthelp"> The div help container id attribute with its value of containersubjecthelp.
  • Note: Two empty code lines are placed between each field section in the code block for easier reading.
    <form action="#" method="post" id="enquiryform">
                <fieldset>
                    <legend>
                        Enquiry Form
                    </legend>
                    <h3 class="form" title="help instructions">Activate/Click a Help icon to open or close help.</h3>
                    <div>
                        <label for="subject" title="Subject dropdown list">
                            Subject <span class="req">(required)</span>
                            <img id="subjecthelp" alt="help for subject field" class="help" width="16" height="16" src="images/help_small.gif">
                        </label>
                    </div>
                    <div id="containersubjecthelp">
                        <p class="cshelp">
                            Please select a subject in the dropdown list.
                        </p>
                    </div>
                    <div>
                        <select name="subject" id="subject">
                            <option value="">Select a Subject</option>
                            <option value="Option 1">Help Authoring Tools</option>
                            <option value="Option 2">Microsoft HTML Help</option>
                            <option value="Option 3">Web-based Help</option>
                            <option value="Option 4">Context-Sensitive Help</option>
                        </select>
                    </div>
                    <div>
                        <label for="name" title="Name field">
                            Name <span class="req">(required)</span>
                            <img id="namehelp" alt="help for name field" class="help" width="16" height="16" src="images/help_small.gif">
                        </label>
                    </div>
                    <div id="containernamehelp">
                        <p class="cshelp">
                            Please enter your full name in the textbox.
                        </p>
                    </div>
                    <div>
                        <input type="text" name="name" id="name">
                    </div>
                    <div>
                        <label for="email" title="Email field">
                            Email <span class="req">(required)</span>
                            <img id="emailhelp" alt="help for email field" class="help" width="16" height="16" src="images/help_small.gif">
                        </label>
                    </div>
                    <div id="containeremailhelp">
                        <p class="cshelp">
                            Please enter your email address in the textbox.
                        </p>
                    </div>
                    <div>
                        <input type="text" name="email" id="email">
                    </div>
                    <div>
                        <label for="message" title="Message field.">
                            Message <span class="req">(required)</span>
                            <img id="messagehelp" alt="help for message field" class="help" width="16" height="16" src="images/help_small.gif">
                        </label>
                    </div>
                    <div id="containermessagehelp">
                        <p class="cshelp">
                            Please enter your message in the textbox.
                        </p>
                    </div>
                    <div>
                        <textarea name="message" id="message" rows="6" cols="30">
                        </textarea>
                    </div>
                    <div>
                        <label for="update" title="Receive updates checkbox">
                            Send Me Updates <span class="req">(optional)</span>
                            <img id="updateshelp" alt="help for updates checkbox" class="help" width="16" height="16" src="images/help_small.gif">
                        </label>
                    </div>
                    <div id="containerupdateshelp">
                        <p class="cshelp">
                            Check the box if you want to receive updates.
                        </p>
                    </div>
                    <div>
                        <input class="checkbox" type="checkbox" name="update" id="update" value="n">
                    </div>
                    <label for="submit" title="Click to submit your data.">
                        <input class="submit" type="submit" id="submit" value="Submit Enquiry">
                    </label>
                </fieldset>
            </form>

      Field Help Unobtrusive DOM/JavaScript Code

      Linking to the external DOM/JavaScript file

      • The link to the source (src) external DOM/JavaScript file (fieldhelp.js) is applied in the <head></head> section of the Field Help Method web page shown below.
      • Notice that this is a relative link to the scripts folder where the fieldhelp.js file is kept.
      • Important Note: All files must always be kept within the main project folder.
        <head>
        	<script type="text/javascript" src="scripts/fieldhelp.js"></script>
        </head>
        

          The DOM/JavaScript Code

          Use this Unobtrusive DOM/JavaScript to initiate Context-Sensitive Field Help.

          Below is the external DOM/JavaScript code which opens and closes the Context-Sensitive help text below each field name when triggered by a user activating a field help icon.

          • The code contains three functions:
            1. function addLoadEvent(func) This function enables more than one script associated to the web page to load and perform as intended.
            2. function init() This function sets the initial display of the help container to none, and then establishes a relationship beween a field image id and a div help container id.
            3. function openClose(objElement) This function provides the toggle switch to open the help, and then close it again.
          • After the Field Help Method web page loads, the DOM/JavaScript orders the browser to hide all Context-Sensitive help with the objHelp.style.display = 'none' instruction.
          • When a user clicks or activates a field help icon, the objHelp.style.display = 'none' changes to objHelp.style.display = 'block'.
          • This opens the Context-Sensitive help section beneath a field name.
            /* start addLoadEvent(func) function - allows scripts to load/register gracefully - design by Simon Willison */
            function addLoadEvent(func)
            {
            var oldonload = window.onload;

            if (typeof window.onload != 'function')
            {
            window.onload = func;

            }
            else
            {
            window.onload = function()
            {
            if (oldonload)
            {
            oldonload();
            }

            func();
            }
            }
            }

            addLoadEvent(init);

            addLoadEvent(function()
            {

            /* add more code here to run on page load */

            addLoadEvent(openClose(objElement));

            });

            /* end multiple script load function */

            /* start init function - design by Gez Lemon */
            function init()
            {
            var objImage = document.getElementsByTagName('img');

            var objHelp, objAnchor, objClone;

            for (var iCounter = 0; iCounter < objImage.length; iCounter++)
            {
            if (objImage[iCounter].className == 'help')
            {
            objHelp = document.getElementById('container' + objImage[iCounter].id);

            objAnchor = document.createElement('a');

            objClone = objImage[iCounter].cloneNode(true);

            objAnchor.setAttribute('href', '#');

            objAnchor.onclick = function()
            {
            return openClose(this);
            };

            objAnchor.appendChild(objClone);

            objHelp.style.display = 'none';

            objImage[iCounter].parentNode.replaceChild(objAnchor, objImage[iCounter]);
            }
            }
            }
            /* end function init() */

            /* start openClose(objElement) function - design by Gez Lemon */
            function openClose(objElement)
            {
            var objHelp = document.getElementById('container' + objElement.firstChild.id);

            if (objHelp)
            {
            if (objHelp.style.display == 'none')
            {
            objHelp.style.display = 'block';
            }
            else
            {
            objHelp.style.display = 'none';
            }
            }
            return false;
            }
            /* end function openClose(objElement) */

              Meeting the Objectives

              Follow these steps to test the Context-Sensitive field help in the following form (Opens in a new window/tab):

              1. Mouse activation:
                1. Click the Help icon next to a field label in the form to open the Context-Sensitive help.
                2. Click the same help icon again to close the field help.
              2. Keyboard activation:
                1. Press the TAB key to gain focus on a help icon.
                2. Press the ENTER key on your keyboard to open the Context-Sensitive help for that field.
                3. Press the ENTER key again to close the Context-Sensitive help for that field.
              3. Turn off scripting in your browser:
                1. Refresh the web page.
                2. Each field help section will be displayed below its label.
                3. Hyperlinks in the help icon images will be disabled.
              Topics:

              The best of DZone straight to your inbox.

              SEE AN EXAMPLE
              Please provide a valid email address.

              Thanks for subscribing!

              Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.
              Subscribe

              {{ parent.title || parent.header.title}}

              {{ parent.tldr }}

              {{ parent.urlSource.name }}