Merge branch 't/9638'

CHANGES.md

@@ -11,6 +11,7 @@ Fixed Issues:
 * [#12140](http://dev.ckeditor.com/ticket/12140): Fixed: Double-clicking linked widgets opens two dialogs.
 * [#12132](http://dev.ckeditor.com/ticket/12132): Fixed: Image is inserted with `width` and `height` styles even when they are not allowed.
 * [#9317](http://dev.ckeditor.com/ticket/9317): [IE] Fixed: [`config.disableObjectResizing`](http://docs.ckeditor.com/#!/api/CKEDITOR.config-cfg-disableObjectResizing) does not work on IE. **Note**: We were not able to fix this issue on IE11+ because necessary events stopped working. See a [last resort workaround](http://dev.ckeditor.com/ticket/9317#comment:16) and make sure to [support our complaint](https://connect.microsoft.com/IE/feedback/details/742593/please-respect-execcommand-enableobjectresizing-in-contenteditable-elements).
+* [#9638](http://dev.ckeditor.com/ticket/9638): Added [`config.ariaEditorHelpLabel`](http://docs.ckeditor.com/#!/api/CKEDITOR.editor-event-ariaEditorHelpLabel) event, allowing to set/disable a11yhelp availability.
 
 ## CKEditor 4.4.2
 

core/editable.js

@@ -1164,14 +1164,17 @@
 				if ( ariaLabel )
 					editable.changeAttr( 'title', ariaLabel );
 
-				// Put the voice label in different spaces, depending on element mode, so
-				// the DOM element get auto detached on mode reload or editor destroy.
-				var ct = this.ui.space( this.elementMode == CKEDITOR.ELEMENT_MODE_INLINE ? 'top' : 'contents' );
-				if ( ct ) {
-					var ariaDescId = CKEDITOR.tools.getNextId(),
-						desc = CKEDITOR.dom.element.createFromHtml( '<span id="' + ariaDescId + '" class="cke_voice_label">' + this.lang.common.editorHelp + '</span>' );
-					ct.append( desc );
-					editable.changeAttr( 'aria-describedby', ariaDescId );
+				var helpLabel = editor.fire( 'ariaEditorHelpLabel', {} ).label;
+				if ( helpLabel ) {
+					// Put the voice label in different spaces, depending on element mode, so
+					// the DOM element get auto detached on mode reload or editor destroy.
+					var ct = this.ui.space( this.elementMode == CKEDITOR.ELEMENT_MODE_INLINE ? 'top' : 'contents' );
+					if ( ct ) {
+						var ariaDescId = CKEDITOR.tools.getNextId(),
+							desc = CKEDITOR.dom.element.createFromHtml( '<span id="' + ariaDescId + '" class="cke_voice_label">' + helpLabel + '</span>' );
+						ct.append( desc );
+						editable.changeAttr( 'aria-describedby', ariaDescId );
+					}
 				}
 			}
 		} );
@@ -2137,6 +2140,27 @@
  * @member CKEDITOR.config
  */
 
+/**
+ * Event fired by the editor in order to get accessibility help label.
+ * The event is responded by a component which provides accessibility
+ * help (i.e. `a11yhelp` plugin) hence editor is notified whether help is available.
+ *
+ * Providing info:
+ *
+ *		editor.on( 'ariaEditorHelpLabel', function( evt ) {
+ *				evt.data.label = editor.lang.common.editorHelp;
+ *		} );
+ *
+ * Getting label:
+ *
+ *		var helpLabel = editor.fire( 'ariaEditorHelpLabel', {} ).label;
+ *
+ * @since 4.4.3
+ * @event ariaEditorHelpLabel
+ * @param {String} label The label to be used.
+ * @member CKEDITOR.editor
+ */
+
 /**
  * @event focus
  * @todo

plugins/a11yhelp/plugin.js

@@ -40,6 +40,10 @@
 
 			editor.setKeystroke( CKEDITOR.ALT + 48 /*0*/, 'a11yHelp' );
 			CKEDITOR.dialog.add( commandName, this.path + 'dialogs/a11yhelp.js' );
+
+			editor.on( 'ariaEditorHelpLabel', function( evt ) {
+				evt.data.label = editor.lang.common.editorHelp;
+			} );
 		}
 	} );
 } )();

