Programmatically Determined

The phrase "programmatically determined" features prominently in six of the 61 WCAG 2.0 Success Criteria. It's a bit of a mouthful, for sure, and perhaps a little daunting to those getting into accessibility and WCAG for the first time, but it's really not that complicated. In fact, you may already have a handle on it, even if you're not familiar with the phrase itself.

Whatever the case, I think "programmatically determined" is a very useful concept for explaining, particularly to web developers, something about WCAG, what web accessibility means and why the proper use of HTML is so important.

It's in the HTML

Behind all your typical web page content is, of course, the HTML markup. When used properly, it serves to identify the semantic structure of, and the relationships between, different bits of that content.

Most people never see a web page's HTML, but the browser used to access a web page relies on it to understand the page's content. The HTML tells the browser things like

  • this bit of content is a paragraph and it falls under that 2nd-level heading,
  • this is the third item in an ordered list of five items,
  • this is a text input field and it has this name,
  • this is a link to that page on that web site,
  • this web page is in French, except for this sentence which is in English, etc.

Providing this information about content structure and relationships is a fundamental part of what HTML was designed to do and of how it is meant to be used in the first place.

We Call It "Programmatically Determined"

When content is properly marked up in HTML, its semantic structure and relationships are in the markup itself. That is, they can be programmatically determined. Because this information is in the code, as it were, supporting technologies can programmatically retrieve it and present it to users in different ways. The information can be transformed...into different sensory formats (e.g., visual, auditory) or styles of presentation needed by individual users. This is a key aspect of accessible web content and a core concept in WCAG 2.0.

Such information can then be passed along by the browser to whatever other device or software is able to make use of it. Screen readers, voice recognition software, alternative input devices, etc., can tell what each bit of content is and allow users to interact with them accordingly.

Relevant WCAG 2.0 Success Criteria

What follows is not a comprehensive review of WCAG 2.0 Success Criteria, but rather a general explanation of those six that use the concept "programmatically determined" and what it means for each of them in terms of web accessibility and HTML markup. For more detailed explanations of all the Success Criteria and related techniques, start with the Understanding WCAG 2.0 and Techniques for WCAG 2.0.

1.3.1 Info and Relationships

Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text. (Level A)

Understanding Success Criterion 1.3.1

Things are getting better all the time, but some web content is still being marked up according to how it is meant to look or behave on the screen as opposed to its semantic structure. Things like headings, paragraphs, lists, blockquotes, tables, and links get stuffed into semantically meaningless div and span elements and then styled or scripted in such a way that sighted users are able to interpret them as headings, paragraphs, links, etc. But in these cases, what each of these bits of content are and how they relate to each other cannot be programmatically determined because this information is not available from the markup.

Semantic HTML

Instead, the appropriate semantic elements and attributes should be used so that the content's structure and relationships are identified by the markup. Well-coded content can then be styled for visual presentation however one wishes by using the appropriate technology, i.e., CSS. This is what progressive enhancement and the separation of content or structure from presentation are all about.

Certainly, there will always be some content that doesn't fit easily into the admittedly limited semantics that HTML permits, but in most cases it is fairly straightforward. In any case, it's useful to familiarise oneself with the range of HTML elements and attributes that exist and how they are meant to be used. The following are some resources to help with that:

HTML5 Semantics

You'll also find it interesting and useful to learn about HTML5 and its new semantic elements such as header, footer, nav, section, article, and others:

WAI-ARIA Roles and Properties

Additionally, WAI-ARIA provides a collection of attributes and values that can be used to supplement content's programmatically determined semantics and relationships. For instance, landmark roles such as banner, navigation, main, and search can be applied to the appropriate elements to further identify their place and meaning in the document structure.

Associations between elements, particularly those not already provided by native HTML semantics, or those whose native semantics are not yet supported by assistive technologies, can be expressed using various WAI-ARIA relationship properties like aria-describedby and aria-labelledby.

1.3.2 Meaningful Sequence

