Add extra accessibility labels to jump to citation (↑) links

Had to do that in JavaScript as doing it server-side would have
made refactoring large parts of the extension necessary.

Bug: 38141
Change-Id: I60ecd2fc0edf2aee89974d8069cc0b075cda3f93

Cite.i18n.php

@@ -73,6 +73,8 @@ no text was provided for refs named <code>$1</code>',
 	'cite_references_link_many_format_backlink_labels' => 'a b c d e f g h i j k l m n o p q r s t u v w x y z aa ab ac ad ae af ag ah ai aj ak al am an ao ap aq ar as at au av aw ax ay az ba bb bc bd be bf bg bh bi bj bk bl bm bn bo bp bq br bs bt bu bv bw bx by bz ca cb cc cd ce cf cg ch ci cj ck cl cm cn co cp cq cr cs ct cu cv cw cx cy cz da db dc dd de df dg dh di dj dk dl dm dn do dp dq dr ds dt du dv dw dx dy dz ea eb ec ed ee ef eg eh ei ej ek el em en eo ep eq er es et eu ev ew ex ey ez fa fb fc fd fe ff fg fh fi fj fk fl fm fn fo fp fq fr fs ft fu fv fw fx fy fz ga gb gc gd ge gf gg gh gi gj gk gl gm gn go gp gq gr gs gt gu gv gw gx gy gz ha hb hc hd he hf hg hh hi hj hk hl hm hn ho hp hq hr hs ht hu hv hw hx hy hz ia ib ic id ie if ig ih ii ij ik il im in io ip iq ir is it iu iv iw ix iy iz ja jb jc jd je jf jg jh ji jj jk jl jm jn jo jp jq jr js jt ju jv jw jx jy jz ka kb kc kd ke kf kg kh ki kj kk kl km kn ko kp kq kr ks kt ku kv kw kx ky kz la lb lc ld le lf lg lh li lj lk ll lm ln lo lp lq lr ls lt lu lv lw lx ly lz ma mb mc md me mf mg mh mi mj mk ml mm mn mo mp mq mr ms mt mu mv mw mx my mz na nb nc nd ne nf ng nh ni nj nk nl nm nn no np nq nr ns nt nu nv nw nx ny nz oa ob oc od oe of og oh oi oj ok ol om on oo op oq or os ot ou ov ow ox oy oz pa pb pc pd pe pf pg ph pi pj pk pl pm pn po pp pq pr ps pt pu pv pw px py pz qa qb qc qd qe qf qg qh qi qj qk ql qm qn qo qp qq qr qs qt qu qv qw qx qy qz ra rb rc rd re rf rg rh ri rj rk rl rm rn ro rp rq rr rs rt ru rv rw rx ry rz sa sb sc sd se sf sg sh si sj sk sl sm sn so sp sq sr ss st su sv sw sx sy sz ta tb tc td te tf tg th ti tj tk tl tm tn to tp tq tr ts tt tu tv tw tx ty tz ua ub uc ud ue uf ug uh ui uj uk ul um un uo up uq ur us ut uu uv uw ux uy uz va vb vc vd ve vf vg vh vi vj vk vl vm vn vo vp vq vr vs vt vu vv vw vx vy vz wa wb wc wd we wf wg wh wi wj wk wl wm wn wo wp wq wr ws wt wu wv ww wx wy wz xa xb xc xd xe xf xg xh xi xj xk xl xm xn xo xp xq xr xs xt xu xv xw xx xy xz ya yb yc yd ye yf yg yh yi yj yk yl ym yn yo yp yq yr ys yt yu yv yw yx yy yz za zb zc zd ze zf zg zh zi zj zk zl zm zn zo zp zq zr zs zt zu zv zw zx zy zz',
 	'cite_references_link_many_sep'                    => "&#32;",
 	'cite_references_link_many_and'                    => "&#32;",
+	'cite_references_link_accessibility_label'         => 'Jump up',
+	'cite_references_link_many_accessibility_label'    => 'Jump up to:',
 
 	# Although I could just use # instead of <li> above and nothing here that
 	# will break on input that contains linebreaks
@@ -205,6 +207,11 @@ Parameters:
 	'cite_references_link_many_format_backlink_labels' => '{{Optional}}',
 	'cite_references_link_many_sep' => '{{optional}}',
 	'cite_references_link_many_and' => '{{optional}}',