plugins/wysiwygarea/plugin.js

@@ -46,28 +46,31 @@
 					iframe.on( 'load', onLoad );
 
 				var frameLabel = editor.title,
-					frameDesc = editor.lang.common.editorHelp;
+					helpLabel = editor.fire( 'ariaEditorHelpLabel', {} ).label;
 
 				if ( frameLabel ) {
-					if ( CKEDITOR.env.ie )
-						frameLabel += ', ' + frameDesc;
+					if ( CKEDITOR.env.ie && helpLabel )
+						frameLabel += ', ' + helpLabel;
 
 					iframe.setAttribute( 'title', frameLabel );
 				}
 
-				var labelId = CKEDITOR.tools.getNextId(),
-					desc = CKEDITOR.dom.element.createFromHtml( '<span id="' + labelId + '" class="cke_voice_label">' + frameDesc + '</span>' );
+				if ( helpLabel ) {
+					var labelId = CKEDITOR.tools.getNextId(),
+						desc = CKEDITOR.dom.element.createFromHtml( '<span id="' + labelId + '" class="cke_voice_label">' + helpLabel + '</span>' );
 
-				contentSpace.append( desc, 1 );
+					contentSpace.append( desc, 1 );
+					iframe.setAttribute( 'aria-describedby', labelId );
+				}
 
 				// Remove the ARIA description.
 				editor.on( 'beforeModeUnload', function( evt ) {
 					evt.removeListener();
-					desc.remove();
+					if ( desc )
+						desc.remove();
 				} );
 
 				iframe.setAttributes( {
-					'aria-describedby': labelId,
 					tabIndex: editor.tabIndex,
 					allowTransparency: 'true'
 				} );

tests/core/editable/aria.js

@@ -0,0 +1,62 @@
+/* bender-tags: editor,unit */
+/* bender-ckeditor-plugins: toolbar */
+
+( function() {
+	'use strict';
+
+	bender.test( {
+		'test editor#ariaEditorHelpLabel event - handled': function() {
+			var fired = 0;
+
+			bender.editorBot.create( {
+				name: 'editor1',
+				creator: 'inline',
+				config: {
+					removePlugins: 'a11yhelp',
+					on: {
+						pluginsLoaded: function() {
+							this.on( 'ariaEditorHelpLabel', function( evt ) {
+								evt.data.label = 'foo';
+								fired += 1;
+							} );
+						}
+					}
+				}
+			}, function( bot ) {
+				var editor = bot.editor,
+					describedBy = editor.editable().getAttribute( 'aria-describedby' );
+
+				assert.areSame( 1, fired, 'event was fired once' );
+				assert.isNotNull( describedBy, 'editable has aria-describedby attribute' );
+				var label = editor.ui.space( 'top' ).findOne( '#' + describedBy );
+				assert.isNotNull( label, 'label element exists within top space' );
+				assert.areSame( 'foo', label.getHtml(), 'label\'s content' );
+			} );
+		},
+
+		'test editor#ariaEditorHelpLabel event - unhandled': function() {
+			var fired = 0;
+
+			bender.editorBot.create( {
+				name: 'editor2',
+				creator: 'inline',
+				config: {
+					removePlugins: 'a11yhelp',
+					on: {
+						pluginsLoaded: function() {
+							this.on( 'ariaEditorHelpLabel', function( evt ) {
+								fired += 1;
+							} );
+						}
+					}
+				}
+			}, function( bot ) {
+				var editor = bot.editor,
+					describedBy = editor.editable().getAttribute( 'aria-describedby' );
+
+				assert.areSame( 1, fired, 'event was fired once' );
+				assert.isNull( describedBy, 'editable does not have has aria-describedby attribute' );
+			} );
+		}
+	} );
+} )();

