Over a million developers have joined DZone.

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

DZone's Guide to

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

· Web Dev Zone ·
Free Resource

Jumpstart your Angular applications with Indigo.Design, a unified platform for visual design, UX prototyping, code generation, and app development.

This article was contributed by my good friend, accessible designer, Technical Writer with Opera Software ASA, and co-founder of The South African Web Standards and Accessibility Group, Frank Palinkas. This is part two of a two part series that explores a new accessible way of providing context sensitive help to both form fields and a complete form (If you missed part 1 you can read it here.).

Employing the Form Help Method

Calling traditional Context-Sensitive help popup windows

This method has been implemented throughout web-based application history.

  • A hyperlink from the web form (a help icon or other means) is made to an external help topic or file which details instructions to complete each field in the form.
  • The Context-Sensitive help is called by JavaScript, which produces a secondary window containing the help within the web form page.
  • This action or behavior is commonly known as "invoking a popup window".

The advent of web standards and web accessibility has highlighed the difficulties assistive devices (i.e., screen readers, etc.) encounter when dealing with popup windows.

  • This new interest has given rise to what is known as Unobtrusive DOM/JavaScript and its employment in cases such as Context-Sensitive help popup windows.
  • The Form Help Method shows how to implement Unobtrusive DOM/JavaScript to call an external Context-Sensitive help popup window from a web form in a standards-based and accessible manner.

Form Help Method

How it Works

A user clicks on or activates the help icon link in the web form.

  1. The DOM/JavaScript instructs the browser to open the external Context-Sensitive help file.
  2. The browser follows the link to the external Context-Sensitive help file and opens it in a new window in the current web page.

What makes using Unobtrusive DOM/JavaScript "good practice" according to current web standards and accessibility practices?

  • In the markup, we replace the onclick event handler attribute with the rel attribute.
  • In doing so:
    • The rel attribute now serves the same purpose and delivers the same result as the replaced onclick event handler attribute.
    • We have separated the Behavior layer (DOM/JavaScript) from the Structure layer (markup and content) of the web page.
    • When scripting is turned off in the browser and the help icon is activated by a user, the external Context-Sensitive help file will open in a new, full-sized browser window.

Below is a screen shot of that we are working towards:

[img_assist|nid=2178|title=Screenshot of the final form|desc=|link=none|align=none|width=450|height=450]

Activating the Context-Sensitive Form Help

Important! Inform the user that clicking the help icon will open help in a new window.

Following good practice, the user should know what is going to happen before performing an action.

  1. Mouse activation:
    • Click the Help icon help icon in the form to call the Context-Sensitive help.
    • Click the [ X ] in the Help window title bar to close it.
  2. Keyboard activation:
    • Press the TAB key to gain focus on the Help icon help icon.
    • Press the ENTER key to open the help.
    • Press the ALT + F4 keys together to close the help window.
  3. Turn off scripting in your browser, refresh the web page, and then activate/click the same help icon again.
    • The Context-Sensitive help will now open in a new full sized window, covering up this web page.

HTML Markup Code for the Form Help Method

The Context-Sensitive help markup starts on code line 5 and ends on code line 7 in the code block.

  • Below is a HTML code block (gray colored area) containing all of the markup needed to construct the form.
  • An external cascading style sheet (master.css) positions the Context-Sensitive help icon on the right side of the <h3> element instruction text for quick association and access to it.
  • For your editing and reference purposes, this external CSS style sheet is contained within the main project folder along with the rest of the working parts of this tutorial.

Definitions of the code in the code block:

  • <a></a> This is the anchor (link) element which contains the following attributes and their values:
  • rel="help" This markup attribute and its value act as the structural "hook" to the external DOM/JavaScript.
  • href="HelpExample.htm" This markup attribute and its value identify the hyperlink path to the external Context-Sensitive help web page.
  • <img - - - src="images/help_small.gif" This markup attribute and its value identify the source location of the external help icon image. 
<form action="" method="post" id="enquiryform">
<legend>Enquiry Form</legend>
<h3 title="help instructions">Click the icon to view help in a new window.<a rel="help" href="HelpExample.html"><img alt="helpicon" title="Click to view help in a new window." width="16" height="16" src="../media/icons/help_small.gif"></a></h3>
<label for="subject" title="Subject dropdown list.">
Subject <span class="req">Required</span>
<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>
<label for="name" title="Name field">
Name <span class="req">Required</span>
<input type="text" name="name" id="name">
<label for="email" title="Email field">
Email <span class="req">Required</span>
<input type="text" name="email" id="email">
<label for="message" title="Message field">
Message <span class="req">Required</span>
<textarea name="message" id="message" rows="6" cols="30"></textarea>
<label for="updates" title="Updates checkbox">
Send Me Updates <span class="req">Optional</span>
<input type="checkbox" name="updates" id="updates" value="n">
<label for="submit" title="Click this button to submit your enquiry.">
<input class="submit" type="submit" id="submit" value="Submit Enquiry">

