JavaScript: Colorbox

Dialog boxes, like these colorboxes, are pretty common. Using jQuery, as we do, it's very easy to show or hide an element that is then overlaid on the page. In most cases, however, it’s an accessibility disaster. 


Accessibility Concerns

(Much of the following comes from Nicholas Zakas's article on making an accessible dialog box Exit.)

When you create a overlaid dialog, the input focus isn't handled correctly, and screen readers aren't able to tell that something is changed. However, it's not difficult to make a dialog fully accessible. You do need to understand the importance of a few lines of code.

ARIA roles

If you want screen reader users to be aware that a dialog has popped up, then you’ll need to learn about Accessible Rich Internet Applications (ARIA) roles. These "roles" add additional meaning to HTML elements allowing browsers to communicate better with screen readers. There are a large number of roles that alter the way screen readers perceive different elements on the page. When it comes to dialogs, there are two of interest: dialog and alertdialog.

In most cases, dialog is the role to use. By setting this as the value of the role attribute on an element, you are informing the browser that the purpose of the element is as a dialog box.

<div id="my-dialog" role="dialog">
    <-- Your dialog code here -->
</div>

When an element with a role of dialog is made visible, the browser tells the screen reader that a dialog is present.

Dialogs should also have labels. You can specify a label using either the aria-label attribute to indicate the label text or the aria-labelledby attribute to indicate the ID of the element that contains the label. Here are a couple of examples:

<div id="my-dialog" role="dialog" aria-label="New Message">
    <-- Your dialog code here -->
</div>

<div id="my-dialog" role="dialog" aria-labelledby="dialog-title">
    <h3 id="dialog-title">New Message</h3>
    <-- Your dialog code here -->
</div>

In the first example, the aria-label attribute is used to specify a label that is only used by screen readers. You would want to do this when there is no visual label for the dialog. In the second example, the aria-labelledby attribute is used to specify the ID of the element containing the dialog label. Since the dialog has a visual label, it makes sense to reuse that information rather than duplicate it. Screen readers announce the dialog label when the dialog is displayed.

The role of alertdialog is a specialized type of dialog that is designed to get a user's attention. Think of this as a confirmation dialog when you try to delete something. An alertdialog has very little interactivity. It's primary purpose is to get the user’s attention so that an action is performed. Compare that to a dialog, which may be an area for the user to enter information, such as writing a new e-mail or instant message.

When an alertdialog is displayed, screen readers look for a description to read. It's recommended to use the aria-describedby element to specify which text should be read. Similar to aria-labelledby, this attribute is the ID of an element containing the content to read. If aria-describedby is omitted, then the screen reader will attempt to figure out which text represents the description and will often choose the first piece of text content in the element. Here's an example:

<div id="my-dialog" role="alertdialog" aria-describedby="dialog-desc">
    <p id="dialog-desc">Are you sure you want to delete this message?</p>
    <-- Your dialog code here -->
</div>

This example uses an element to contain the description. Doing so ensures that the correct text will be read when the dialog is displayed.

Even if you omit the extra attributes and just use role for your dialogs, your page accessibility improves tremendously.

Setting focus to the dialog

The next part of creating an accessible dialog is managing focus. When a dialog is displayed, the focus should be placed inside of the dialog so users can continue to navigate with the keyboard. Exactly where inside the dialogue focus is set depends largely on the purpose of the dialogue itself. If you have a confirmation dialog with one button to continue in one button to cancel then you may want the default focus to be on the cancel button. If you have a dialog where the user is supposed to enter text, then you may want the focus to be on the text box by default. If you can’t figure out where to set focus, then a good starting point is to set focus to the element representing the dialog.

In this case, the jQuery plugin we're using, Colorbox Exit, works well. It will handle the focus for you and allows for keyboard navigation inside the dialog. If you're using an alternate plugin, you need to ensure it's setting the proper focus.

Top of Page


Colorbox Examples

Inline Content

To see an example of a "popup" Colorbox, click the first link below.

Basics of the New Law (from the CFLs home page).

New Light Bulb Law (Energy Independence and Security Act of 2007) - The Basics

The law:

  • does not ban the use or purchase of incandescent bulbs.
  • does not ban the sale or manufacture of ALL incandescent bulbs, just those common household incandescent (and other) bulbs that are not energy-efficient.
  • does not require the use of compact fluorescent bulbs.
  • requires about 25 percent greater efficiency (that is, less energy use) for household light bulbs that have traditionally used between 40 and 100 watts of electricity.
  • exempts many bulbs, including specialty bulbs, three-way bulbs, chandelier bulbs, refrigerator bulbs, plant grow lights and others.
  • was passed by Congress and signed by President Bush in 2007 and is implemented by the U.S. Department of Energy.
  • includes many other provisions that do not pertain to lighting. Some of these provisions call for: higher gas mileage in automobiles; transportation electrification; increased reliance on biofuels; and training for green jobs.

How-to: HTML

You will need to be comfortable with source view.

First, create your link, and give it a class of colorbox-inline. Point the href to the element you want to display when this link is clicked.

<a class="colorbox-inline" href="#colorbox-hidden">Basics of the New Law</a>

Then create the content you want "hidden" and displayed only when the link is clicked. Wrap this content in two <div>s, like so:

<div id="hidden-content" role="dialog" aria-labelledby="dialog-title">
  <div class="colorbox-hidden" id="colorbox-hidden">
    <h3 id="dialog-title">New Message</h3>
    <-- Your dialog code here -->
  </div>
</div>

How-to: JavaScript

<script>
 jQuery(document).ready(function() {
  // Hide the inline content
  jQuery("#hidden-content").css({'display':'none'});
  // Open inlined content in "box"
  jQuery(".colorbox-inline").colorbox({inline:true,width:"50%"});
 });
</script>

You can, of course, fiddle with the parameters for the colorbox itself, making it wider or narrower.

Top of Page


Image Gallery

Warning: linking to the original image inserts a direct link to the original file. It is not a managed file, handled by the database, and links to the original file may break over time.

Here's how you might create an image gallery with the thumbnails linking to the full-size image.

How-to: HTML

You will need to be comfortable with source view. Follow the instructions for making a gallery of images. As you upload each image, don't forget to check the box to "link to the original image."

Once you've got your column of images, then add the following, class="colorbox-gallery" role="dialog" to each link, like so:

<a class="colorbox-gallery" role="dialog" href="/sites/production/files/blue_heron-th.jpg" title="Blue Heron">[ [  {"type":"media","view_mode":"media_small","fid":"209","attributes":{"alt":"","class":"media-image","height":"160","width":"160"}} ] ]</a>

Note that the img is not present while you're in code view: your image is actually a managed Media file, and all of that "funny-looking" text will be processed by Drupal WebCMS before publishing the page (note, spacing around the is added for clarity).

How-to: JavaScript

Note that the target for the jQuery code is the same as the class you added to the link above.

<script src="/sites/all/libraries/colorbox/colorbox/jquery.colorbox-min.js"></script>
<script>
jQuery(document).ready(function() {
  // Colorbox gallery
  jQuery('.colorbox-gallery').colorbox({rel:'colorbox-gallery'});
});
</script>

Top of Page


YouTube Video

Here's how you might link to a YouTube video. Here's EPA's SmartWay: Anyway you ship it video.

Note that you'll want to link to the "embed" version of the video. See the following image for tips.

After clicking "Share" and then "Embed," grab the URL from the code snippet. You'll also want to check the "Use HTTPS" and "Enable privacy-enhanced mode" boxs and uncheck the "Show suggested videos when the video finishes" box.

How-to: HTML

My link looks like this: <a class="colorbox-youtube" href="https://www.youtube-nocookie.com/embed/yvrAJ5tq7Fc?rel=0" role="dialog">EPA's SmartWay: Anyway you ship it video</a>.

How-to: JavaScript

Note that the target for the jQuery code is the same as the class you added to the link above. You can also fiddle with the height and width of the video colorbox.

<script src="/sites/all/libraries/colorbox/colorbox/jquery.colorbox-min.js"></script>
<script>
jQuery(document).ready(function() {
    // Colorbox YouTube content
  jQuery(".colorbox-youtube").colorbox({iframe:true, innerWidth:425, innerHeight:344});

}); </script>

Top of Page