+	'cite_references_link_accessibility_label' => 'Text for screen readers to describe the jump to citation link ("↑").',
+	'cite_references_link_many_accessibility_label' =>
+'Text for screen readers to describe the jump to citation links (a b c ...) for citations which are used in multiple places.
+This is going to be prepended to the first link, the following ones will just be read by screen readers as they are visible.',
+
 	'cite_references_prefix' => '{{notranslate}}',
 	'cite_references_suffix' => '{{notranslate}}',
 );

Cite.php

@@ -24,7 +24,7 @@ $wgHooks['BeforePageDisplay'][] = 'wfCiteBeforePageDisplay';
 $wgExtensionCredits['parserhook'][] = array(
 	'path' => __FILE__,
 	'name' => 'Cite',
-	'author' => 'Ævar Arnfjörð Bjarmason',
+	'author' => array( 'Ævar Arnfjörð Bjarmason', 'Marius Hoch' ),
 	'descriptionmsg' => 'cite-desc',
 	'url' => 'https://www.mediawiki.org/wiki/Extension:Cite/Cite.php'
 );
@@ -70,6 +70,15 @@ $citeResourceTemplate = array(
 	'remoteExtPath' => 'Cite/modules'
 );
 
+$wgResourceModules['ext.cite'] = $citeResourceTemplate + array(
+	'scripts' => 'ext.cite.js',
+	'styles' => 'ext.cite.css',
+	'messages' => array(
+		'cite_references_link_accessibility_label',
+		'cite_references_link_many_accessibility_label',
+	),
+);
+
 $wgResourceModules['ext.cite.popups'] = $citeResourceTemplate + array(
 	'scripts' => 'ext.cite.popups.js',
 	'position' => 'bottom',
@@ -98,6 +107,7 @@ $wgResourceModules['ext.rtlcite'] = $citeResourceTemplate + array(
 function wfCiteBeforePageDisplay( $out, &$sk ) {
 	global $wgCiteEnablePopups;
 
+	$out->addModules( 'ext.cite' );
 	if ( $wgCiteEnablePopups ) {
 		$out->addModules( 'ext.cite.popups' );
 	}

modules/ext.cite.css

@@ -0,0 +1,13 @@
+/**
+ * Per http://developer.yahoo.com/blogs/ydn/clip-hidden-content-better-accessibility-53456.html
+ */
+.cite-accessibility-label {
+	position: absolute !important;
+	clip: rect(1px 1px 1px 1px); /* IE6, IE7 */
+	clip: rect(1px, 1px, 1px, 1px);
+	padding: 0 !important;
+	border: 0 !important;
+	height: 1px !important;
+	width: 1px !important;
+	overflow: hidden;
+}

modules/ext.cite.js

@@ -0,0 +1,38 @@
+/**
+ * Main JavaScript for the Cite extension. The main purpose of this file
+ * is to add accessibility attributes to the citation links as that can
+ * hardly be done server side (bug 38141).
+ *
+ * @author Marius Hoch <hoo@online.de>
+ */
+( function ( mw, $ ) {
+	'use strict';
+
+	mw.hook( 'wikipage.content' ).add( function ( $content ) {
+		var accessibilityLabelOne = mw.msg( 'cite_references_link_accessibility_label' ),
+			accessibilityLabelMany = mw.msg( 'cite_references_link_many_accessibility_label' );
+
+		$content.find( '.mw-cite-backlink' ).each( function () {
+			var $links = $( this ).find( 'a' ),
+				label;
+
+			if ( $links.length > 1 ) {
+				// This citation is used multiple times. Let's only set the accessibility label on the first link, the
+				// following ones should then be self-explaining. This is needed to make sure this isn't getting
+				// too wordy.
+				label = accessibilityLabelMany;
+			} else {
+				label = accessibilityLabelOne;
+			}
+
+			// We can't use aria-label over here as that's not supported consistently across all screen reader / browser
+			// combinations. We have to use visually hidden spans for the accessibility labels instead.
+			$links.eq( 0 ).prepend(
+				$( '<span>' )
+					.addClass( 'cite-accessibility-label' )
+					// Also make sure we have at least one space between the accessibility label and the visual one
+					.text( label + ' ' )
+			);
+		} );
+	} );
+} )( mediaWiki, jQuery );