When the sequence in which content is presented affects its meaning, a correct reading sequence can be programmatically determined. (Level A)

Understanding Success Criterion 1.3.2

Typical examples of where this Success Criterion apply are poorly constructed layout tables that don't linearise properly, and the use of CSS to present content in groups or columns that aren't also expressed in the markup. Similar to SC 1.3.1, the issue here has to do with providing in a visual way information that is necessary to understanding the content while not also making that same information available programmatically.

For more on the problem caused by improperly built layout tables and linearisation, see WebAIM's Creating Accessible Tables article. For an example of content that is presented as columns in the visual layer but not the structural layer, see F1: Failure of Success Criterion 1.3.2 from the W3C.

2.4.4 Link Purpose (In Context)

The purpose of each link can be determined from the link text alone or from the link text together with its programmatically determined link context, except where the purpose of the link would be ambiguous to users in general. (Level A)

Understanding Success Criterion 2.4.4

Personally, I think that in most cases a link's purpose or destination should be evident from the link text alone. However, this Level A Success Criterion requires only that the link's purpose can be known based on its programmatically determined context, for example, from the heading element that immediately precedes the link, or the text that is in the same paragraph, list, or table cell as the link or in a table header cell that is associated with the table cell that contains the link. Contrast this with Level AAA Success Criterion 2.4.9, which requires that the link's purpose be explicit from the link text alone, or through some mechanism that is either provided in the page itself or through supporting user agents or assistive technologies.

Example: "Read more" Links

Consider all those "Read more" links that one finds associated with excerpts and summaries from blog posts or articles. In most cases, the "Read more" link appears visually next to the excerpt's text and so the link's purpose or target is usually clear enough to sighted users.

For visually impaired users, on the other hand, determining the link's purpose means knowing or investigating its surrounding context and the text with which it is associated, that is, its "programmatically determined link context." Accordingly, the link's purpose can be considered accessible if, for example, it is immediately preceded by the post or article's title in a heading element, or if it is in the same paragraph as the excerpt itself. If the article's title is not provided as a heading and the "Read more" link is in its own separate paragraph, this would likely constitute a failure of this Success Criterion.

Something else to consider is that screen reader users are generally able to call up a list of all the links on a web page. Such a list would contain a number of "Read more" links that are all named the same and removed from their programmatically determined context, thus making it very difficult to know where each link goes.

This is why I prefer, where possible, to support SC 2.4.9 and include the title of the relevant post or article in the "Read more" link itself, thereby making the link's purpose explicit from the link text alone. I've written more extensively about how one can make this work in "Continue Reading" Links in WordPress.

3.1.1 Language of Page

The default human language of each Web page can be programmatically determined. (Level A)

Understanding Success Criterion 3.1.1

This Success Criterion is pretty straightforward. Basically, the content on every web page is written in a certain human language. Most pages probably only use a single language, but no matter how many different languages a page includes, a default language for the page needs to be chosen, and this language needs to be declared programmatically in the HTML.

Language Codes

First, you need to figure out the relevant language tag to use. You'll have to decide if you need only a primary language subtag to indicate the language, or if you also need to include a region subtag to specify a particular regional version of the language. The article Choosing a language tag will help you understand all this.

For example, the primary language subtag "en" indicates English. To specify British or American English, we would append the "GB" or "US" region subtags, respectively, i.e., "en-GB" and "en-US".

All primary language and region subtags are listed in the IANA language tag registry. There is also the handy Language Subtag Lookup tool.

Adding the Language Code to the Page

Once you've got your language tag, implementation is easy. For HTML 4.01 and HTML5, simply add the lang attribute, with your language tag as its value, to the html element:

<html lang="en-NZ">

For XHTML 1.0 or XHTML5:

<html xml:lang="en-NZ">

And for polyglot (HTML-compatible XHTML) documents:

<html lang="en-NZ" xml:lang="en-NZ">