Form Help Unobtrusive DOM/JavaScript Code

Linking to the external DOM/JavaScript file

Put a link to the external Unobtrusive DOM/JavaScript file in the <head></head> section of the web page.

Definitions of the markup:

  • <head></head> This markup element contains the <script></script> element that holds the relative path to the external DOM/JavaScript file.
  • src="scripts/formhelp.js" This markup attribute of the <script></script> element contains the relative path to the external source (src) location of the DOM/JavaScript file.

Important Note: All files must always be kept within the main project folder to maintain their associations as written in the code.

<script type="text/javascript" src="../js/formhelp.js"></script>

Employ this Unobtrusive DOM/JavaScript to initiate Context-Sensitive Form Help.

The external DOM/JavaScript code sets a hook to the rel attribute value of "help" in the <a></a> element with its href attribute to open the Context-Sensitive help web page (HelpExample.htm) within the Form Help Method web page.

The following code block contains three functions:

  • function addLoadEvent(func) This function enables more than one script to register and load in a web page.
  • function formhelp() This function sets the rel attribute as the hook to the anchor link which points to the external help file.
  • function popUp(winURL) This function provides the trigger to open the external help file in a new window.
  • This DOM/JavaScript code block is kept in a formhelp.js file in the scripts folder in the same project folder with the:
    • Form Help Method web page
    • Context-Sensitive help web page
    • images folder
    • CSS files
  • Notice the rel attribute with its value of "help" and its relationship to the anchor ("a") element href attribute which in the markup points to the external help file.
  • This is the hook that the DOM/JavaScript needs to follow and open a new window containing the Context-Sensitive help.
  • You can also set the:
    • width and height of the new Context-Sensitive help window;
    • add a status bar to it (highly recommended);
    • give the user the ability to resize the new Context-Sensitive help window if they choose to do so;
    • add scrollbars to it.
  • These additions to the function are shown in the window.open(winURL,"popup", ...), line 39 in the following code block.
  • If scripting is turned off in the browser the Context-Sensitive help page when activated, will gracefully open in a new, full sized window.

/* start multiple load function - design by Simon Willison */
function addLoadEvent(func)
var oldonload = window.onload;

if (typeof window.onload != 'function')
window.onload = func;
window.onload = function()
if (oldonload)
/* add more code here to run on page load if necessary */
/* end multiple load function */

/* start window.onload = function() */
window.onload = function()
if (!document.getElementsByTagName) return false;

var lnks = document.getElementsByTagName("a");

for (var i = 0; i < lnks.length; i++)
if (lnks[i].getAttribute("rel") == "help")
lnks[i].onclick = function()
return false;
/* end formhelp() function */

/* start popUp(winURL) function */
function popUp(winURL){
window.open(winURL, "popup", "width=460,height=680,status=yes,resizable=yes,scrollbars=yes,screenX=600,screenY=200,top=200,left=600");

/* end popUp(winURL) function */

Click here to see the working form in action. So, if you have followed the series and read part 1 and now part 2, you will have discovered how Unobtrusive DOM/JavaScript achieves the desired result in calling Context-Sensitive help, and demonstrate how to keep the Structure, Presentation, and Behavior layers of a web page completely separate from one another ensuring good practice with current web standards and accessibility rules. So go ahead, make it part of your developer toolbox today!

I sincerely thank

Frank Palinkas

Technical Writer with Opera Software ASA
Websites: http://frank.helpware.net/

Frank sincerely thanks (in alphabetical order)

Char James-Tanny

President of JTF Associates, Owner of helpstuff.com, Secretary of the Society for Technical Communication (S.T.C.)
http://www.helpstuff.com HAT-Matrix.com

Dana Worley

Manager - Applications Engineer, Campbell Scientific Inc.

Dave Gash

Owner of HyperTrain dot Com. Author, Lecturer and Programmer of Technical Communications and Web Standards, encompassing (X)HTML, XML, XSLT, C.S.S., and D.O.M./JavaScript

Gez Lemon

Principal Accessibility Engineer and Project Leader - The Paciello Group (T.P.G.)

Mike Paciello

Creator/Owner of Helpware.net, Helpware FAR HTML, and H2Reg



Take a look at an Indigo.Design sample application to learn more about how apps are created with design to code software.


Opinions expressed by DZone contributors are their own.

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

{{ parent.tldr }}

{{ parent.urlSource.name }}