View source for Using aria-labelledby for link purpose

[[Category: Techniques]]
[[Category: ARIA Techniques]]
[[Category: Techniques Accepted]]
[[Category: Ready for XML]]


== Status ==

* [https://www.w3.org/2002/09/wbs/35422/html-techs-28-June-2012/results#x2596 Surveyed 2 July 2012]
* [http://www.w3.org/2012/07/02-html-techs-tf-minutes Discussed 2 July 2012]
* [https://www.w3.org/2002/09/wbs/35422/20130110aria/ Surveyed by WG 10 Jan 2013], returned to TF
* 21 June 2013: Comments in [https://www.w3.org/2002/09/wbs/35422/20130110aria/ Survey by WG 10 Jan 2013] implemented (description and test)
* David [http://davidmacd.com/test/labelledby-on-a-link.html tested] on Aug 25, 2013... Example 2 and 3 are not sufficiently supported. (see next section)
* Added to XML by AWK 2013/1/2

== Applicability ==

WAI-ARIA, HTML5

This technique applies to:
* [http://www.w3.org/TR/UNDERSTANDING-WCAG20/navigation-mechanisms-refs.html Success Criterion 2.4.4 (Link Purpose(In Context))]

== User agent and assistive technology support notes [To be published separately] ==

Please see user agent ARIA support:
[http://www.w3.org/TR/WCAG20-TECHS/wai-aria_notes.html#wai-aria_ua_support]

===Testing as of July 2012===
Using VoiceOver 3 with Safari 5.1.3. On focus the link text 'Read more' was announced first with the referenced <code>aria-labelledby</code> content announced second.

===Screen reader testing as of 22 October 2012===
* '''Not''' supported: 
** Win 7, IE 9, JAWS 13
** Win 7, FF 13, NVDA 2012.2.1
** Win XP, FF 15.0, NVDA 2011.3
** Win XP, IE 8, SaToGo
* '''Partial''' support (both link text and element referenced by aria-labeledby are read):
** Win 7, IE9, NVDA 2012.2.1 (but '''Example 2 not supported''')
** Win XP, IE 8, NVDA 2011.3 (but '''Example 2 not supported''')
* '''Supported''': 
** Win 7, FF 13, JAWS 13 (but '''Example 2 has only partial/buggy support''': "Sales report 2012" is read twice)
** Mac OS 10.5.8, VoiceOver

[http://3needs.org/en/testing/code/aria-labelledby-for-link-purpose.html See full testing results for Example 1]

[http://3needs.org/en/testing/code/aria-labelledby-filetype.html See full testing results for Example 2]

David [http://davidmacd.com/test/labelledby-on-a-link.html tested] on Aug 25, 2013... Example 2 and 3 are still not sufficiently supported. 
**Example 1 ok on JAWS, VoiceOver. NVDA ignores labelledby on an anchor 
**Example 2: JAWS 14 in FF, IE 10 read the entire paragraph for each link which is confusing and chatty. VoiceOver for Mountain Lion in Safari 6 same as JAWS. NVDA ignores labelledby on an anchor (unsuccessful implementation)
**Example 3: JAWS 14 in FF, IE 10 read the entire paragraph for each link which is confusing and chatty, VoiceOver for Mountain Lion in Safari 6 OK.  NVDA ignores labelledby on an anchor (unsuccessful implementation)

== Description ==
With the <code>aria-labelledby</code> attribute, authors can use a visible text element on the page as a label for a focusable element (a form control or a link). For example, a "read more..." link could be associated with the text of the heading of the preceding section to make the purpose of the link unambiguous (see example 1).
 
When associating text to a focusable element with the help of <code>aria-labelledby</code>, the target text element is given an ID which is referenced in the value of the <code>aria-labelledby</code> attribute of the focusable element. 

It is also possible to use several text elements on the page as a label for a focusable element. Each of the text elements used must be given a unique ID which is referenced as a string of IDs (<code>IDREF</code>) in the value of the <code>aria-labelledby</code> attribute. The label text should then be concatenated following the order of IDs in the value of the <code>aria-labelledby</code> attribute.

When applied on links, <code>aria-labelledby</code> can be used to identify the purpose of a link that may be readily apparent for sighted users, but less obvious for screen reader users. 

The specified behavior of <code>aria-labelledby</code> is that the associated label text is announced <strong>instead</strong> of the link text (not in addition to the link text). When the link text itself should be included in the label text, the ID of the link should be referenced as well in the string of IDs forming the value of the <code>aria-labelledby</code> attribute.

For more information on the naming hierarchy please consult the [http://www.w3.org/TR/wai-aria/roles#textalternativecomputation ARIA specification] and the [http://www.w3.org/TR/html-aapi/#accessible-name-and-description-calculation accessible name and description calculation] in the HTML to Platform Accessibility APIs Implementation Guide.

== Examples ==
=== Example 1 ===
This example should replace the "read more" link text at the end of the teaser text with the content of the <code>h2</code> heading referenced by <code>aria-labelledby</code>.

<pre>
<h2 id="headline">Storms hit east coast</h2>

<p>Torrential rain and gale force winds have struck the east coast, causing flooding in many coastal towns.
   <a href="news.html" aria-labelledby="headline">Read more...</a></p>
</pre>

=== Example 2 ===
The following example concatenates a link name through <code>aria-labelledby</code> referencing both the report title, "2012 Sales Report", and the respective file type, (PDF, Word, or Powerpoint).

<pre>
<p id="report-title">Download 2012 Sales Report:
<a aria-labelledby="report-title pdf" href="#" id="pdf">PDF</a> |
<a aria-labelledby="report-title doc" href="#" id="doc">Word</a> |
<a aria-labelledby="report-title ppt" href="#" id="ppt">Powerpoint</a></p>
</pre>

=== Example 3 ===
There may be cases where an author will placed a <span> tag  around a section of code that will be referenced. 

''Note:'' The use of <code>tabindex="-1"</code> on the <code>span</code> element is not meant to support focusing by scripts - here, it merely serves to ensure that some browsers (IE9, IE10) will include the <code>span</code> element in the accessibility tree, thus making it available for reference by <code>aria-labelledby</code>. For more details see [http://msdn.microsoft.com/en-us/library/ie/gg701963%28v=vs.85%29.aspx#Accessible_HTML_Elements Accessible HTML Elements]
<pre>
<p>Download <span id="report-title" tabindex="-1">2012 Sales Report</span>:
<a aria-labelledby="report-title pdf" href="#" id="pdf">PDF</a> |
<a aria-labelledby="report-title doc" href="#" id="doc">Word</a> |
<a aria-labelledby="report-title ppt" href="#" id="ppt">Powerpoint</a></p>
</pre>

== Resources ==
* [http://www.w3.org/TR/html-aapi/#accessible-name-and-description-calculation HTML to Platform Accessibility APIs Implementation Guide: Accessible Name and Description Calculation]

== Tests ==

For each link that has an <code>aria-labelledby</code> attribute:

# Check that each ID in the value of the <code>aria-labelledby</code> attribute matches an ID of a text element used as part of the link purpose.

=== Expected results ===

Test #1 is true for the ID (or each of the IDs) referenced by <code>aria-labelledby</code>.