With this code in place, supporting technologies can easily tell what the page's main language is. In the case of some screen readers, this can be very useful. If a screen reader supports multiple languages, and knows what language the page uses, it can read the page according to that language's pronunciation rules.

While working in Canada, it was not unusual to listen to French content being read as if it were English because the screen reader was set to read English by default and the web page did not identify that the page was in French. Had the screen reader been able to programmatically determine that the page was in French, it would not have pronounced the word "français", for instance, as "frankayce".

3.1.2 Language of Parts

The human language of each passage or phrase in the content can be programmatically determined except for proper names, technical terms, words of indeterminate language, and words or phrases that have become part of the vernacular of the immediately surrounding text. (Level AA)

Understanding Success Criterion 3.1.2

By default, all the content on a page is assumed to be in the language specified for the document as a whole by the lang attribute on the html element, as was noted with SC 3.1.1 above. Success Criterion 3.1.2 applies where some chunk of content, whether it is a word or a longer passage of text, is written in a language other than the document's primary language. In these cases, the change in language must be indicated programmatically in the same way by specifying the appropriate language code on the element containing the text in question.

If the text that is in a language other than the document's default language is entirely contained in its own element, the language code can be applied to that element itself. For example, on a Canadian government web page with a link to the same page in French, the text for that link would be "français", which is a French word. To programmatically identify it as such, we should expect to see something like the following markup:

<a href="" lang="fr">Français</a>

Where the text in another language is not self-contained in its own element, as might happen where a word or phrase in another language is part of a longer passage, it will be necessary to wrap the word or phrase in its own element and apply the appropriate lang attribute to that. In many cases, this will probably be something like a generic span element.

<p>Merry Christmas in Māori is <span lang="mi">Meri Kirihimete</span>.</p>

4.1.2 Name, Role, Value

For all user interface components (including but not limited to: form elements, links and components generated by scripts), the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to user agents, including assistive technologies. (Level A)

Note: This success criterion is primarily for Web authors who develop or script their own user interface components. For example, standard HTML controls already meet this success criterion when used according to specification.

Understanding Success Criterion 4.1.2

This Success Criterion has specifically to do with interactive elements on a page, and applies with special importance to custom interactive components and widgets that don't make use of native HTML control elements.

Forms and Links

When it comes to interactivity, the first things we tend to think of are forms and links. If we create such components using the built-in elements that HTML provides and in accordance with their specifications, we are pretty much assured that their names, roles, states, and values will be programmatically accessible. WCAG 2.0 Technique H91: Using HTML form controls and links provides a good number of examples illustrating how these can and should be implemented.

Custom Widgets and WAI-ARIA

But not all interactive components are forms and links. With the current state of browser technology and the greater demand for interactive websites, more and more scripted interfaces and widgets, e.g., drop-down menus, tree structures, tabbed panels, expandable/collapsible content areas, etc., are getting implemented in web pages. But there are generally no default HTML controls for these that natively provide name, role and state information. As such, implementing them in an accessible manner can require some additional work and makes this Success Criterion especially important.

Fortunately, WAI-ARIA was developed specifically to address many of these issues, and provides a bunch of widget roles and other widget attributes that go a long way to helping programmatically identify the purpose, state, and value of various custom interactive components. I won't provide any examples here since it is a large topic and many great resources already exist, some of which can be found through the links to WAI-ARIA resources that were listed above.

To Quickly Summarise...

Wherever possible, use the appropriate HTML elements and attributes for the job. Write your markup to so that it expresses the content's structure and relationships:

  • What kind of content is it?
  • What is its relationship to the content around it?
  • If it provides functionality, what does it do? Are its name, role, state, and value clear from the markup?

If answers to these questions are clearly indicated through the HTML and/or WAI-ARIA markup alone, it's a good bet that this same information can be programmatically determined by the browser as well as supporting assistive technologies and devices.

