Video Headers in 4.7

WordPress 4.7 extends the Custom Header feature to introduce support for video.

Video headers are considered decorative elements — like headerHeader The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes. images, but with motion. With that in mind, they play automatically, loopLoop The Loop is PHP code used by WordPress to display posts. Using The Loop, WordPress processes each post to be displayed on the current page, and formats it according to how it matches specified criteria within The Loop tags. Any HTML or PHP code in the Loop will be processed on each post. https://codex.wordpress.org/The_Loop. by default, and don’t have sound. They work best when paired with an image, so they can progressively enhance the experience when video is supported.

Header media UIUI User interface in the customizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings. when a theme supports video.

Adding theme support

Adding support for video headers to a theme requires three basic steps:

Registering theme support

Support for video headers can be registered when adding support for custom headers in a theme.

add_theme_support( 'custom-header', array(
 'video' => true,
) );

Adding support this way does a few things:

  • Renames the “Header Image” customizer section to “Header Media.”
  • Registers customizer controls for selecting a video from the media library or entering a URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org to a YouTube video.
  • Enables support for Selective Refresh for header images.

Displaying the header

In previous versions of WordPress, generating the image tagtag A directory in Subversion. WordPress uses tags to store a single snapshot of a version (3.6, 3.6.1, etc.), the common convention of tags in version control systems. (Not to be confused with post tags.) manually was the recommended way to display a header image. WordPress 4.4 introduced the_header_image_tag() to take advantage of the responsive image improvements.

In WordPress 4.7, the_custom_header_markup() unifies support for header images and videos and is the recommended method for displaying custom headers.

It prints a div that will contain a header image if one is set in the customizer and will also enqueue the wp-custom-header.js script if a video is set in the customizer. The script determines if the environment supports video, and if so, it will progressively enhance the header by replacing the image with a video.

Styling the play/pause button

When videos are ready to play, the wp-custom-header.js script inserts a button for pausing and playing the video to help improve accessibilityAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility). CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. does not apply any CSSCSS Cascading Style Sheets. to the button in order to makemake A collection of P2 blogs at make.wordpress.org, which are the home to a number of contributor groups, including core development (make/core, formerly "wpdevel"), the UI working group (make/ui), translators (make/polyglots), the theme reviewers (make/themes), resources for plugin authors (make/plugins), and the accessibility working group (make/accessibility). it easier for themes to style. Themes should ensure the button is visible, fits within the design, and add icons if desired.

Pause Button
<button type="button" id="wp-custom-header-video-button" class="wp-custom-header-video-button wp-custom-header-video-play">Pause</button>

Play Button
<button type="button" id="wp-custom-header-video-button" class="wp-custom-header-video-button wp-custom-header-video-pause">Play</button>

The text for the button can be modified using the header_video_settings filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output..

Styling custom headers

When styling custom headers, it’s important to be aware of the various elements that can be used for header media.

A container div with a wp-custom-header class will always be rendered when a header image or video is available. The div may contain an image, video, or iframeiframe iFrame is an acronym for an inline frame. An iFrame is used inside a webpage to load another HTML document and render it. This HTML document may also contain JavaScript and/or CSS which is loaded at the time when iframe tag is parsed by the user’s browser. depending on the source of the video, so each of those elements needs to be considered.

The following selectors should be fairly standard for creating responsive headers:

.wp-custom-header iframe,
.wp-custom-header img,
.wp-custom-header video {
	display: block;
	height: auto;
	max-width: 100%;
}

Accessibility considerations

A button to toggle the play/pause state of the video is automatically rendered to help users who may be distracted or disoriented by motion. Voice assistance is also available using wp.a11y.speak, and like the button text, the strings can be modified using the header_video_settings filter.

Bandwidth considerations

To alleviate concerns about bandwidth, videos are only loaded on the front page for viewports that are at least 900 pixels wide and 500 pixels tall. The maximum file size is also capped at 8MB; however, we strongly encourage smaller files be used whenever possible.

Filtering the front page restriction

By default, videos are only loaded on the front page and only the header image is shown on other pages calling the_custom_header_markup(). Themes that need to display the header video on pages other than the front page can:

  • Define a custom callback for the video-active-callback header argument.
  • Use the is_header_video_active filter.

Testing the environment for video support

Themes may also want to customize the criteria used to determine whether or not a video should be embedded. The header_video_settings filter can be used to modify the minimum viewport width and height.

On the front end, the wp.customHeader.supportsVideo() method can be redefined. For instance, it might be desirable to test the user agent to prevent videos from loading on mobile devices that don’t support autoplay. As browsers introduce bandwidth APIs, it may also be worthwhile to disable video on devices with limited bandwidth.

Selective Refresh enabled by default

When registering support for video headers in a theme, header image settings in the customizer are updated to use the postMessage transport to take advantage of the Selective Refresh API introduced in WordPress 4.5. This ensures header images and videos can be updated in the customizer without refreshing the preview window.

If the_custom_header_markup() template tag isn’t being used, themes will need to update the custom header partial to use a custom render_callback, or change the transport for the header_image and header_image_data settings back to refresh.

Creating custom video handlers

Locally hosted mp4 and mov files, as well as YouTube videos, can be used for video headers by default, but it’s possible to add support for additional sources as well.

The wp-custom-header.js script exports a wp.customHeader.handlers global variable that contains a list of video handlers. Each handler accepts information about the current video to determine if it can process it, and if so, it creates the video and inserts it into the DOM.

Core registers two handlers, one for native video, and one for YouTube videos. Each handler extends a base class exposed at wp.customHeader.BaseVideoHandler and implements a basic interface to make sure all videos receive the same level of support.

In the customizer, there is validation to ensure that local videos are a supported format and file size, and that external video links are to YouTube. This validation needs to be filtered to account for custom handlers, either with the customize_validate_external_header_video and customize_validate_header_video filters to filter the core validation functions, or by changing the validation_callback on the header_video and external_header_video customizer settings. See the documentation on customizer validation for more details.

For an example of registering a custom video handler in a pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party, take a look at how this plugin registers support for Vimeo.

New functions and hooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same.

  • has_header_video() – Checks whether a header video has been set in the customizer.
  • is_header_video_active() – Checks whether a header video is eligible to be shown for the current request.
  • get_header_video_url() – Retrieve the header video URL. May be a local attachment URL or a URL for an external source.
  • the_header_video_url() – Display the header video URL.
  • has_custom_header() – Checks whether a header image or video is set in the customizer and is available for the current request.
  • get_custom_header_markup() – Retrieve the markup for displaying a custom header image (this does not include video support).
  • the_custom_header_markup() – Display the custom header markup and enqueue a script for rendering video in supported environments.

Filters

  • is_header_video_active – Whether a header video should be shown for the current request if available.
  • header_video_settings – Settings that are exported to the wp-custom-header.js script during initial page load and when updating the custom header partial in the customizer preview. The default values are:
    • videoUrl – URL for the selected video.
    • mimeType – MIME type of the selected video.
    • posterUrl – URL for the fallback header image.
    • width – Video width.
    • height – Video height.
    • minWidth – Minimum viewport width to embed a video.
    • minHeight – Minimum viewport height to embed a video.
    • l10n – An array of button text and accessibility strings.

Theme support arguments

When calling add_theme_support( 'custom-header' ), two new arguments are available:

  • video – Registers support for video headers.
  • video-active-callback – Defines a callback used to determine whether a header video should be shown for the current request. Defaults to is_front_page.

#4-7, #custom-header, #customize, #dev-notes, #themes