Make WordPress Core

Tagged: 4.7 Toggle Comment Threads | Keyboard Shortcuts

  • Andrew Rockwell 8:34 pm on December 8, 2016 Permalink |
    Tags: 4.7,   

    Week in Core, November 30 – December 6, 2016 

    Welcome back the latest issue of Week in Core, covering changes [39380-39529]. Here are the highlights:

    • 150 commits
    • 63 contributors
    • 140 tickets created
    • 17 tickets reopened
    • 104 tickets closed
    • WordPress 4.7 released 🎉

    Ticket numbers based on trac timeline for the period above. The following is a summary of commits, organized by component.

    Code Changes


    • Accessibility: Remove inappropriate content from the Themes screen heading. [39528] #26601
    • Accessibility: Remove inappropriate content from the Add Themes screen heading. [39527] #26601
    • Accessibility: Remove inappropriate content from the Media Library screens headings. [39526] #26601

    Build/Test Tools

    • Correctly set up the current screen during list table tests so that they don’t fail when run individually. [39481] #38761
    • Specify exact node version in package.json. [39480], [39478] #35105, #38657
    • Remove PHP 7.1 from allowed failures [39424-39425] #37625

    Bundled Theme

    • Default Themes: Update version numbers and readme files for 4.7 release [39496] #38858
    • Twenty Seventeen: Fix CSS specificity problem with CSS feature query for object-fit [39495] #39073
    • Twenty Seventeen: Improve display of video header and header image in modern browsers [39485], [39483] #39035
    • Twenty Seventeen: Add specific font stack for Thai language [39484], [39482] #38937
    • Twenty Seventeen: Improve ARIA for the nav menu. [39451-39452] #39029, #39026
    • Twenty Seventeen: Ensure header text color updates in Customizer preview when cleared [39447-39448] #38993
    • Twenty Seventeen: Fix broken menu toggle in Customizer after menu items are added [39419], [39423] #38992
    • Twenty Seventeen: Fix style issues with gallery image links [39418], [39422] #38969
    • Twenty Seventeen: Hide front section panels on page load of Customizer. [39417], [39421] #38951
    • Twenty Seventeen: Add .has-header-video styles for custom color schemes. [39416] #38995
    • Twenty Seventeen: Better handling of custom headers when no image is set. [39413-39414] #38995
    • Twenty Seventeen: Make spacing on pages without comments consistent [39404-39405] #38972
    • Twenty Seventeen: Make sure header text color is applied when color schemes are active. [39397-39398] #38980
    • Twenty Seventeen: Make fixed navigation apply at correct height on front page, without header video or image [39394], [39392] #38927
    • Twenty Seventeen: Provide a background color fallback for non-webkit browsers on input styles [39388] #38939
    • Twenty Seventeen: Allow child themes to easily extend custom color patterns [39386] #38949
    • Twenty Seventeen: Make screen reader text on scroll arrow more meaningful [39384] #38970
    • Twenty Seventeen: Keep header videos from extending past footer. [39380-39381] #38950


    • Merge a similar string between comments.php, XML-RPC and the REST API comments controller. [39508] #39013


    • Prevent infinite full refresh from occurring when selective refresh falls back for a nav menu that has items excluded from rendering via filtering. [39510-39511] #38612
    • Defer populating post_name for auto-draft posts in customized state until posts are published. [39506-39507] #39078
    • Ensure changeset_uuid query param is removed from the customize.php window’s location once a changeset has been published (committed) with starter content. [39504-39505] #39081
    • Prevent posts/pages imported via starter content from being dropped when adding post/page stubs via nav menus and the dropdown-pages control. [39502-39503] #38114, #34923, #39071
    • Ensure textarea for Custom CSS displays as code (in LTR) when an RTL language is active. [39499-39500] #35395, #39085
    • Ensure a custom_css post insertion gets an initial post revision. [39479], [39477] #30854, #38672, #35395, #39032
    • Custom CSS: Change the help link to something better for users. [39467], [39466] #39015
    • Fix posts limit query arg for WP_Query from incorrect number to posts_per_page. [39434-39435] #39022
    • Reuse existing non-auto-draft posts and existing auto-draft posts in the customized state with matching slugs when applying starter content. [39411] #38114, #38928
    • Reject a changeset update when a non-future date is provided and also ensure that a published changeset always gets set to the current date/time. [39409-39410] #30937, #38943
    • Fix handling of the nav menu item labels (titles) that match defaults (original titles) and fix the display of item type labels. [39395], [39393] #38015, #38955





    • Accessibility: Improve keyboard accessibility avoiding confusing tab stops in the Media views. [39529] #30599
    • Docs: Add inline documentation for image-edit.js. [39493] #38748
    • Fix regression with display of small images in media library. [39399], [39396] #38965
    • Docs: Document the usage of the global $wpdb in _filter_query_attachment_filenames(). [39390] #38973


    • Tag 4.7 [39525] #
    • WordPress 4.7 “Vaughan”. [39524] #
    • Post-RC3 bump. [39519] #
    • WordPress 4.7 RC3. [39516] #
    • Post-RC2 bump. [39474] #
    • WordPress 4.7 RC2. [39473] #
    • Twenty Seventeen: Add .has-header-video styles for custom color schemes. [39415]

    Options, Meta APIs

    • REST API: Register the admin_email setting in single site only. [39470-39472] #38990
    • REST API: Site URL setting should not be present on multisite installations. [39468] #39005
    • REST API: Correct the admin_email setting description for single site installs. [39406] #38990
    • Multisite: Display different descriptions for multisite or single site installations. [39407] #38990
    • Options: Pass the $passed_default parameter to the 'default_option_{$option} filter in add_option(). [39382] #38176, #38930



    • Comments: Merge similar strings between comments.php and the REST API comments controller. [39490-39491] #39014
    • Merge similar date strings in the revisions and comments controllers. [39488-39489] #39016
    • Treat any falsy value as false in ‘rest_allow_anonymous_comments’. [39487] #39010
    • Docs: Add missing REST API-related args to register_post_type() and register_taxonomy(). [39462-39463] #39023
    • Merge similar strings in a comments endpoint parameter description. [39457] #39036
    • Fix bug where comment author and author email could be an empty string when creating a comment. [39446], [39444] #38971
    • Fix handling of some orderby parameters for the Posts controller. [39440-39441] #38971
    • Disable DELETE requests for users in multisite. [39438-39439] #38962
    • Return a WP_Error if meta property is not an array. [39436-39437] #38989
    • Add test for creating a comment with an invalid post ID. [39408] #38991
    • Fix incorrect uses of rest_sanitize_value_from_schema(). [39400-39401] #38984


    • Don’t assign the delete_site capability to anyone on single site installs. [39494] #38326
    • Multisite: Replace is_super_admin() with manage_network for admin bar permissions. [39492] #39064, #37616


    • Docs: Update an @since as there will not be a 4.6.2 before 4.7. [39475-39476] #37291
    • REST API: Capability check for editing a single term should use the singular form. [39464] #35614, #39012
    • REST API: Use the correct error message when editing a single term. [39460-39461] #39017
    • REST API: Fix incorrect capability check on term create. [39402-39403] #35614, #38958
    • Performance: Revert [38677] from the 4.7 branch. This avoids fatal errors caused with recursive calling of term functions within the get_terms filter. [39454] #21760


    • Reuse existing non-auto-draft posts and existing auto-draft posts in the customized state with matching slugs when applying starter content. [39412] #38114, #38928


    • Fix the styling of notices generated by the editor UI. [39501] #38917


    • Clarify the return value of get_current_user_id() for non-logged-in users. [39486] #39051
    • REST API: Require the reassign parameter when deleting users. [39426-39427] #39000

    Thanks to @andizer, @mor10, @jnylen0, @adamsilverstein, @afercia, @azaozz, @boonebgorges, @celloexpressions, @ChopinBach, @clorith, @coffee2code, @davidakennedy, @dd32, @desros, @dlh, @dlh, @flixos90, @georgestephanis, @helen, @helen, @hnle, @iaaxpage, @imnok, @jbpaul17, @jeremyfelt, @jnylen0, @joedolson, @joehoyle, @joemcgill, @johnbillion, @jorbin, @kadamwhite, @karmatosed, @ketuchetan, @laurelfulford, @littlebigthing, @lucasstark, @melchoyce, @michaelarestad, @mikeschroder, @mt8.biz, @nacin, @netweb, @ocean90, @ovenal, @pento, @peterwilsoncc, @presskopp, @rachelbaker, @rahulsprajapati, @ramiabraham, @ramiy, @rensw90, @rianrietveld, @rmccue, @samuelsidler, @sayedwp, @SergeyBiryukov, @sstoqnov, @The PHP tea, @timmydcrawford, @utkarshpatel, and @westonruter for their contributions!

  • Aaron Jorbin 7:32 pm on December 8, 2016 Permalink |
    Tags: 4.7, retrospective   

    4.7 Retrospective 

    A retrospective meeting on the WordPress 4.7  release will be held during the week of December 19th. In order to properly prepare for that retrospective and make the time as productive as possible, I would like to encourage everyone to comment below with things they would like to bring up. To help, here are three good questions to ask yourself:

    • What should WordPress start doing as a part of the development process?
    • What should WordPress stop doing as a part of the development process?
    • What should WordPress continue doing as a part of the development process?

    Please remember when commenting to keep the discussion professional and focused on ways the process of creating WordPress is either already working great or can be improved.

    • Aaron Jorbin 7:35 pm on December 8, 2016 Permalink | Log in to Reply

      We failed at getting the field guide and email to plugin dev out early enough. We have aimed to have that out around beta 2 and usually end up getting it out around RC the last few releases. This time it came out the day before (field guide) and day after the release (email)

    • Darren Ethier (nerrad) 7:41 pm on December 8, 2016 Permalink | Log in to Reply

      I’m curious as to how the announcement by Matt about changes to the development process is going to affect this retrospective process. It might be beneficial if there was some clarity surrounding that change brought up at the meeting perhaps? It may be hard to talk about improvements that can be when there’s some ambiguity about what developing WordPress core will look like in 2017.

      • Aaron Jorbin 8:03 pm on December 8, 2016 Permalink | Log in to Reply

        I can’t speak for @matt, but I imagine that the feedback generated will help inform the process in 2017 and going forward.

      • Jeffrey Paul 8:32 pm on December 8, 2016 Permalink | Log in to Reply

        I’d prefer we frame this Retrospective with the current state of core development in mind. Let’s identify the start/stop/continue doing items based on the current approach and as @jorbin says I’m certain it will help inform any changes in the process next year.

    • J.D. Grimes 9:02 pm on December 8, 2016 Permalink | Log in to Reply

      The posts explaining new features and changes are helpful, but I think that we need more of them. I follow the trac feed, and sometimes I know that as a plugin developer a particular ticket is important for me to take note of, but it can be difficult to unravel exactly what the final decision was just based on the changesets. An example of something that is going on right now is the a11y team’s work on removing excessive content from headings on admin screens. Often API changes get documented and UI changes don’t, but I’m a perfectionist and I like to stay up to date on the latest design/a11y evolutions as well. I can usually figure out what changes I might want to make in my plugins based on the changes in core, but I’m sure that often most plugin developers don’t even know that there was a change, if they don’t read every ticket.

      I also think that continuing to plan releases for particular dates and stick by those deadlines is helpful for me as a plugin developer. It helps me to plan plugin releases, because I can coordinate them with WordPress’s release cycle. By coordinating the release cycle of my plugins with WordPress, I can test any extensions against the new versions of both the plugin and WordPress at once, instead of having to duplicate effort in that regard.

    • Nick Halsey 2:49 am on December 9, 2016 Permalink | Log in to Reply

      We need to collectively review the “feature plugin merge guidelines” listed here: https://make.wordpress.org/core/handbook/about/release-cycle/features-as-plugins/#feature-plugin-merge-criteria

      While development in plugins has become less prominent, most of the bigger projects merging into core in 4.7 (I would exclude the REST API since that’s less user-facing) skipped many of the steps here. A lot of the points don’t apply to most projects – to the point that the checklist is often forgotten entirely. But there remains a need for better quality control and an updated checklist or recommended merge considerations for larger projects should be created accordingly. These written guidelines can better inform merge decisions and assess readiness.

      Only one feature posted a visual record on make/flow during 4.7. Prior to beta, that was also the only feature to publish any user testing on make blogs. There should have been far more of that happening, especially given the large number of significant user-oriented features in 4.7. I don’t think any frontend user testing of Twenty Seventeen was ever published either, which would have been a good way to identify potential usability issues.

      On a related note, clearer procedures about backing out merged features are needed. Particularly if a feature goes through an extensive process to demonstrate readiness and is approved for merge, input on removing the feature during beta/RC should be solicited publicly via make/core posts and scheduled meetings, similarly to the initial merge decision. Otherwise, the decision to remove a feature can seem to ignore the value of the opinions that went into making the decision initially and may not be fully informed about the broader implications with respect to related aspects of a component. If work on a feature seems to stagnate as bugs accumulate during beta and a lead is considering pulling it due to lack of attention, contributors working on the feature should be notified so that they can address the issues or recommend removing the feature based on availability. Perhaps putting more trust in the feature teams and component maintainers that are most intimately familiar with a given project could help ensure that decisions are more broadly considered.

  • Jeffrey Paul 7:16 pm on December 8, 2016 Permalink |
    Tags: 4.7, , ,   

    Dev Chat Summary: December 7th (4.7 launch week) 

    This post summarizes the dev chat meeting from December 7th (Slack archive).


    4.7 Issues Reported

    • Caches not always clearing, not something we can fix, but seems to be the most common problem
    • Couple of reports around fatals related to WP_Hook, one traced to APC the cause of the other is still unknown
      • #39132: WP 4.7, object-cache.php breaks the site if APC is not enabled in php
    • We’re unable to pinpoint why lots of folks who meet the requirements still don’t have PDF thumbnails
      • Are there more specific requirements beyond “you need Imagik, ImageMagick and Ghostscript” perhaps specific versions?
      • Many problems so far there have been outright lack of Ghostscript installed, so having the gs info when reporting bugs would be great
      • Discussion continued on capturing ghostscript, Imagick and ImageMagick versions details via a plugin (e.g., a hidden wp-admin/debug.php, https://wordpress.org/plugins/health-check/)
    • Several reports of rest_cannot_edit and similar things from the users endpoints
    • Reports of people getting denied access to the admin area, issue appears to all be caching plugins not being cleared properly
    • #39104: Customize: starter content home menu item needs to be a link, not a page
      • This is concerning for back-compatability and needs to have a coordinated Twenty Seventeen update. The usability implications are somewhat concerning for new sites being created with 4.7.0.
    • #39146: plugin.php gives error on do_all_hook() function
    • #39150: Empty JSON Payload Causes rest_invalid_json
    • Thanks to @macmanx and @clorith and all of the people volunteering in the forums! Would be great for everyone to help answer questions in the forums, its a great way to understand the problems that users are having.

    4.7.1 Planning

    • Discussion on targeting 4.7.1 before the holidays in December 2016 or aiming for January 2017
      • Timing depends heavily on the severity and type of issue(s), and not the amount of issues
      • Target is to get close to a 4.7.1 RC by the end of the year
      • Two bug scrubs happening this week (see the Bug Scrubs reference in Reminders section above) that will give us an idea of what’s realistically close to being ready for a December release.
    • No immediate Release Lead for 4.7.1
    • Handbook reference for releasing minor versions

    4.7 Retrospective

    • We failed at getting the field guide and email to plugin dev out early though. We have aimed to have that out around beta 2 and usually end up getting it out around RC the last few releases.
    • We will post a general request for feedback on Make/Core to capture Retrospective input
    • We will review the feedback and then present it for discussion during the dev chat on December 21st and agree on action items on how we can improve in the future
  • Aaron Jorbin 9:05 pm on December 5, 2016 Permalink |
    Tags: 4.7, ,   

    WordPress 4.7 Field Guide 

    WordPress 4.7 is shaping up to be the best WordPress yet!  Users will receive new and refined features that make it easier to “Make your site, YOUR site”, and developers will be able to take advantage of 173 enhancements and feature requests added.  Let’s look at the many improvements coming in 4.7…

    RESTing, RESTing: 1, 2, 3

    The foundation for RESTful APIs has been in core since 4.4, and 4.7 sees the addition of Content Endpoints after a healthy discussion. We’ve defined four success metrics as part of the merge discussion and you can help by building themes and plugins on top of the API, using the API in custom development projects, and utilizing the API for a feature project, core features, or patches. So, dive in, start playing around, and let us know what you build!

    REST API Merge Proposal, Part 2: Content API


    It don’t mean a thing, if you ain’t got a theme

    No matter if you are building themes for public consumption, as a bespoke project for a major public company, or anything in between WordPress 4.7 has something to help you.

    Theming with Twenty Seventeen

    Video Headers in 4.7

    Starter content for themes in 4.7

    Visible Edit Shortcuts in the Customizer Preview

    Whitespace changes in navigation for 4.7

    Post Type Templates in 4.7

    New Post Type Labels in 4.7

    New Functions, Hooks, and Behaviour for Theme Developers in WordPress 4.7

    The Voyages of USS Media

    Two notable changes, enhanced PDF support in the media library and changes to the default fallbacks for image alt attributes, are explained in separate posts.

    Enhanced PDF Support in WordPress 4.7

    Improving accessibility of image alternative text in 4.7

    Media also received other exciting enhancements and bug fixes you should check out.

    Around the World

    The way users understand the words on WordPress are important and now users will be able to select their personal preferred language.

    User Admin Languages and Locale Switching in 4.7


    For Whom Customization Tolls

    The customize component will now support the ability to create pages within live preview during site setup; will have a faster, smoother, and more accessible navigation; will automatically persist your changes in the background while you browse your site and switch themes; and will let you fine-tune your site with custom CSS.

    Customizer Improvements in 4.7

    Customize Changesets Technical Design Decisions

    Changes to Customizer Sliding Panels/Sections in WordPress 4.7

    Extending the Custom CSS editor


    Reading, Writing and Teriffic

    Whether you’re creating content in the WordPress Admin or concerned about comment moderation, we’ve got updates that will be sure to please you.

    Editor changes in 4.7

    Comment “allowed” checks in WordPress 4.7


    The Foundation of WordPress

    For those who like to get “under the hood” of WordPress, we’ve got some improvements that will hopefully make your life easier.

    Changed loading order for current user in 4.7

    Multisite Focused Changes in 4.7

    Attributes for Resource Hints in 4.7

    wp_list_sort() and WP_List_Util in 4.7

    WP_Taxonomy in 4.7

    Fine grained capabilities for taxonomy terms in 4.7

    WP_Hook: Next Generation Actions and Filters

    Registering your settings in WordPress 4.7


    But Wait, There is More!

    Over 447 bugs, 165 enhancements, 8 feature requests, and 15 blessed tasks have been marked as fixed in WordPress 4.7. Some additional ones to highlight include:

    • Make media library searchable by file name (#22744)
    • Improved Custom Background Properties UI (#22058)
    • Hue-only Color Picker (#38263)
    • Fix Sections that .cannot-expand (#37980)
    • Allow Plugins to do Comprehensive Late Validation of Settings (#37638)

    Please, test your code. Fixing issues now, before 4.7 is released, helps you and helps millions of WordPress sites.

  • Helen Hou-Sandi 6:26 am on December 3, 2016 Permalink |
    Tags: 4.7   

    There is a quiet RC2 now available – it is a fair number of commits (50+), so please take a look through those and test as you can.

  • Nick Halsey 10:14 pm on November 30, 2016 Permalink |
    Tags: 4.7, ,   

    Customizer Improvements in 4.7 

    WordPress 4.7 has been the most active release on record for the customize component, with four major feature projects merging and shipping with 4.7 and over 90 tickets closed as fixed. This post summarizes the highlights of the user and developer-facing changes.

    4.7 Customizer Feature Projects

    Create pages within live preview during site setup

    Add new pages while building menus and setting a static front page; outline your site directly in the customizer.

    This project began with the ability to create posts and pages direction from the available menu items panel in the customizer, as originally proposed near the end of the 4.6 cycle:

    Feature Proposal: Content Authorship in Menus, with Live Preview

    Subsequent changes also added the ability to create new pages when assigning the front page and posts page in the Static Front Page section. Because this is now built into the core dropdown-pages customizer control, themes and plugins can also allow users to create new pages for their options instead of relying on existing content. The homepage sections in Twenty Seventeen include this new allow_addition parameter. Here’s how to register a dropdown-pages control supporting new pages:

    $wp_customize->add_control( 'featured_page', array(
    	'label'          => __( 'Featured Page', 'mytextdomain' ),
    	'section'        => 'theme_options',
    	'type'           => 'dropdown-pages',
    	'allow_addition' => true, // This allows users to add new pages from this dropdown-pages control.
    ) );

    Additionally, a proposal for term statuses was developed as a first step toward expanding the menus functionality to work for creating and previewing taxonomy terms in a future release (see #37915).

    Improvements to the Sliding Panels UI

    Customizer navigation is now faster, smoother, and more accessible.

    This project tackled a series of tickets focused on improving the usability of the “sliding panels” UI in the customizer controls pane. The first step was to refactor the section and panel markup so that sections and panels are not logically nested. This is the biggest internal change to the UI and has a dedicated post going into the details:

    Changes to Customizer Sliding Panels/Sections in WordPress 4.7

    This primary change resolved numerous problems with sections and panels not opening and closing properly, and eliminated situations where navigation to leave a section could become hidden. The next step was making section and panel headers “sticky” so that navigation is easier to access within long sections (such as for a menu); see #34343.

    Finally, hover and focus styling for navigation in the customizer has been updated to use the blue-border approach found elsewhere in core, including for the device-preview buttons in the customizer, in #29158. This completes a refresh of the customizer controls pane’s UI design that began in WordPress 4.3 with #31336. The core UI now uses the following consistent UI patterns in the customizer:

    • White background colors are used only to indicate navigation and actionable items (such as inputs)
    • The general #eee background color provides visual contrast against the white elements
    • 1px #ddd borders separate navigational elements from background margins and from each other
    • 15px of spacing is provided between elements where visual separation is desired
    • 4px borders are used on one side of a navigation element to show hover or focus, with a color of #0073aa
    • Customizer text uses color: #555d66, with #0073aa for hover and focus states on navigation elements

    Plugins and themes should follow these conventions in any custom customizer UI that they introduce, and inherit core styles wherever possible.

    Any custom sections and panels, as well as customizations to the core objects in plugins and themes, should be tested extensively to ensure that they continue functioning as intended with all of these changes in 4.7. It’s particularly important to ensure that things like the use of color match the core conventions so that the user experience is seamless between functionality added by plugins and core.

    Customize Changesets (formerly Transactions)

    Browse your site and switch themes more seamlessly within the customizer, as your changes automatically persist in the background.

    This project rewrote the internals of the customizer preview mechanism to make changes persistent. Each change made to a setting in the customizer is saved to a changeset (a new customize_changeset post type), facilitating future features such as scheduled changes, revisions, or saving and sharing drafted changes. Changesets also open the door to using the customizer to preview Ajax requests, headless sites, and REST API calls for mobile apps. In 4.7, changesets enable switching themes in the customizer without needing to decide between publishing or losing your customizations, as they’re automatically persisted in the background.

    For more details on changesets, check out the two dedicated posts:

    Customize Changesets (formerly Transactions) Merge Proposal

    Customize Changesets Technical Design Decisions

    Custom CSS

    Fine-tune your site and take your theme customizations to the next level with custom css in the customizer.

    #35395 introduced a user-oriented custom CSS option in the customizer. Now that the base functionality is in place, it will be further enhanced in #38707 in future releases. Read the feature proposal for details on the implementation and why it’s important for core:

    Feature Proposal: Better theme customizations via custom CSS with live previews

    There’s also a dedicated post that walks through the process of migrating existing custom CSS options in themes and plugins to the core functionality – be sure to follow those steps if your plugin or theme does custom CSS:

    Extending the Custom CSS editor

    Other Changes with Dedicated Posts

    4.7 features several other features deserving special attention. Read the posts for visible edit shortcuts (which expand the functionality of customizer partials), video headers (which extend the custom header feature), and starter content for more information:

    Visible Edit Shortcuts in the Customizer Preview

    Video Headers in 4.7

    Starter content for themes in 4.7

    Additional User-facing Changes

    With over 90 tickets fixed in the customize component in 4.7, we can’t cover everything here. But, here are a few more highlights:

    Improved Custom Background Properties UI

    #22058 introduces a more comprehensive and more usable custom background properties UI when a custom background is set up. There are now presets to control all of the detailed options at once, and the individual options are presented in a more visual way. Background size and vertical position are also now available as standalone options when using a custom preset.

    Theme developers should update their add_theme_support() calls for custom-background to specify the default size, vertical position, and preset to reflect their default background image CSS. Perhaps the most significant improvement here is the ability for users to easily set up fixed full-screen backgrounds – and the ability for themes to make that behavior default if desired.

    And even more…

    4.7 also:

    • Loads the frontend preview iframe more naturally, eliminating a lot of weirdness with JS running in an unexpected location and ensuring that JS-based routing will work (#30028)
    • Allows the search results page to be previewed, and any forms that use the GET method in general can now be submitted whereas previously they would do nothing when submitted (#20714)
    • Hides edit post links in the customizer by default. Plugins, such as Customize Posts, can restore the links if they make post editing available in the customizer (#38648), although the visible edit shortcuts should generally be used instead.
    • Shows a cursor: not-allowed for mouse users when hovering over external links in the preview, as these can’t be previewed
    • Officially removes support for the customizer in Internet Explorer 8, preventing users of this outdated browser from accessing the customizer at all (#38021)

    Additional Developer-oriented Changes

    Hue-only Color Picker

    #38263 adds a hue-only mode to the Iris color picker, wpColorPicker, and WP_Customize_Color_Control. Built for Twenty Seventeen’s custom colors functionality, the hue-only mode allows users to select a hue and saves the hue degree as a number between 0 and 359. To add a hue-color control:

    $wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'colorscheme_hue', array(
    	'mode' => 'hue',
    	'section' => 'colors',
    ) ) );

    As demonstrated in Twenty Seventeen’s custom colors strategy, the hue-selection strategy opens up a whole new world of possibilities for custom color options in themes. Rather than introducing numerous text and background color options and requiring users to adjust them to ensure that adequate color contrast is provided, themes can consolidate their color options into one or more hue pickers. Then, the corresponding use of hsl colors in CSS allows themes to define color patterns where users customize color hues without impacting the lightness of a color option, thereby preserving the designer’s use of proper contrast between text and background colors, and any use of color lightness for visual hierarchy. Check out the implementation in Twenty Seventeen for inspiration (including instant live preview).

    Fix Sections that .cannot-expand

    When creating custom customizer sections that, for example, display an external link but don’t actually expand to show section contents, the cannot-expand class can be added to the section title container to prevent JS events and CSS hover/focus styles from being applied. Be sure to also remove the tabindex="0" from the container if you copy the core code since your custom section shouldn’t be focusable if it can’t expand (and any contained links or buttons would be keyboard-focusable automatically). See #37980 for details.

    Allow Plugins to do Comprehensive Late Validation of Settings

    To account for custom subclasses of WP_Customize_Setting that don’t apply the customize_validate_{{$setting_id}} filter, this filter now will be applied when WP_Customize_Manager::validate_setting_values() is called. This ensures that plugins can add custom validation for every setting. For more, see #37638.


    Huge thanks to the 61 people (and counting) receiving props for the 120+ customize component commits in 4.7 (as of RC2): @westonruter, @celloexpressions, @afercia, @sirbrillig, @ryankienstra, @helen, @ocean90, @melchoyce, @bradyvercher, @folletto, @johnbillion, @delawski, @karmatosed, @georgestephanis, @dlh, @curdin, @valendesigns, @mattwiebe, @michaelarestad, @joemcgill, @sstoqnov, @lgedeon, @mihai2u, @coreymcollins, @stubgo, @utkarshpatel, @desrosj, @odysseygate, @johnregan3, @aaroncampbell, @mapk, @iseulde, @mrahmadawais, @vishalkakadiya, @sayedwp, @hugobaeta, @jonathanbardo, @jorbin, @tristangemus, @deltafactory, @kkoppenhaver, @seancjones, @presskopp, @Mista-Flo, @nikeo, @adamsilverstein, @lukecavanagh, @coffee2code, @peterwilsoncc, @presskopp, @pento, @Kelderic, @sebastian.pisula, @mckernanin, @FolioVision, @MikeHansenMe, @welcher, @cdog, @grapplerulrich, @iamfriendly, @flixos90.


  • Helen Hou-Sandi 8:49 pm on November 30, 2016 Permalink |
    Tags: 4.7,   

    Starter content for themes in 4.7 

    One of the hardest things for people setting up sites with WordPress for the first time is understanding what themes are and how a given theme can work for you, especially when there’s no content there to visualize. There are also significant gaps between local theme previews, screenshots, and .org previews. Even when there are easy-to-use site customization tools, it is difficult to figure out where to start and what things are going to be like.

    To help users along that path, 4.7 introduces the concept of “starter content” – theme-specific selections of content to help showcase a theme to users and serve as a starting point for further setup of new sites. Starter content works especially well in tandem with visible edit shortcuts, allowing users to not only see what content might work best where within a theme, but from there to be able to jump to building off of that base without having to initially spend time figuring out, say, which widgets areas map where.

    How it works

    Starter content is applied and displayed upon entering the customizer, with no changes appearing on the live site until customizer changes are explicitly saved and published. In 4.7, this initial view of a theme with starter content will only happen for “fresh sites” – new installs that have not yet had any posts, pages, widgets, or customizer settings updated. This state is indicated in the fresh_site option with a value of 1. The current limitation is in line with prioritizing initial site setup for this release, and allows for themes to begin implementing content and ensuring that there is a solid base before introducing more complicated logic and UI to “merge” starter content with existing content in a future release (#38624). That being said, if two themes in a given fresh site both have starter content, if the starter content from the first theme is applied and you make some changes to that starter content, when you switch to the second theme the starter content from that theme will override the starter content from the first theme only for the settings which have not been modified. Also remember that theme mods are always theme-specific, so starter content for theme switches will never be copied.

    Core provides a set of content that themes can select from (technical details below). These include a variety of widgets, pages, and nav menu items (including references for the pages), along with the ability to provide attachments, theme mods, and options. Any included images for attachments need to be from within a theme or plugin folder and cannot be loaded from an external URL. Twenty Seventeen will ship with starter content enabled; there are no plans to add the functionality to past default themes.

    How to use it

    Themes define a subset of core-provided starter content using add_theme_support() – let’s look at a breakdown of how Twenty Seventeen does things. In its setup function hooked to after_setup_theme, we see an array with collections of widgets, posts (pages), attachments, options, theme mods, and nav menus registered as the starter content. The customizer looks for this starter-content at after_setup_theme priority 100, so do make this call at that point or later:

    add_theme_support( 'starter-content', array( /*...*/ ) )


    Each widget area ID corresponds to one sidebar registered by the theme, with the contents of each widget area array being a list of widget “symbols” that reference core-registered widget configurations. Most default widgets are available (archives, calendar, categories, meta, recent-comments, recent-posts, and search), as well as text widgets with business hours (text_business_info) and a short prompt for an “about this site” style blurb (text_about). Themes should place widgets based on what works best in that area – for instance, business info in a footer widget of a business-centric theme, or a nicely styled calendar widget in the sidebar of a blog.

    Custom widgets can also be registered at the time of starter content registration or later filtered in, which will be more likely the case for plugins, as add_theme_support() for starter content will be overridden by any later calls.

    // Custom registration example
    add_theme_support( 'starter-content', array(
    	'widgets' => array(
    		'sidebar-1' => array(
    			'meta_custom' => array( 'meta', array(
    				'title' => 'Pre-hydrated meta widget.',
    			) ),
    // Plugin widget added using filters
    function myprefix_starter_content_add_widget( $content, $config ) {
    	if ( isset( $content['widgets']['sidebar-1'] ) ) {
    		$content['widgets']['sidebar-1']['a_custom_widget'] = array(
    			'my_custom_widget', array(
    				'title' => 'A Special Plugin Widget',
    	return $content;
    add_filter( 'get_theme_starter_content', 'myprefix_starter_content_add_widget', 10, 2 );

    Posts (Pages)

    Like widgets, core provides posts which can be referenced by symbols; all six currently in the core set are pages, but the starter content API can support various post types (including attachments, which are defined and handled separately). The symbols for the core-provided pages as of 4.7 are home, about, contact, blog, news, and homepage-section. The pages references by blog and news are both empty in the content area and are meant to be assigned as the page for posts (detailed with options below). Imported posts can further be used as post IDs when referenced using the symbol of the item within double curly braces, e.g. {{home}} for the static front page option.

    Posts, like widgets, are also easily customizable, either by overriding specific fields for a predefined item or by defining a new custom one entirely. The available fields are post_type, post_title, post_excerpt, post_name (slug), post_content, menu_order, comment_status, thumbnail (featured image ID), and template (page template name, as would be stored in post meta).

    // Overriding/supplementing a predefined item plus a custom definition
    add_theme_support( 'starter-content', array(
    	'posts' => array(
    		'about' => array(
    			// Use a page template with the predefined about page
    			'template' => 'sample-page-template.php',
    		'custom' => array(
    			'post_type' => 'post',
    			'post_title' => 'Custom Post',
    			'thumbnail' => '{{featured-image-logo}}',


    While attachments are post objects, they have special handling due to the sideloading of specified media. Media must be loaded from within the theme or plugin directory – external URLs are currently disallowed for performance reasons. The location of the media, either as a full file path or relative to the theme root, is indicated in the file array item, and some other post fields are available, with post_content mapping to description and post_excerpt to caption. Imported attachments can further be used by using their respective array keys as symbols used within double curly braces, e.g. {{featured-image-logo}} as the featured image (thumbnail) for a post. In the example below, an attachment is specified and used as the featured image for the about page.

    add_theme_support( 'starter-content', array(
    	'attachments' => array(
    		'featured-image-logo' => array(
    			'post_title' => 'Featured Logo',
    			'post_content' => 'Attachment Description',
    			'post_excerpt' => 'Attachment Caption',
    			'file' => 'assets/images/featured-logo.jpg',
    	'posts' => array(
    		'about' => array(
    			// Use the above featured image with the predefined about page
    			'thumbnail' => '{{featured-image-logo}}',

    Nav Menus

    Nav menus are also specially treated post objects. There are essentially two types of nav menu items – custom links, which require a title and url, and object references, which require type, object, and object_id, which can be a {{post}} symbolic reference.

    Options and Theme Mods

    Options and theme mods are more freeform and merely require a match for a name. Symbolic references to imported items are particularly useful here, such as for the page_on_front option and Twenty Seventeen’s multi-section homepage as stored in theme mods. Themes hosted on .org will likely be limited to theme mods and a subset of options; all other developers are encouraged to consider user experience and expectations first.

    What does this mean for themes?

    Core-provided content helps support a consistent preview experience across themes with high quality localized content, helping users understand how WordPress and that theme fit their needs. Theme authors are encouraged to select from core-provided content, but as is always the case with WordPress, starter content still has some flexibility, and will continue to mature as a feature over time.

    While theme review guidelines need to be finalized and documented, it is anticipated that themes being submitted to WordPress.org will be expected to select from core-provided content to promote consistency and to help keep the theme review process from becoming lengthier, with exceptions being made on a case by case basis. Themes being distributed outside of WordPress.org are not subject to the same review process; however, it is recommended that consistent user experiences be the primary consideration in how starter content is chosen and implemented.

    What’s next?

    Testing this feature with your theme or plugin does not require a fresh install every time – you can set the fresh_site option to 1 using the tool of your choice, such as wp-cli or phpMyAdmin. Do note that content merging logic has not been tackled so you may not quite get the exact same effect as a truly fresh install; however, since all of the changes are held in a customizer changeset and are not otherwise live on the site, there is no data loss, unless you save and publish the starter content overrides of course.

    In the future, all sites should be able to live preview new themes in ways that really showcase that theme’s capabilities, whether that’s with no content made yet or with a lot of existing content to work into the preview. This will take a lot of consideration around user expectations for content merging, and should be tackled as its own feature. There are also potentially interesting extensions such as UI for users to select from sets of content or selectively accept/reject staged changes.

    And finally, to best align preview experiences in various places, theme previews on .org should also leverage starter content. Helping hands are needed here – please ping me (@helen) in Slack should you be interested!

    • Luke Cavanagh 8:55 pm on November 30, 2016 Permalink | Log in to Reply

      Thanks for sharing.

    • Madalin Tache 9:05 pm on November 30, 2016 Permalink | Log in to Reply

      That’s a really good idea! Looking forward to it!:)

    • Hardeep Asrani 9:08 pm on November 30, 2016 Permalink | Log in to Reply

      That’s gonna be a game changer for themes. 🙂

    • t-p 11:39 pm on November 30, 2016 Permalink | Log in to Reply

      To be able to live preview new themes sounds awesome 🙂

    • WPDevHQ 11:40 pm on November 30, 2016 Permalink | Log in to Reply

      Awesome news for themes.

      Will this be carried over to WordPress.org theme preview or does that not work as a `fresh_site`?

    • Omaar Osmaan 11:57 pm on November 30, 2016 Permalink | Log in to Reply

      Awesome thank you!

    • evisiontheme 9:21 am on December 1, 2016 Permalink | Log in to Reply

      Really, great idea. Thanks for the sharing it. We look forward it soon.

    • NateWr 9:39 am on December 1, 2016 Permalink | Log in to Reply

      Looks great! I suppose this has been discussed, but is there any plan to support post meta in a more generic fashion? I’m thinking a key for `post_meta` which can itself be an assoc array with a key/value map. This could be useful for previewing data from plugin custom post types which rely more heavily on post meta.

      • Helen Hou-Sandi 3:16 pm on December 1, 2016 Permalink | Log in to Reply

        Untested at the moment, but I believe this is already technically possible, just requires some more hoop jumping at the moment in the form of having to filter it in using get_theme_starter_content as opposed to being able to specify it during initial registration. That is the case for plugins as it is though, so it’s not really that much of a hoop. So to do that, you would want to use a meta_input arg with the definition of that post, the same way post_title can be specified. Can you let me know if it works?

        • NateWr 9:06 pm on December 6, 2016 Permalink | Log in to Reply

          Hey thanks Helen. I missed this reply in my notifications so just seeing it now. I’ll try to give this a go in the next couple weeks and let you know.

    • Mahesh Waghmare 9:51 am on December 1, 2016 Permalink | Log in to Reply

      +1, Its nice enhancement for theme developer.

    • Ahmad Awais 2:57 pm on December 1, 2016 Permalink | Log in to Reply

      Thanks a lot Helen and all the contributors for making this happen. It’s a huge deal for me and my clients.

    • rheinardkorf 11:15 pm on December 5, 2016 Permalink | Log in to Reply

      Love it! Handy for developers and those looking for themes. Nothing more annoying than previewing a theme with current standard content. Great improvement.

    • Armando Duran 12:46 am on December 7, 2016 Permalink | Log in to Reply

      I tried this on an existing install. For a moment I thought that the fresh_site option would be there after upgrading to 4.7 but then I realized that after adding the option manually on the DB, starter content was there!

      love this feature … and the new 4.7 version of course!

    • Volkv 9:50 am on December 7, 2016 Permalink | Log in to Reply

      But it doesnt work right for me. After fresh 4.7 install I got 20/17 theme loaded WITHOUT any starter pre-loaded content – only with default widgets. Starter changes appears ONLY after I click on customizer button.

      Same behavior with my own theme. Is it bug or what am I doing wrong?

    • Mal 11:06 am on December 7, 2016 Permalink | Log in to Reply

      It doesn’t work for me.

      I just installed WordPress 4.7 and put this in the functions.php file:

      function my_setup() {
      	add_theme_support( 'starter-content', array(
      		'options' => array(
      			'test123' => 'test',
      	) );
      add_action( 'after_setup_theme', 'my_setup' );

      The frest_site option was added to the database automatically with value of 1.

      In footer.php when I run var_dump(get_theme_starter_content()); I get the correct result but when I run var_dump(get_option('test123')); right next to it I’m only getting false.

      I tried to debug that but I can’t figure out what this is supposed to do preg_match( '/^{{(?P.+)}}$/', $value, $matches ) in import_theme_starter_content()?

      I also noticed that all arrays need to be serialized which was kind of unexpected:

      add_theme_support( 'starter-content', array(
      	'options' => array(
      		'test123' => 'test',
      		'test1234' => maybe_serialize( array(
      			'something' => 'test',
      		) ),
      ) );
  • Andrew Rockwell 6:47 pm on November 30, 2016 Permalink |
    Tags: 4.7,   

    Week in Core, November 23 – 29, 2016 

    Welcome back the latest issue of Week in Core, covering changes [39341-39379]. Here are the highlights:

    • 39 commits
    • 30 contributors
    • 81 tickets created
    • 3 tickets reopened
    • 31 tickets closed

    Ticket numbers based on trac timeline for the period above. The following is a summary of commits, organized by component.

    Code Changes

    Build/Test Tools

    • Build: Remove fsevents from npm-shrinkwrap.json [39368] #38657
    • Add an extra WP_Error assertion when testing a valid user activation key. This provides a better failure message if the assertion does fail. [39364] #38716
    • When testing the output of wp_list_pages(), use a known and fixed date for each post so the tests don’t fail when the date changes between the beginning and end of a test. [39363] #38688
    • Git: Prevent untracked files from being ignored by git in bundled themes. [39362] #27207, #38779
    • Add npm-shrinkwrap.json to 4.7. [39358] #38657

    Bundled Theme

    • Twenty Seventeen: Add textdomain for starter content attachment titles. [39374-39373] #38981
    • Twenty Seventeen: Ensure edit button label displays properly in other languages [39341] #38876


    • Fix regression in ability to hide fields for advanced menu properties in nav menu item controls. [39379-39378] #34391, #38952
    • Fix regression in ability to create submenus for nav menus via drag and drop. [39377-39376] #34391, #38948
    • Fix logic for previewing the URL for nav_menu_item settings for terms and post type archives. [39365] #38114, #38945
    • Refactor logic for updating custom_css posts by introducing wp_update_custom_css_post() function and renaming update filter. [39350] #35395, #38672
    • Clean up docs and code style for customize changes in 4.7. [39345] #37770, #38908


    • Correctly remove security attribute from iframes in IE 10 and IE 11. [39347] #38694


    • Git: Ignore patch related files, so they can’t be accidentally committed. [39361] #38727
    • SVN: Ignore patch related files, so they can’t be accidentally committed. [39360] #38727
    • Docs: Add a missing changelog entry for the point where the $tagnames parameter was added to get_shortcode_regex(). [39351] #38914



    • WP_Hook: Re-initialize any actions added directly to $wp_filter by advanced-cache.php. [39370-39369] #38929


    • Add test for creating a comment with an invalid post ID. [39375] #38816, #38991
    • Add tests for empty or “no-op” updates. [39371] #38700, #38975
    • Special case the “standard” post format to always be allowed. [39353] #38916
    • Allow unsetting a post’s password. [39352] #38919
    • Add support for comments of password-protected posts. [39349] #38692
    • Always fire the rest_insert_* actions after the related object is updated or inserted. [39348] #38905
    • Make JS Client store schema in session storage. [39344] #38895
    • Allow unsetting of page templates in update requests. [39343] #38877
    • Update “resource” strings to use the appropriate nouns. [39342] #38811


    • Fix logic for previewing the URL for nav_menu_item settings for terms and post type archives. [39366] #38114, #38945
    • Theme starter content: Add support for featured images and page templates. [39346] #38615


    • Fix the styling of notices generated by the editor UI. [39367] #38917

    Thanks to @mor10, @adamsilverstein, @afercia, @azaozz, @celloexpressions, @danielbachhuber, @davidakennedy, @dd32, @delawski, @DrewAPicture, @flixos90, @georgestephanis, @helen, @iseulde, @jnylen0, @joehoyl, @joehoyle, @johnbillion, @karmatosed, @keesiemeijer, @lucasstark, @nacin, @ocean90, @odysseygate, @pento, @rachelbaker, @ramiy, @swissspidy, @tg29359, @westonruter, and @xrm for their contributions!

  • David A. Kennedy 12:22 am on November 29, 2016 Permalink |
    Tags: 4.7, , ,   

    Theming with Twenty Seventeen 

    In 4.7, WordPress gets a new default theme: Twenty Seventeen. Like all default themes, it’s easily customizable for users and developers. This post will cover developer features and a few tricks when customizing the theme.

    Of note

    Override enqueued styles and scripts

    With the use of get_theme_file_uri, introduced in 4.7, Twenty Seventeen lets child themes override styles and scripts with ease. For example, if you want to replace the theme’s global.js file, you can do so by including the same file in your child theme in the same path.


    Twenty Seventeen includes a handful of filters, all of which are documented in line in the code.

    Content width

    The value is filterable in the event a child theme needs to change it.

    function childtheme_content_width( $content_width ) {
        if ( twentyseventeen_is_frontpage() ) {
            $content_width = 960;
        return $content_width;
    add_filter( 'twentyseventeen_content_width', 'childtheme_content_width' );

    Custom header settings

    Like past default themes, Twenty Seventeen filters the arguments for add_theme_support( 'custom-header' );. These can be changed in a child theme. Here, we’ll add flex-width to the current args.

    function childtheme_custom_header_args( $args ) {
        $args['flex-width'] = true;
        return $args;
    add_filter( 'twentyseventeen_custom_header_args', 'childtheme_custom_header_args' );

    Header video settings

    The theme changes the default provided by Core, but that can be modified by a child theme. Here, we change the text on the button in a child theme:

    remove_filter( 'header_video_settings', 'twentyseventeen_video_controls' );
    function childtheme_video_controls( $settings ) {
    	$settings['l10n']['play'] = '__( 'Play my awesome video', 'childtheme' );
    	$settings['l10n']['pause'] = '__( 'Pause my awesome video', 'childtheme' );
    	return $settings;
    add_filter( 'header_video_settings', 'childtheme_video_controls' );

    Front page sections

    Twenty Seventeen uses the Customizer to add sections to the front page. These are filterable with the twentyseventeen_front_page_sections filer. They can changed like so:

    function childtheme_front_page_sections() {
    	return 6;
    add_filter( 'twentyseventeen_front_page_sections', 'childtheme_front_page_sections' );

    With 6 being a new number there. In this way, the number of sections can be adjusted in a child theme.


    One of the theme’s most notable behind-the-scenes features, the use of SVGs means better accessibility for icons, they look great on any device and they’re easier to customize.

    First, the list of social link icons is filterable, so child themes can change it.

    function childtheme_social_links_icons( $social_links_icons ) {
        $social_links_icons['mysocialsite.com'] = 'mysocialsite';
        return $social_links_icons;
    add_filter( 'twentyseventeen_social_links_icons', 'childtheme_social_links_icons' );

    All of Twenty Seventeen’s icons are decorative in nature. But if a child theme wanted to include an icon that needed to be described in an accessible way, it can thanks to built-in options.

    These examples are documented in the code itself. However, for example:

    Using a title:

    <?php echo twentyseventeen_get_svg( array( 'icon' => 'arrow-right', 'title' => __( 'This is title', 'childtheme' ) ) ); ?>

    Another example with title and desc (description):

    <?php echo twentyseventeen_get_svg( array( 'icon' => 'arrow-right', 'title' => __( 'This is title', 'childtheme' ), 'desc' => __( 'This is longer desc', 'textdomain' ) ) ); ?>

    For more information on SVG accessibility, see Using ARIA to enhance SVG accessibility.

    Custom Colors

    Like other default themes, this one comes with some color options so you can make the theme your own. Twenty Seventeen uses saturation to create a custom color scheme that will look great. That saturation level can be adjusted, like so:

    function childtheme_custom_colors_saturation() {
    	return 25;
    add_filter( 'twentyseventeen_custom_colors_saturation', 'childtheme_custom_colors_saturation' );

    So the lower the number there, the more muted a color appears, and the higher it is, the more intense a color becomes.

    You can also add new CSS to the existing CSS output for custom colors.

    By adding a filter, child themes can add additional selectors onto the custom color scheme CSS. Like so:

    // Add child theme selectors for color schemes.
    function dynamic_seventeen_custom_colors_css( $css, $hue, $saturation ) {
    	$css .= '
    	.colors-custom .content-menu > article:not(.has-post-thumbnail),
    	.colors-custom .content-menu > section:not(.has-post-thumbnail) {
    		border-top-color: hsl( ' . $hue . ', ' . $saturation . ', 87% ); /* base: #ddd; */
    	return $css;
    add_filter( 'twentyseventeen_custom_colors_css', 'dynamic_seventeen_custom_colors_css', 10, 3 );

    Enjoy customizing Twenty Seventeen and happy theming!

    • djsteveb 1:30 am on November 29, 2016 Permalink | Log in to Reply

      glad to see ” all of which are documented in line in the code.”
      thanks for the tips and early warnings!

      I am sure there will be many that love the video header and many that calculate the waste of this. Without having looking at the code and such, but having some experience with video and wordpress I must ask..

      Is there an option to easily have the video auto play or not play, and instead show a thumbnail with a play button?

      Has someone gotten code to make the video auto-pause when scrolled out of view? I looked hard for this and asked for help in doing that with the flv-player plugin – but never got it working – hopefully others have figured it out by now.

      Is the video going to be self hosted / in the install files for default wordpress or is it hot linked from elsewhere? One way equals bloat for installs, the other sacrifices privacy and puts our page load speed in the hands of third parties.

      Are there options for having the video not load at all in different scenarios like cell phone screen size or 2g data connection?

      Would love to see an option to have a gif (converted to webm perhaps) showing that there is a video to be played – click to download / stream / play – otherwise the bandwidth is saved for the end user.

      Has anyone gotten anything like src set for video yet? Last version of wordpress has some auto magic for different image sizes for different screens right? Does this now work with video?

      One theme I play with has a slider that pulls an mp4 hi rez when screen size is large enough, and then chooses to load a webm version if it detects a smaller screen size – would love to see this (or similar) options in wp core like how images are dealt with.

      anyhow, love to see WP embracing video more by default – it’s great, but comes with some challenges and limitations – that I hope are mostly solved in the future. Also glad to see a focus on having the default themes made with developing in mind for the end users.. I disagree that all default themes are easy to manipulate for end users, certainly 2013 theme and those before were.. the last couple not so much imho.

      thanks to all those who have been and are working on this! the default theme is seriously important for so many reasons!

    • tobifjellner 7:09 am on November 29, 2016 Permalink | Log in to Reply

      Hi. It seems you pasted the same image four times, when attempting to illustrate the saturation setting.

  • Brady Vercher 10:25 pm on November 26, 2016 Permalink |
    Tags: 4.7, custom-header, , ,   

    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 header images, but with motion. With that in mind, they play automatically, 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 UI in the customizer 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 URL to a YouTube video.
    • Enables support for Selective Refresh for header images.

    Displaying the header

    In previous versions of WordPress, generating the image tag 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 accessibility. Core does not apply any CSS to the button in order to make 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 filter.

    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 iframe 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 plugin, take a look at how this plugin registers support for Vimeo.

    New functions and hooks

    • 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.


    • 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.
    • Paal Joachim Romdahl 12:15 am on November 29, 2016 Permalink | Log in to Reply

      Thank you for a very good overview!

    • Guido Scialfa 12:36 am on December 2, 2016 Permalink | Log in to Reply

      Probably I’m doing something wrong but the height and width must be set for the custom-header or the frame will not be visible because of the ‘width’ and ‘height’ defined are 0.

      Also, it is right that if i set the header image that is for example 640×480, the video will get the same size? Because even if I set the width and height for the custom-header I get the resolution of the image.

      I’m so sorry, most probably this isn’t the right place to ask for this.

      Anyway, thank you for this new great feature 🙂

    • AH-WebDesign.net 1:06 am on December 7, 2016 Permalink | Log in to Reply

      I’m looking forward to implementing the video header in my theme. Thanks for the detailed documentation.

    • Gioni 3:20 pm on December 7, 2016 Permalink | Log in to Reply

      Yeah, that’s a great feature to reduce conversion rate and increase bounce. I hate those automatically started videos and will never use them in my projects and on my sites. When I see such useless, annoying and resource consuming video on the site I just close it or jump to inner page.

    • tremmal 9:05 am on December 9, 2016 Permalink | Log in to Reply

      Would be nice to implement volume control in header video. Standard volume should be 0, zero, but the user should be able to adjust it.

compose new post
next post/next comment
previous post/previous comment
show/hide comments
go to top
go to login
show/hide help
shift + esc
Skip to toolbar