tests/plugins/a11yhelp/editorhelp.js

@@ -0,0 +1,50 @@
+/* bender-tags: editor,unit,a11yhelp */
+/* bender-ckeditor-plugins: toolbar */
+
+( function() {
+	'use strict';
+
+	bender.test( {
+		'async:init': function() {
+			var that = this;
+
+			bender.tools.setUpEditors( {
+				withA11y: {
+					name: 'editor1',
+					creator: 'inline',
+					config: {
+						extraPlugins: 'a11yhelp'
+					}
+				},
+				withoutA11y: {
+					name: 'editor2',
+					creator: 'inline',
+					config: {
+						removePlugins: 'a11yhelp'
+					}
+				}
+			}, function( editors, bots ) {
+				that.editorBots = bots;
+				that.editors = editors;
+				that.callback();
+			} );
+		},
+
+		'test editor with a11y plugin has aria-describedby': function() {
+			var editor = this.editors.withA11y,
+				describedBy = editor.editable().getAttribute( 'aria-describedby' );
+
+			assert.isNotNull( describedBy, 'editable has aria-describedby attribute' );
+			var label = CKEDITOR.document.getById( describedBy );
+			assert.isNotNull( label, 'label element exists' );
+			assert.areSame( editor.lang.common.editorHelp, label.getHtml(), 'label\'s content' );
+		},
+
+		'test editor without a11y plugin has aria-describedby': function() {
+			var editor = this.editors.withoutA11y,
+				describedBy = editor.editable().getAttribute( 'aria-describedby' );
+
+			assert.isNull( describedBy, 'editable does not have aria-describedby attribute' );
+		}
+	} );
+} )();

tests/plugins/wysiwygarea/aria.js

@@ -0,0 +1,63 @@
+/* bender-tags: editor,unit */
+/* bender-ckeditor-plugins: toolbar */
+
+( function() {
+	'use strict';
+
+	bender.test( {
+		'test editor#ariaEditorHelpLabel event - handled': function() {
+			var fired = 0;
+
+			bender.editorBot.create( {
+				name: 'editor1',
+				config: {
+					removePlugins: 'a11yhelp',
+					on: {
+						pluginsLoaded: function() {
+							this.on( 'ariaEditorHelpLabel', function( evt ) {
+								evt.data.label = 'foo';
+								fired += 1;
+							} );
+						}
+					}
+				}
+			}, function( bot ) {
+				var editor = bot.editor,
+					iframe = editor.window.getFrame(),
+					describedBy = iframe.getAttribute( 'aria-describedby' );
+
+				assert.areSame( 1, fired, 'event was fired once' );
+				assert.isNotNull( describedBy, 'iframe has aria-describedby attribute' );
+				var label = editor.ui.space( 'contents' ).findOne( '#' + describedBy );
+				assert.isNotNull( label, 'label element exists within top space' );
+				assert.areSame( 'foo', label.getHtml(), 'label\'s content' );
+				if ( CKEDITOR.env.ie )
+					assert.areSame( editor.title + ', foo', iframe.getAttribute( 'title' ), 'on IE title contains label' );
+			} );
+		},
+
+		'test editor#ariaEditorHelpLabel event - not handled': function() {
+			var fired = 0;
+
+			bender.editorBot.create( {
+				name: 'editor2',
+				config: {
+					removePlugins: 'a11yhelp',
+					on: {
+						pluginsLoaded: function() {
+							this.on( 'ariaEditorHelpLabel', function( evt ) {
+								fired += 1;
+							} );
+						}
+					}
+				}
+			}, function( bot ) {
+				var editor = bot.editor,
+					describedBy = editor.window.getFrame().getAttribute( 'aria-describedby' );
+
+				assert.areSame( 1, fired, 'event was fired once' );
+				assert.isNull( describedBy, 'iframe does not have aria-describedby attribute' );
+			} );
+		}
+	} );
+} )();