7 Responses to Programmatically Determined

  1. 1. Cliff Tyllick:

    Great post, Jason! In fact, I plan on linking our accessibility information on our intranet to this post.

    Why? Because, as useful as this phrase is, it is too often an impediment to the understanding of WCAG 2.0.

    To get the point across, I have often said, “The information must be in there in a way that lets software recognize it and retrieve it.”

    In other words, can MS Word tell whether to use its English dictionary or its Spanish dictionary to spell-check your document? If so, then JAWS or NVDA can tell which convention to apply to figure out how to pronounce each word.

    once is one syllable; once is two. When you code it that way, screen readers can tell the difference.

  2. 2. Jason:

    Thanks, Cliff.

    Of course, I totally agree. The phrase, while succinct, needs demystifying for a broader audience as the concept in itself is just so central to understanding how content becomes accessible through the different technologies people use.

  3. 3. Jared Smith:

    One quick comment that was brought up on Twitter regarding the Language of Parts example. It could be clarified that the lang attribute is added because the text of the link is in Māori and not because the page being linked to is in the Māori language. The hreflang attribute could/should also be used to designate that that linked page is in Māori (assuming it is), though this is not required by WCAG 2.0.

    I could also argue that the word “Māori” isn’t really Māori at all, but is a proper, universal name that probably doesn’t need lang defined. The word is “Māori” in English too. Similarly, you wouldn’t need to mark up “San Jose” on an English page as being Spanish, even if a screen reader reads it with a hard “J”. There are, however, some instances where if you didn’t identify the natural language of the proper noun that it might be pronounced so differently in the document language so as to be confusing. Perhaps (I’m just making this up) “Apple” in a French page would be read as “applay”, for example.

  4. 4. Jared Smith:

    There’s also an additional layer of common sense that needs to be applied to all of this. Just because something CAN be programmatically determined doesn’t mean it will be. I argued hard in WCAG 2.0 for “programmatically determinable” instead. It’s uglier, but more accurate because it indicates that it isn’t automatically accessible or useful just because there’s programmatic context.

    Even though a “read more” or “click here” link is in a paragraph with its context, this doesn’t do a lick of good for a screen reader user navigating by links (a screen reader doesn’t magically find the context and present it). The user must still hunt around for it, though this is arguably equally inaccessible to sighted users who must also visually scan the paragraph.

  5. 5. Jason:

    Thanks for the comments, Jared. And thanks to you and @TinaHolmboe for pointing out how the previous example of a link to page in the Māori language was rather unclear. Distinctions in pronunciation, if any, of the word Māori between English and Māori speakers aside, the example was not strong, so I’ve replaced it with one that I think is clearer using the word “français”.

    And you are, of course, right that the hreflang attribute should ideally be used on such a link. I had considered it, but wanted to keep the example fairly simple.

    Funny you should mention your preference for the phrase “programmatically determinable.” I prefer it, myself, but mainly because I think it is simply a shorter and cleaner of saying “can be programmatically determined,” which I take to mean the same thing and how the phrase is used in the WCAG 2.0 Success Criteria.

    Regarding your point about “read more” and “click here” links, I couldn’t agree more, hence my preference to meet SC 2.4.9 wherever possible, and explicitly identify the link’s purpose in the link text itself.

  6. 6. Cliff Tyllick:

    Jared, you’re right about the prudent use of the lang attribute. For example, very few people would recognize Los Angeles as the city on or San Antonio as the city in Texas. (I hope I entered that right — I’m trying to get the coding for the language to display as code. I failed the first time, with once, which is pronounced own’-seh in Spanish, meaning “eleven,” and wunse in English, meaning “one time.”)

    On the other hand, even though the city is in California I definitely would code La Jolla (la hoy’-a) as Spanish, because a pronunciation according to English rules would not be recognizable to anyone.

  7. 7. Cliff Tyllick:

    Wow, I messed that up royally! Let me try again: <lang=”es”>Los Angeles</lang> makes no sense if you’re referring to the city in California, but <lang=”es”>La Jolla</lang> makes perfect sense, even if the page is otherwise in English.

    And if that doesn’t work, I give up!

Comments are now closed.