From b5563ef917ee1a2c4659236dfc2caffaa9d292be Mon Sep 17 00:00:00 2001 From: Joe McGill Date: Wed, 16 Nov 2016 23:25:28 +0000 Subject: [PATCH] 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 --- .../class-wp-customize-manager.php | 2 +- src/wp-includes/js/wp-custom-header.js | 521 ++++++++++++++---- src/wp-includes/script-loader.php | 2 +- src/wp-includes/theme.php | 6 + 4 files changed, 414 insertions(+), 117 deletions(-) diff --git a/src/wp-includes/class-wp-customize-manager.php b/src/wp-includes/class-wp-customize-manager.php index 1a975fb664..016c1d4d53 100644 --- a/src/wp-includes/class-wp-customize-manager.php +++ b/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' ), ) ); diff --git a/src/wp-includes/js/wp-custom-header.js b/src/wp-includes/js/wp-custom-header.js index 08e24882fa..929e6cf02a 100644 --- a/src/wp-includes/js/wp-custom-header.js +++ b/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 = { - nativeVideo: { - test: function( settings ) { - var video = document.createElement( 'video' ); - return video.canPlayType( settings.mimeType ); - }, - callback: nativeHandler - }, - youtube: { - test: function( settings ) { - return 'video/x-youtube' === settings.mimeType; - }, - callback: youtubeHandler - } + /** + * Trigger an event. + * + * @param {Element} target HTML element to dispatch the event on. + * @param {string} name Event name. + */ + function trigger( target, name ) { + var evt; + + if ( 'function' === typeof window.Event ) { + evt = new Event( name ); + } else { + evt = document.createEvent( 'Event' ); + 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() { - settings.container = document.getElementById( 'wp-custom-header' ); + CustomHeader.prototype = { + /** + * 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() ) { - for ( var id in handlers ) { - 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 ); - } + if ( 'test' in handler && handler.test( settings ) ) { + this.activeHandler = handler.initialize.call( handler, settings ); + // 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, - initialize: initialize, - supportsVideo: supportsVideo - }; - } + /** + * Base handler for custom handlers to extend. + * + * @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'; - video.autoplay = 'autoplay'; - video.loop = 'loop'; - video.muted = 'muted'; - video.width = settings.width; - video.height = settings.height; + BaseHandler.prototype = { + /** + * Initialize the video handler. + * + * @param {object} settings Video settings. + */ + initialize: function( settings ) { + var handler = this, + button = document.createElement( 'button' ); - video.addEventListener( 'click', function() { - if ( video.paused ) { - video.play(); - } else { - video.pause(); - } - }); + this.settings = settings; + this.container = document.getElementById( 'wp-custom-header' ), + this.button = button; - settings.container.innerHTML = ''; - settings.container.appendChild( video ); - video.src = settings.videoUrl; - } + button.setAttribute( 'type', 'button' ); + button.setAttribute( 'id', 'wp-custom-header-video-button' ); + button.setAttribute( 'class', 'wp-custom-header-video-button wp-custom-header-video-play' ); + button.innerHTML = settings.l10n.play; - function youtubeHandler( settings ) { - // @link http://stackoverflow.com/a/27728417 - var VIDEO_ID_REGEX = /^.*(?:(?:youtu\.be\/|v\/|vi\/|u\/\w\/|embed\/)|(?:(?:watch)?\?v(?:i)?=|\&v(?:i)?=))([^#\&\?]*).*/, - videoId = settings.videoUrl.match( VIDEO_ID_REGEX )[1]; - - function loadVideo() { - 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 - } - }); + // Toggle video playback when the button is clicked. + button.addEventListener( 'click', function() { + if ( handler.isPaused() ) { + handler.play(); + } else { + handler.pause(); + } }); + + // 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 ) { - loadVideo(); - } else { - var tag = document.createElement( 'script' ); - tag.src = 'https://www.youtube.com/player_api'; - tag.onload = function () { loadVideo(); }; - document.getElementsByTagName( 'head' )[0].appendChild( tag ); + CustomHandler.prototype = Object.create( BaseHandler.prototype ); + CustomHandler.prototype.constructor = CustomHandler; + + for ( prop in protoProps ) { + CustomHandler.prototype[ prop ] = protoProps[ prop ]; } - } - window.wp = window.wp || {}; - window.wp.customHeader = new wpCustomHeader(); - document.addEventListener( 'DOMContentLoaded', window.wp.customHeader.initialize, false ); + return CustomHandler; + }; + /** + * 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(); } diff --git a/src/wp-includes/script-loader.php b/src/wp-includes/script-loader.php index fadfb28870..e405b13134 100644 --- a/src/wp-includes/script-loader.php +++ b/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 ); diff --git a/src/wp-includes/theme.php b/src/wp-includes/theme.php index 6401efda00..7514dd936e 100644 --- a/src/wp-includes/theme.php +++ b/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 ) ) {