Themes: Improve a11y and extendability of custom video headers.

This adds play/pause controls to video headers, along with voice
assistance, using `wp.a11y.speak`, to make custom video headers more
accessible. To make styling the play/pause button easier for themes,
CSS has been omitted from the default implementation.

This also includes a refactor of the `wp.customHeader` code to introduce
a `BaseHandler` class, which can be extended by plugins and themes to modify
or enhance the default video handlers.

Props davidakennedy, afercia, bradyvercher, joemcgill, adamsilverstein, rianrietveld.
Fixes #38678.

git-svn-id: https://develop.svn.wordpress.org/trunk@39272 602fd350-edb4-49c9-b593-d223f7449a82

src/wp-includes/class-wp-customize-manager.php

@@ -3596,7 +3596,7 @@ final class WP_Customize_Manager {
 		$this->add_setting( 'external_header_video', array(
 			'theme_supports'    => array( 'custom-header', 'video' ),
 			'transport'         => 'postMessage',
-			'sanitize_callback' => 'esc_url',
+			'sanitize_callback' => 'esc_url_raw',
 			'validate_callback' => array( $this, '_validate_external_header_video' ),
 		) );
 

src/wp-includes/js/wp-custom-header.js

@@ -1,155 +1,446 @@
-(function( window, settings ) {
+/* global YT */
+( function( window, settings ) {
 
+	var NativeHandler, YouTubeHandler;
+
+	window.wp = window.wp || {};
+
+	// Fail gracefully in unsupported browsers.
 	if ( ! ( 'addEventListener' in window ) ) {
-		// Fail gracefully in unsupported browsers.
 		return;
 	}
 
-	function wpCustomHeader() {
+	/**
-		var handlers = {
+	 * Trigger an event.
-			nativeVideo: {
+	 *
-				test: function( settings ) {
+	 * @param {Element} target HTML element to dispatch the event on.
-					var video = document.createElement( 'video' );
+	 * @param {string} name Event name.
-					return video.canPlayType( settings.mimeType );
+	 */
-				},
+	function trigger( target, name ) {
-				callback: nativeHandler
+		var evt;
-			},
+
-			youtube: {
+		if ( 'function' === typeof window.Event ) {
-				test: function( settings ) {
+			evt = new Event( name );
-					return 'video/x-youtube' === settings.mimeType;
+		} else {
-				},
+			evt = document.createEvent( 'Event' );
-				callback: youtubeHandler
+			evt.initEvent( name, true, true );
-			}
+		}
+
+		target.dispatchEvent( evt );
+	}
+
+	/**
+	 * Create a custom header instance.
+	 *
+	 * @class CustomHeader
+	 */
+	function CustomHeader() {
+		this.handlers = {
+			nativeVideo: new NativeHandler(),
+			youtube: new YouTubeHandler()
 		};
+	}
 
-		function initialize() {
+	CustomHeader.prototype = {
-			settings.container = document.getElementById( 'wp-custom-header' );
+		/**
+		 * Initalize the custom header.
+		 *
+		 * If the environment supports video, loops through registered handlers
+		 * until one is found that can handle the video.
+		 */
+		initialize: function() {
+			if ( this.supportsVideo() ) {
+				for ( var id in this.handlers ) {
+					var handler = this.handlers[ id ];
 
-			if ( supportsVideo() ) {
+					if ( 'test' in handler && handler.test( settings ) ) {
-				for ( var id in handlers ) {
+						this.activeHandler = handler.initialize.call( handler, settings );
-					var handler = handlers[ id ];
-
-					if ( handlers.hasOwnProperty( id ) && handler.test( settings ) ) {
-						handler.callback( settings );
-
-						// Set up and dispatch custom event when the video is loaded.
-						if ( 'dispatchEvent' in window ) {
-							var videoLoaded = new Event( 'wp-custom-header-video-loaded' );
-							document.dispatchEvent( videoLoaded );
-						}
 
+						// Dispatch custom event when the video is loaded.
+						trigger( document, 'wp-custom-header-video-loaded' );
 						break;
 					}
 				}
 			}
-		}
+		},
 
-		function supportsVideo() {
+		/**
+		 * Determines if the current environment supports video.
+		 *
+		 * Themes and plugins can override this method to change the criteria.
+		 *
+		 * @return {boolean}
+		 */
+		supportsVideo: function() {
 			// Don't load video on small screens. @todo: consider bandwidth and other factors.
-			if ( window.innerWidth < settings.minWidth  || window.innerHeight < settings.minHeight ) {
+			if ( window.innerWidth < settings.minWidth || window.innerHeight < settings.minHeight ) {
 				return false;
 			}
 
 			return true;
-		}
+		},
 
-		return {
+		/**
-			handlers: handlers,
+		 * Base handler for custom handlers to extend.
-			initialize: initialize,
+		 *
-			supportsVideo: supportsVideo
+		 * @type {BaseHandler}
-		};
+		 */
-	}
+		BaseVideoHandler: BaseHandler
+	};
 
-	function nativeHandler( settings ) {
+	/**
-		var video = document.createElement( 'video' );
+	 * Create a video handler instance.
+	 *
+	 * @class BaseHandler
+	 */
+	function BaseHandler() {}
 
-		video.id = 'wp-custom-header-video';
+	BaseHandler.prototype = {
-		video.autoplay = 'autoplay';
+		/**
-		video.loop = 'loop';
+		 * Initialize the video handler.
-		video.muted = 'muted';
+		 *
-		video.width = settings.width;
+		 * @param {object} settings Video settings.
-		video.height = settings.height;
+		 */
+		initialize: function( settings ) {
+			var handler = this,
+				button = document.createElement( 'button' );
 
-		video.addEventListener( 'click', function() {
+			this.settings = settings;
-			if ( video.paused ) {
+			this.container = document.getElementById( 'wp-custom-header' ),
-				video.play();
+			this.button = button;
-			} else {
-				video.pause();
-			}
-		});
 
-		settings.container.innerHTML = '';
+			button.setAttribute( 'type', 'button' );
-		settings.container.appendChild( video );
+			button.setAttribute( 'id', 'wp-custom-header-video-button' );
-		video.src = settings.videoUrl;
+			button.setAttribute( 'class', 'wp-custom-header-video-button wp-custom-header-video-play' );
-	}
+			button.innerHTML = settings.l10n.play;
 
-	function youtubeHandler( settings ) {
+			// Toggle video playback when the button is clicked.
-		// @link http://stackoverflow.com/a/27728417
+			button.addEventListener( 'click', function() {
-		var VIDEO_ID_REGEX = /^.*(?:(?:youtu\.be\/|v\/|vi\/|u\/\w\/|embed\/)|(?:(?:watch)?\?v(?:i)?=|\&v(?:i)?=))([^#\&\?]*).*/,
+				if ( handler.isPaused() ) {
-			videoId = settings.videoUrl.match( VIDEO_ID_REGEX )[1];
+					handler.play();
-
+				} else {
-		function loadVideo() {
+					handler.pause();
-			var YT = window.YT || {};
+				}
-
-			YT.ready(function() {
-				var video = document.createElement( 'div' );
-				video.id = 'wp-custom-header-video';
-				settings.container.innerHTML = '';
-				settings.container.appendChild( video );
-
-				new YT.Player( video, {
-					height: settings.height,
-					width: settings.width,
-					videoId: videoId,
-					events: {
-						onReady: function( e ) {
-							e.target.mute();
-						},
-						onStateChange: function( e ) {
-							if ( YT.PlayerState.ENDED === e.data ) {
-								e.target.playVideo();
-							}
-						}
-					},
-					playerVars: {
-						autoplay: 1,
-						controls: 0,
-						disablekb: 1,
-						fs: 0,
-						iv_load_policy: 3,
-						loop: 1,
-						modestbranding: 1,
-						//origin: '',
-						playsinline: 1,
-						rel: 0,
-						showinfo: 0
-					}
-				});
 			});
+
+			// Update the button class and text when the video state changes.
+			this.container.addEventListener( 'play', function() {
+				button.className = 'wp-custom-header-video-button wp-custom-header-video-play';
+				button.innerHTML = settings.l10n.pause;
+				if ( 'a11y' in window.wp ) {
+					window.wp.a11y.speak( settings.l10n.playSpeak);
+				}
+			});
+
+			this.container.addEventListener( 'pause', function() {
+				button.className = 'wp-custom-header-video-button wp-custom-header-video-pause';
+				button.innerHTML = settings.l10n.play;
+				if ( 'a11y' in window.wp ) {
+					window.wp.a11y.speak( settings.l10n.pauseSpeak);
+				}
+			});
+
+			this.ready();
+		},
+
+		/**
+		 * Ready method called after a handler is initialized.
+		 *
+		 * @abstract
+		 */
+		ready: function() {},
+
+		/**
+		 * Whether the video is paused.
+		 *
+		 * @abstract
+		 * @return {boolean}
+		 */
+		isPaused: function() {},
+
+		/**
+		 * Pause the video.
+		 *
+		 * @abstract
+		 */
+		pause: function() {},
+
+		/**
+		 * Play the video.
+		 *
+		 * @abstract
+		 */
+		play: function() {},
+
+		/**
+		 * Append a video node to the header container.
+		 *
+		 * @param {Element} node HTML element.
+		 */
+		setVideo: function( node ) {
+			var editShortcutNode,
+				editShortcut = this.container.getElementsByClassName( 'customize-partial-edit-shortcut' );
+
+			if ( editShortcut.length ) {
+				editShortcutNode = this.container.removeChild( editShortcut[0] );
+			}
+
+			this.container.innerHTML = '';
+			this.container.appendChild( node );
+
+			if ( editShortcutNode ) {
+				this.container.appendChild( editShortcutNode );
+			}
+		},
+
+		/**
+		 * Show the video controls.
+		 *
+		 * Appends a play/pause button to header container.
+		 */
+		showControls: function() {
+			if ( ! this.container.contains( this.button ) ) {
+				this.container.appendChild( this.button );
+			}
+		},
+
+		/**
+		 * Whether the handler can process a video.
+		 *
+		 * @abstract
+		 * @param {object} settings Video settings.
+		 * @return {boolean}
+		 */
+		test: function() {
+			return false;
+		},
+
+		/**
+		 * Trigger an event on the header container.
+		 *
+		 * @param {string} name Event name.
+		 */
+		trigger: function( name ) {
+			trigger( this.container, name );
+		}
+	};
+
+	/**
+	 * Create a custom handler.
+	 *
+	 * @param  {object} protoProps Properties to apply to the prototype.
+	 * @return CustomHandler The subclass.
+	 */
+	BaseHandler.extend = function( protoProps ) {
+		var prop;
+
+		function CustomHandler() {
+			var result = BaseHandler.apply( this, arguments );
+			return result;
 		}
 
-		if ( 'YT' in window ) {
+		CustomHandler.prototype = Object.create( BaseHandler.prototype );
-			loadVideo();
+		CustomHandler.prototype.constructor = CustomHandler;
-		} else {
+
-			var tag = document.createElement( 'script' );
+		for ( prop in protoProps ) {
-			tag.src = 'https://www.youtube.com/player_api';
+			CustomHandler.prototype[ prop ] = protoProps[ prop ];
-			tag.onload = function () { loadVideo(); };
-			document.getElementsByTagName( 'head' )[0].appendChild( tag );
 		}
-	}
 
-	window.wp = window.wp || {};
+		return CustomHandler;
-	window.wp.customHeader = new wpCustomHeader();
+	};
-	document.addEventListener( 'DOMContentLoaded', window.wp.customHeader.initialize, false );
 
+	/**
+	 * Native video handler.
+	 *
+	 * @class NativeHandler
+	 */
+	NativeHandler = BaseHandler.extend({
+		/**
+		 * Whether the native handler supports a video.
+		 *
+		 * @param {object} settings Video settings.
+		 * @return {boolean}
+		 */
+		test: function( settings ) {
+			var video = document.createElement( 'video' );
+			return video.canPlayType( settings.mimeType );
+		},
+
+		/**
+		 * Set up a native video element.
+		 */
+		ready: function() {
+			var handler = this,
+				video = document.createElement( 'video' );
+
+			video.id = 'wp-custom-header-video';
+			video.autoplay = 'autoplay';
+			video.loop = 'loop';
+			video.muted = 'muted';
+			video.width = this.settings.width;
+			video.height = this.settings.height;
+
+			video.addEventListener( 'play', function() {
+				handler.trigger( 'play' );
+			});
+
+			video.addEventListener( 'pause', function() {
+				handler.trigger( 'pause' );
+			});
+
+			video.addEventListener( 'canplay', function() {
+				handler.showControls();
+			});
+
+			this.video = video;
+			handler.setVideo( video );
+			video.src = this.settings.videoUrl;
+		},
+
+		/**
+		 * Whether the video is paused.
+		 *
+		 * @return {boolean}
+		 */
+		isPaused: function() {
+			return this.video.paused;
+		},
+
+		/**
+		 * Pause the video.
+		 */
+		pause: function() {
+			this.video.pause();
+		},
+
+		/**
+		 * Play the video.
+		 */
+		play: function() {
+			this.video.play();
+		}
+	});
+
+	/**
+	 * YouTube video handler.
+	 *
+	 * @class YouTubeHandler
+	 */
+	YouTubeHandler = BaseHandler.extend({
+		/**
+		 * Whether the handler supports a video.
+		 *
+		 * @param {object} settings Video settings.
+		 * @return {boolean}
+		 */
+		test: function( settings ) {
+			return 'video/x-youtube' === settings.mimeType;
+		},
+
+		/**
+		 * Set up a YouTube iframe.
+		 *
+		 * Loads the YouTube IFrame API if the 'YT' global doesn't exist.
+		 */
+		ready: function() {
+			var handler = this;
+
+			if ( 'YT' in window ) {
+				YT.ready( handler.loadVideo.bind( handler ) );
+			} else {
+				var tag = document.createElement( 'script' );
+				tag.src = 'https://www.youtube.com/iframe_api';
+				tag.onload = function () {
+					YT.ready( handler.loadVideo.bind( handler ) );
+				};
+
+				document.getElementsByTagName( 'head' )[0].appendChild( tag );
+			}
+		},
+
+		/**
+		 * Load a YouTube video.
+		 */
+		loadVideo: function() {
+			var handler = this,
+				video = document.createElement( 'div' ),
+				// @link http://stackoverflow.com/a/27728417
+				VIDEO_ID_REGEX = /^.*(?:(?:youtu\.be\/|v\/|vi\/|u\/\w\/|embed\/)|(?:(?:watch)?\?v(?:i)?=|\&v(?:i)?=))([^#\&\?]*).*/;
+
+			video.id = 'wp-custom-header-video';
+			handler.setVideo( video );
+
+			handler.player = new YT.Player( video, {
+				height: this.settings.height,
+				width: this.settings.width,
+				videoId: this.settings.videoUrl.match( VIDEO_ID_REGEX )[1],
+				events: {
+					onReady: function( e ) {
+						e.target.mute();
+						handler.showControls();
+					},
+					onStateChange: function( e ) {
+						if ( YT.PlayerState.PLAYING === e.data ) {
+							handler.trigger( 'play' );
+						} else if ( YT.PlayerState.PAUSED === e.data ) {
+							handler.trigger( 'pause' );
+						} else if ( YT.PlayerState.ENDED === e.data ) {
+							e.target.playVideo();
+						}
+					}
+				},
+				playerVars: {
+					autoplay: 1,
+					controls: 0,
+					disablekb: 1,
+					fs: 0,
+					iv_load_policy: 3,
+					loop: 1,
+					modestbranding: 1,
+					playsinline: 1,
+					rel: 0,
+					showinfo: 0
+				}
+			});
+		},
+
+		/**
+		 * Whether the video is paused.
+		 *
+		 * @return {boolean}
+		 */
+		isPaused: function() {
+			return YT.PlayerState.PAUSED === this.player.getPlayerState();
+		},
+
+		/**
+		 * Pause the video.
+		 */
+		pause: function() {
+			this.player.pauseVideo();
+		},
+
+		/**
+		 * Play the video.
+		 */
+		play: function() {
+			this.player.playVideo();
+		}
+	});
+
+	// Initialize the custom header when the DOM is ready.
+	window.wp.customHeader = new CustomHeader();
+	document.addEventListener( 'DOMContentLoaded', window.wp.customHeader.initialize.bind( window.wp.customHeader ), false );
+
+	// Selective refresh support in the Customizer.
 	if ( 'customize' in window.wp ) {
-		wp.customize.selectiveRefresh.bind( 'render-partials-response', function( response ) {
+		window.wp.customize.selectiveRefresh.bind( 'render-partials-response', function( response ) {
 			if ( 'custom_header_settings' in response ) {
 				settings = response.custom_header_settings;
 			}
 		});
 
-		wp.customize.selectiveRefresh.bind( 'partial-content-rendered', function( placement ) {
+		window.wp.customize.selectiveRefresh.bind( 'partial-content-rendered', function( placement ) {
 			if ( 'custom_header' === placement.partial.id ) {
 				window.wp.customHeader.initialize();
 			}

src/wp-includes/script-loader.php

@@ -481,7 +481,7 @@ function wp_default_scripts( &$scripts ) {
 	$scripts->add( 'customize-nav-menus', "/wp-admin/js/customize-nav-menus$suffix.js", array( 'jquery', 'wp-backbone', 'customize-controls', 'accordion', 'nav-menu' ), false, 1 );
 	$scripts->add( 'customize-preview-nav-menus', "/wp-includes/js/customize-preview-nav-menus$suffix.js", array( 'jquery', 'wp-util', 'customize-preview', 'customize-selective-refresh' ), false, 1 );
 
-	$scripts->add( 'wp-custom-header', "/wp-includes/js/wp-custom-header$suffix.js", array(), false, 1 );
+	$scripts->add( 'wp-custom-header', "/wp-includes/js/wp-custom-header$suffix.js", array( 'wp-a11y' ), false, 1 );
 
 	$scripts->add( 'accordion', "/wp-admin/js/accordion$suffix.js", array( 'jquery' ), false, 1 );
 

src/wp-includes/theme.php

@@ -1381,6 +1381,12 @@ function get_header_video_settings() {
 		'height'    => absint( $header->height ),
 		'minWidth'  => 900,
 		'minHeight' => 500,
+		'l10n'      => array(
+			'pause'      => __( 'Pause' ),
+			'play'       => __( 'Play' ),
+			'pauseSpeak' => __( 'Video is paused.'),
+			'playSpeak'  => __( 'Video is playing.'),
+		),
 	);
 
 	if ( preg_match( '#^https?://(?:www\.)?(?:youtube\.com/watch|youtu\.be/)#', $video_url ) ) {