Make WordPress Core

Tagged: themes Toggle Comment Threads | Keyboard Shortcuts

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

    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.

    • Bonaldi 7:46 pm on December 30, 2016 Permalink | Log in to Reply

      I agree, the user should be able to adjust the volume. Missing.

    • wpweaver 9:18 pm on January 3, 2017 Permalink | Log in to Reply

      I duplicated 2017’s BG parallax header video look, but now I’m going crazy.

      I’d like a video just in the header area – like a traditional wide and tall banner image – but a video (YouTube). Is there a way to make the video size responsively instead of vertical or horizontal letterboxing? If you get the size of the video just right, it will match the corresponding image, but then letterboxes if you resize the page.

      Fitvids does not seem to be able to fix it either.

      As usual with new WP features, there is no really good documentation with real world examples. So far, 2017 seems to be it. It is just so hard to read code to try to figure out what really is going on.

      • wpweaver 1:31 am on January 4, 2017 Permalink | Log in to Reply

        When there’s a video displayed in the header as a replacement for the header, you need to make the .wp-custom-header div position:relative;height:0;padding-bottom:aspect-ratio %; and then make the .wp-custom-header iframe div absolute, top,bottom: 0; height,width:100%.

        The aspect ration % is the width / height (e.g. 9/16 for 56.25%). Getting the aspect ratio % right in the .wp-coustom-header div is critical to avoid black letterbox bars. If the matching image picture has the same aspect ratio as the video, then all is well. Otherwise, you may want to set the height and width with a ‘header_video_settings’ filter to the proper aspect ratio. Note that you don’t really need the real size and width here, just the aspect ratio: 16 for the width, 9 for the height, for example.

    • abain 7:04 pm on January 6, 2017 Permalink | Log in to Reply

      Thank you for the review. Do you know how I can enable audio for a YouTube URL in the Header (for my Front Page)? I understand on Twenty Seventeen the audio is muted by default. I would like to get specific steps on how I can enable the sound. Thanks!

    • danibaba 10:20 pm on January 14, 2017 Permalink | Log in to Reply

      After installing Twenty Seventeen theme on our website, at Costumize -> Media Header section I see this message: “This theme doesn’t support video headers on this page. Navigate to the front page or another page that supports video headers.”
      How is it possible to enable video header support at 2017 or other themes?

  • Nick Halsey 7:18 pm on November 10, 2016 Permalink |
    Tags: , , , themes   

    Visible Edit Shortcuts in the Customizer Preview 

    #27403 added visible edit shortcuts to the customizer preview, making it easier to see which elements of your site are editable in the customizer and how to edit them. Here’s a demo with Twenty Fifteen (note that the ability to toggle icons off has since been removed):

    Implementation: Selective Refresh Partials

    Visible edit shortcuts are an extension of the existing “shift-click-to-edit” functionality built into customizer partials. Partials are sections of the front end of the site, in the customizer preview, that are associated with customizer settings. When settings change, their associated partials are selectively refreshed via an Ajax call without reloading the entire preview. Partials are to the customizer preview what controls are to the customizer editing pane: a visual representation of a setting.

    Buttons are now injected into partials within the preview to expose this relationship visually and to users of all input modes. However, the role of the customizer preview is to provide an accurate representation of the frontend of the site as it’ll appear once changes are published. Accordingly, visible edit shortcuts pose a challenge as they have the potential to significantly hamper the preview-ability of the preview.

    To balance between discoverability and providing an accurate preview, the initial core iteration showed a flash of the buttons when the preview first loads, then hid them. To show the shortcuts, or to toggle them on and off, you could click/tap anywhere in the preview (except on a link or button). Keyboard users had a screen-reader-text button (visible on focus) to toggle the shortcuts on and off. This functionality was removed in [39131] and icons are currently persistently visible when customizing but hidden when the controls are collapsed, and supplemental usability testing validated this decision.

    Background & Prior Implementations

    Shift-click to edit an element in the customizer preview was first implemented with the widget customizer project in WordPress 3.9. Visual approaches to exposing this functionality were explored, but left for a future release. Selective refresh was also first proposed, and put on hold pending development of the concept.

    The first core implementation of selective refresh came with menu management in the customizer in WordPress 4.3. Menus include shift-click-to-edit on a per-menu-item bases, further demonstrating the powerful potential of associating portions of the customizer preview with their associated settings and controls.

    WordPress.com currently supports a similar feature with visible edit icons in the customizer. This approach serves as the inspiration for the final UI being introduced in core, with additional UX adjustments and a complete rewrite of the implementation to make it compatible with as many themes as possible.

    Adding Theme Support

    Theme support for this feature is all about supporting selective refresh, which was added in WordPress 4.5. In some cases, a small amount of additional CSS will be required to ensure that the shortcuts are positioned properly. Edit shortcuts will be enabled by default for all themes, but are contingent on themes supporting selective refresh.

    Selective Refresh for Widgets

    See the post from WordPress 4.5 for adding support for selective refresh for widgets. In most cases, add_theme_support( 'customize-selective-refresh-widgets' ) is the only requirement:

    Implementing Selective Refresh Support for Widgets

    Selective Refresh for Menus

    Menus support selective refresh out of the box unless: a custom nav menu walker is used, the echo argument is false, or wp_nav_menu isn’t used. In those cases, you’ll need to add support directly. Some themes may still be missing full support for selective refresh of menus, which has been enabled by default since WordPress 4.3.  Reference the post for details, but note that it predates the core implementation of an API for selective refresh:

    Fast previewing changes to Menus in the Customizer

    Selective Refresh for Custom Options

    Custom logo (since 4.5) and header video (since 4.7) support selective refresh automatically if you use the core features via add_theme_support. Other core options such as the site title and tagline or header images can support selective refresh if you register partials for them and set their settings’ transport argument to postMessage. Here’s an example from Twenty Fifteen:

    $wp_customize->get_setting( 'blogname' )->transport        = 'postMessage';
    $wp_customize->get_setting( 'blogdescription' )->transport = 'postMessage';
    $wp_customize->selective_refresh->add_partial( 'blogname', array(
    	'selector' => '.site-title a',
    	'render_callback' => 'twentyfifteen_customize_partial_blogname',
    ) );
    $wp_customize->selective_refresh->add_partial( 'blogdescription', array(
    	'selector' => '.site-description',
    	'render_callback' => 'twentyfifteen_customize_partial_blogdescription',
    ) );

    Where the render callbacks call bloginfo( 'name' ); and bloginfo( 'description' ); For more details on adding support for selective refresh for custom theme options, reference the official customizer documentation.

    Support in Default Themes

    Twenty Eleven through Sixteen support selective refresh as of WordPress 4.5, and also support edit icons for most of their features as a result. Twenty Fourteen and Sixteen require a few very minor positioning tweaks to ensure that all of the icons are visible. This is typical of what most themes could expect needing to add.

    Twenty Seventeen will be a great showcase for this new functionality, as the first theme to ship natively with selective refresh support and with visible edit shortcuts. A few additional adjustments in this new theme will ensure that every option can be previewed with selective refresh and provides visible edit shortcuts where appropriate.

    Limitations & Future Iterations

    The biggest limitation of the current approach is that implementation is entirely dependent on themes supporting it. However, unlike with many other theme-supported features, there is no add_theme_support for visible edit shortcuts. Where themes are already using selective refresh, shortcuts will be available out of the box in WordPress 4.7. To add theme support for edit shortcuts, themes need to add theme support for selective refresh, another newer customizer feature that allows the customizer preview to update granularly. Selective refresh provides superior user experience to the default refresh behavior because the preview context is not lost when changes are made.

    Edit shortcuts currently rely on the presence of selective refresh partials for every setting that needs an icon. Some settings may be previewed exclusively with JavaScript via postMessage. Icons also aren’t needed for every option; for example, layout or color options are broader than a specific area of the site, so they aren’t associated with a particular edit icon in the preview. In the future, a structured JavaScript API for partials in the customizer preview could facilitate adding icons to JS-previewed settings that don’t use selective refresh.

    Visible edit shortcuts are also the first step toward exploring the potential to edit elements of a site directly within the customizer preview. For this to be fully investigated, it’s imperative that a majority of themes and customizer option support selective refresh so that areas of the preview are associated with the appropriate customizer settings and so that context-disrupting full page reloads can be minimized.

    Contributors & Call for Help

    @sirbrillig led development of the feature for core based on the equivalent feature on WordPress.com. Core props went to @sirbrillig, @mattwiebe, @celloexpressions, @melchoyce, @westonruter, and @afercia. Thanks to everyone who has contributed so far!

    Now, your help is needed! Here’s what you can do to make this feature shine in WordPress 4.7:

    • Theme authors: add support for selective refresh to your themes. Start with widgets and make sure it’s working for menus, then make sure you’re using the core custom logo feature. Then, add selective refresh to the site title and tagline, header images, and any custom options with associated regions on the frontend.
    • Theme authors: adjust icon positioning in your theme’s CSS. You can add styles to.customize-partial-icon button to adjust all icons, and scope that to a specific container or even .customize-partial-icon-setting_id to adjust a particular edit icon. Note: these were updated with [39136].
    • Everyone: test edit shortcuts with your current theme with WordPress 4.7 Beta 1 (or newer). Most themes should be able to support them on widgets, menus, and logos with minimal effort. Contact your theme’s developer with any bugs or missing edit icon support, refer them to this post, and ask them to add support for visible edit shortcuts.
    • Everyone: test as many themes as possible and look for anywhere the shortcuts don’t display as expected, or at all. Contact the theme author with your findings, refer them to this post, and ask them to improve support for visible edit shortcuts in their themes.
    • Brad Markle 1:58 pm on November 30, 2016 Permalink | Log in to Reply

      Hi Nick! I sure wish you guys had this feature 6 months ago! I did quite a bit of work implementing similar “visible edit shortcuts” in a group of themes I help manage.

      If I need to disable this new feature within the Customizer, is the correct approach to toggle the customize-partial-edit-shortcuts-shown / customize-partial-edit-shortcuts-hidden classes within the body?


      • Brad
    • Luke Cavanagh 10:17 pm on November 30, 2016 Permalink | Log in to Reply

      Solid feature improvement.

    • AJ Clarke (WPExplorer.com) 7:02 am on December 12, 2016 Permalink | Log in to Reply

      I have an issue with the selective refresh icon not working after the theme mod is altered for the first time – https://cl.ly/3A3b1e3S1u12 – when you first load the Customizer you can click the icon and it goes to the correct section but after the partial refresh the icon is not clickable anymore (no errors in the console).

      Is there an argument that can be used using $wp_customize->selective_refresh->add_partial to disable the icon for the specific partial?

      Thanks!! Besides this bug, it is a nice feature!

      To add..doing shift+click on the element always works.

      • AJ
    • AJ Clarke (WPExplorer.com) 7:41 pm on December 29, 2016 Permalink | Log in to Reply

      Yes that fixes it! Thank you so much for the reply Nick.

      Happy Holidays,

    • AJ Clarke (WPExplorer.com) 1:54 am on January 11, 2017 Permalink | Log in to Reply

      I’ve noticed when adding a selective_refresh partial that uses the_content() it always returns empty. You can test it easily by using ‘render_callback’ => ‘the_content’. Is this a limitation of the Customizer done on purpose? Thanks!

    • scamartist26 4:51 pm on January 16, 2017 Permalink | Log in to Reply

      Is there a way to remove these icons? On my personal, and heavily widgetized theme I find it as a big distraction.

    • cramdesign 3:15 pm on January 17, 2017 Permalink | Log in to Reply

      Is there not a way that built in WordPress functions (get_bloginfo, wp_nav_menu, etc) could have selective refresh already baked in?

  • Nick Halsey 5:36 pm on October 11, 2016 Permalink |
    Tags: , , , , themes   

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

    When people ask “why WordPress?”, some of the most common answers center around flexibility for users of all kinds, whether they’re building their sites primarily through code or UI. Let’s take the story of a user who does a little of both – we’ll call her Becky.

    Becky is a pretty savvy user. She knows that you’re supposed to make child themes instead of hacking on a theme directly, because updates can wipe out your changes. She found that out the hard way when she first started using WordPress – she hardly knew what CSS or PHP were, but she knew there was a theme editor in the admin and that she could make tweaks to colors or remove the author byline pretty easily without having to figure out this FTP stuff. Later on, most colors could be changed with the customizer so having a child theme just to remove an author byline seemed like overkill, but it was certainly better than having it reappear every time her site updated, especially with auto updates turned on.

    After a couple years with the same theme on her personal site, Becky felt it was time to change things up. She was pleasantly surprised to find some new features that made getting a theme set up a lot easier, especially when live previewing them. Still, though, that pesky author byline remained, and since her last child theme copied a template to get rid of the byline, she would have to set up a whole new one to do it again. Then Becky found an “Edit CSS” option and realized she could hide things using CSS without having to go through the entire child theme process. Now, it turns out that those CSS tweaks didn’t come with live previewing, and that functionality was provided by a certain plugin, but Becky got what she needed to get done a lot faster than she would have otherwise, and ended up with the site she wanted.

    This isn’t one specific story, but it is a combination of user stories many have heard, witnessed, or even personally experienced. You could replace Becky with @helen and it would be 100% accurate. The theme editor is a dangerous but useful entry point to more deeply customizing your site – rather than outright removing it and cutting off that introduction not just to WordPress code but to the concept of web development at large, why not provide a far safer and more user-friendly alternative? This post will explain why custom CSS with live previewing is valuable for WordPress and propose an implementation for inclusion in 4.7.

    Proposed solution: Custom CSS with live preview

    When bridging the gap between advanced user and beginning developer, desired changes are typically visual tweaks, such as changing a font size or hiding something, that are theme-specific. These sorts of changes should not require that users take risks editing live files that might white screen their sites or jump immediately into developer-facing tasks such as using FTP. Therefore, the scope of this feature has been defined as a custom CSS editor that leverages the customizer for a user-friendly live preview experience. This live preview allows for users to try various tweaks to a theme before saving and setting their changes live.

    There are hundreds of thousands (if not millions) of users making use of custom CSS plugins or other themes/plugins that have custom CSS capabilities, and the frequent suggestion of CSS fixes in support forums justify a core need for this functionality. When plugins and themes interact in unexpected ways, CSS snippets are often an efficient solution to fixing the particular problem on particular sites.

    The CSS editor takes inspiration from the many plugins offering similar solutions, but with an updated approach that offers instant live previewing in the customizer. The proposal for 4.7 looks like this:


    Notably, previewing CSS in the customizer allows the site to be navigated and previewed on different sized devices by leveraging existing core features, allowing users to visualize the impact of their changes across their site. Error messages are shown for common syntax mistakes to help users ensure that their CSS is formatted properly before saving.

    In future releases, the interface can be iterated on to further improve usability. The long-term design vision provides functionality such as revisions, syntax highlighting, and in-preview selector helpers, and can be implemented iteratively over time (click through for the full version):


    CSS would be stored in a custom post type (without admin UI), with a post stored for each theme. The editor would be used to supplement and override theme styles rather than editing them directly, as users have long been advised that directly editing files may lead to lost changes during updates. Instead, custom CSS safely stays available through updating and switching themes, starting fresh for each new theme. Projects such as customize changesets (#30937) and revisions for customizer settings (#31089) would bring future enhancements to this feature and further leverage the opportunities that come with storing the data in post objects.

    This is proposed as core functionality rather than remaining as plugin territory because it is designed as the first step toward a next generation of the existing theme editor in core, with a more refined feature set and safer, more user-oriented focus. The theme editor is not proposed to be removed at this time, though with the introduction of this feature it likely makes sense to introduce more friction before accessing the editor (#31779).


    To improve the user experience further, it is critical that a link to documentation and resources for learning CSS be included with useful help text. This could initially be the “CSS” codex page but would ideally live on a user or developer handbook of some sort eventually (perhaps the theme developer handbook?). This help text must be much more succinct than the help tab on the existing theme editor, conveying what CSS is, where to learn about specific rules, and explaining that it’s specific to each theme in only a few lines.

    Help is needed to create a resource for using custom CSS in WordPress, and locate it on WordPress.org. There are some related resources on make/training and WordPress.com has a good introductory page that they may be willing to contribute. Translated versions will eventually be needed as well. If anyone is interested in improving this aspect of the feature, which will presumably live on WordPress.org, please comment on this post.

    Security, Capabilities, and Multisite

    While the proposal includes basic validation, it is not possible to fully sanitize CSS. For this reason, a new meta capability will be introduced for managing css, unfiltered_css. By default, this is mapped to the unfiltered_html capability.

    Site administrators on multisite networks do not have the unfiltered_html capability by default. A plugin that remaps unfiltered_css to a different capability can be created to provide this access on multisite, where custom CSS is especially useful given the need to restrict the number of themes and child themes in the network. This is an area of potential evolution over time.

    Related Customize API Improvements

    There are a couple of customizer API improvements introduced as part of the implementation of custom CSS in the customizer. A new “Code Editor” customizer control (WP_Customize_Code_Editor_Control) is used for the CSS editor and can also be utilized in plugins and elsewhere in the future. It currently handles line numbers and basic code styling, and will eventually add enhancements such as syntax highlighting.

    Additionally, the WP_Customize_Section class has a new “description_hidden” parameter, which locates the section description in the section header behind the help icon toggle (“?”), functioning in the same manner as the customizer panel descriptions.


    @johnregan3 is leading development of this project, based on initial work by myself (@celloexpressions). @folletto is leading design efforts, with a focus on the long-term growth of the feature for maximum usability.

    The implementation takes inspiration from many of the numerous plugins and services that implement custom CSS, specifically including:

    • Simple Custom CSS (@johnregan3)
    • Modular Custom CSS (@celloexpressions)
    • WordPress.com Custom CSS in the design upgrade (Automattic)
    • Jetpack (Automattic)

    Testing, Feedback, and Next Steps

    Your help is needed in giving feedback on this proposal and testing the feature! To test, please apply the patch either via Trac or the PR (helpful reminder: grunt patch handles both) and try some custom CSS in the customizer using various themes.

    Pending approval of this proposal, the next steps will be to finalize and commit the patch on #35395. Code review is ongoing in the GitHub PR linked on the ticket. Feedback on the feature in general and the specific implementation is encouraged via the comments on this post, with any more technical implementation discussion happening on the Trac ticket or GitHub PR.

    • FolioVision 5:46 pm on October 11, 2016 Permalink | Log in to Reply

      I appreciate all the thought you’ve put into this Nick. A simpler way to customise a child theme is a bold and welcome proposal.

      Still I’d rather see a tool for CSS customisation (a browser extension or an app) than add all this code to core WordPress. This much javascript and CSS in a single webpage is a house of cards and equally fragile.

      A simple way to save in custom CSS after using an external tool would be useful.

      PS. It pains me every day to see complex caching solutions and top heavy security plugins. Core issues (caching and security) would be a better place to start with heavy duty new features than adding more fragility and complexity to a an already fragile and complex system.

      • Helen Hou-Sandi 7:07 pm on October 11, 2016 Permalink | Log in to Reply

        Volunteer effort is not symmetrical – people work on things they have expertise in and passion for. “X is suffering because you are working on Y” is a fallacy.

      • Nick Halsey 11:30 pm on October 11, 2016 Permalink | Log in to Reply

        This feature doesn’t introduce a significant amount of code and in fact, most of the core code is PHP, not JS or CSS. Because it uses the customizer API, which is a framework for live-previewing changes to sites, the implementation of the particular feature is not complex. The proposed solution will work well in a workflow where you write CSS elsewhere and paste it in as well.

    • Jon Brown 6:33 pm on October 11, 2016 Permalink | Log in to Reply

      The general outline of this proposal sounds good to me and I’d certainly love to see all the custom css plugins die a fiery death. The primary reason for that though is that I’ve seen them all hurt performance with slow queries on each page load. My mantra has long been that CSS doesn’t belong in the database.

      I suspect storing the data in a CPT (instead of _options) is going to be more performant, but I’m still very considered about it based on past experience. Wouldn’t be possible to store it as a static file while still having a similar UI to this proposal for editing that file’s content?

      Either way, is there a way it could be tied into the enqueuing system so it could be easily manipulated by themes and picked up by plugins that concatenate enqueued stylesheets?

    • Luke Cavanagh 8:11 pm on October 11, 2016 Permalink | Log in to Reply

      Not sure what the performance will be like for rendering out CSS from postmeta.

      • Nick Halsey 11:27 pm on October 11, 2016 Permalink | Log in to Reply

        Noting that it’ll use post objects directly, not postmeta. This is how Jetpack and WordPress.com do it, so I don’t believe there aren’t major performance issues with that, although I can’t speak to specifics there.

    • Tom J Nowell 9:39 pm on October 11, 2016 Permalink | Log in to Reply

      I’d just like to note that loading this post on a mobile is painful, I’m sure we can cut down a fullscreen 6MB GIF to perhaps a 640×480 view of a reduced size screen a quarter of the length, especially given that when roaming that GIF could cost a lot of money to load. I know my former carrier charges £6 per MB in the US and Canada, that’s £36 or $43 USD

    • vherring 10:09 pm on October 11, 2016 Permalink | Log in to Reply

      The feed back here is from developers the real benefactors of this kind of change is not developers, it in some ways threatens developers because if we get sophisticated in this feature a significant proportion peoples frustration with themes would go away. Like others I do feel storing in a database is too heavy for the feature at present and maintaining a method similar to existing mechanisms provides the flexibility in using the feature in the short term. Perhaps migrating to a different permanent storage method in the future as we become familiar with it and it is functionality is extended.

    • simonrcodrington 10:54 pm on October 11, 2016 Permalink | Log in to Reply

      Pretty excited by this. I think it’s a great idea to offer a more core centric solution to styles and the customizer is the perfect place for it. Having the ability to control styling in an easy to preview way will really help some of our more tech savvy users without giving me the stress of having to let them loose editing the child them.

      In addition to helping site admins, I can see this being really useful as it gives me the ability to quickly preview style charges without affecting live sites.

    • Ahmad Awais 12:17 am on October 12, 2016 Permalink | Log in to Reply

      Good one, Nick! +1 for Aditional CSS. I am just not so sure about the versioning part of it. While it is going to be an incredibly important part of this addition, at the same time it might confuse a beginner. What are your thoughts about that?

      • Nick Halsey 2:24 am on October 12, 2016 Permalink | Log in to Reply

        Versioning/revisions isn’t part of the initial proposal for 4.7. We’ll explore all of the considerations there in a future release, and your input/any ideas you have for improving the usability would be appreciated there.

    • Ipstenu (Mika Epstein) 1:18 am on October 12, 2016 Permalink | Log in to Reply

      CSS would be stored in a custom post type (without admin UI), with a post stored for each theme.

      One small thought… Sometimes users make changes that are not theme-specific. Like your example, Betty/Helen wanting to hide the author byline via CSS, if she changed from TwentyFifteen to the Magical Jumbotron theme, she should be able to grab the CSS from before. Otherwise she has to go back to her old theme and copy pasta.

      Right now, JetPack lets you restore by clicking from your older, saved revisions so stealing that would help 🙂

      • Nick Halsey 2:22 am on October 12, 2016 Permalink | Log in to Reply

        I explored this with the Modular Custom CSS plugin, which stores CSS intended for themes and plugins separately. In practice, I found that the vast majority of tweaks were specific to a particular theme since so much of the way the markup is structured depends on the theme. For the byline example, it would work on other themes using similar markup, but it’s hard to say how consistent themes would be there.

        That being said, there is definitely room for core to improve the cross-theme experience here over time.

        • Ipstenu (Mika Epstein) 5:31 pm on October 13, 2016 Permalink | Log in to Reply

          Yes but… consider that I may change my theme and keep my plugins. This may be intended to be theme specific, but (part of) the reason Jetpack CSS is so popular is that it’s outside my theme, so I can keep plugin css tweaks between themes 🙂

          • Knut Sparhell 1:33 am on October 14, 2016 Permalink | Log in to Reply

            Does Jetpack really keep custom CSS between themes? It says in a notice at the top of the editor that the CSS will be reset when changing theme.

            • Ipstenu (Mika Epstein) 11:54 pm on October 14, 2016 Permalink

              It does and it doesn’t. What it does is lets me click on the link to see the older versions, with the name of the theme. So I can go back and grab the old one. I’m not saying KEEP them as the active CSS, I’m saying make it easy for me to go back, get my old css, and restore it 🙂

              IIRC it’s via post revisions, but I could be wrong (and I’m currently not using it because I needed SVG stuff they don’t support).

    • David C 1:34 am on October 12, 2016 Permalink | Log in to Reply

      Fantastic idea and proof of concept, Nick! We get customers all the time asking how to “tweak” certain css elements without having to build a child theme. This feature would certainly fill that gap. BTW, nice animated gifs. What software did you use to create them?

    • James Collins 2:20 am on October 12, 2016 Permalink | Log in to Reply

      This is a great idea.

      We always need to write custom css rules when creating WordPress sites for clients. We’ve used our own Custom CSS plugin for many years, which helps us avoid the need to create a child theme just to override some CSS.

      We also have clients who want to tweak CSS rules themselves, so they appreciate being able to do so via the WordPress admin.

      Having this operate via the customizer with live preview would be a real time saver!

      In our custom CSS plugin, we save the CSS rules to the database, and also out to a .css file in wp-content/uploads/ , and reference that inside . So when the website is viewed, the .css file is loaded via a CSS link rather than being embedded directly in each and every page.

      I would have thought serving the static .css file from the uploads directory would be more performant than embedding the CSS in each and every page?

      We also use CodeMirror for the actual textarea/editor interface, which works well.

    • Kishores 5:14 am on October 12, 2016 Permalink | Log in to Reply

      +1 for Aditional CSS.

    • Hapiuc Robert 6:34 am on October 12, 2016 Permalink | Log in to Reply

      Really great idea, for small use of the feature storing the data in a CPT doesn’t sound so bad, but we all know how users act and things can escalade quickly.

      How the CSS will be embedded on the page?

    • Primoz Cigler 6:36 am on October 12, 2016 Permalink | Log in to Reply

      Excellent proposal Nick, I can see lots of positive feedback here and I can only add to it.

      One question: will there be another blogpost here in Make Core going more in details about implementation? With the introduction of Additional CSS in 4.7 we will be deprecating our custom CSS field from customizer and we want do to do in a safely manner by automatically migrating the existing custom CSS for our users.

      > How the CSS will be embedded on the page?


      • Nick Halsey 2:04 pm on October 12, 2016 Permalink | Log in to Reply

        That’s a good point, hopefully @johnregan3 can put together some boilerplate functionality for importing existing CSS data into the new core post type, and we can write a dev note for that during beta.

    • Hugo Ashmore 8:57 am on October 12, 2016 Permalink | Log in to Reply

      While I appreciate the sentiments here in the proposal I also have great worries when WP attempts to pursue the user focussed simplicity path as we are in danger of going too far and of encouraging bad code and broken sites and where those users tweaking wouldn’t especially realise something was amiss.

      CSS is not – as often it feels like it’s suggested – a simple language, yes it’s a simple declarative syntax but in reality a powerful tool for preparing the presentation of rendered code to devices, not simply a tool to make a link ‘green’, the cascade, the inheritance are hard aspects to grasp and the flow of rulesets important. CSS was never intended, really, to be worked as many separate disparate episodes provided by themes, child themes, plugins, core etc.. In many cases this results in sites that are problematic to say the least in maintaining with clashes in code that are largely unresolvable.

      I understand the issue though and that we are talking from the perspective of non coder/developers but from a developers perspective we have to understand that many – if from a Standards focussed background – would have a deep concern with the level of participation a client might have in that core site code, personally if a client came to me and expressed the desire for a major site build but also that they would tweak and play with the code as they saw fit I would decline the work as impossible or hard to maintain any sort of standard. implementing a proposal like this may worry developers and further isolate them from the WP sphere at worst (yes the functionality doesn’t have to exist ).

      The process for adding this custom CSS needs thought, embedding as often seen by plugins using wp_head is not a great idea filling the head element of a document isn’t good practise, never been so , embedded code isn’t cached as a linked file is, the page is weighed down, altogether not a good experience especially when perhaps many plugins drop their styles in. So preferably a method that somehow allows the writing of a file to be enqueued would be better although possibly with issues implementing.

      Regardless I do appreciate the intent in this proposal and the nature of WP is to be user focussed and friendly, with ease of use but we just need to think carefully how we implement improvements such as this.

      • Joy 2:59 pm on October 12, 2016 Permalink | Log in to Reply

        I agree that if you don’t really know CSS, you shouldn’t be using a feature like this. I think it could make it more difficult for support people to diagnose problems or clone a design.

        I already proposed the idea of treating the new CPT like an attachment, in that it would hold the file information of where the CSS is stored, and it would be embedded using a link tag, which means anything other than CSS in the file would be ignored.

        The problem I see with the way the interface is proposed is that the live preview should only come after the CSS is entered. Before that, there needs to be a way to toggle to see the source of the page so the proper selectors can be found. Basically, you need to have the browser’s Developer Tools there so you can see the existing selectors and the cascade and the autocomplete, etc.

      • FolioVision 4:13 pm on October 20, 2016 Permalink | Log in to Reply

        Thank you for articulating our shared concerns so well Hugo. A hidden custom CSS feature is a troubleshooting nightmare conceived to destroy developers lives. End users in the end won’t like it either when neither they nor their developer can make their site run right again without starting from scratch.

        The situation isn’t quite as bad as I’ve described above for very well organised developers (I imagine you fall into this class too Hugo). We’ll just add yet another nuisancy check to our checklists of what to do before we start work on a site.

        For our internal clients, we’ll be disabling the Customizer completely I believe as our clients don’t want a tool which could break their sites available to any site admin. It’s funny that developers all have to spend as much time fighting WordPress core these days as working with it.

        What we really need is rock solid caching in core and a built-in security solution and not more toys to break and slow websites. A CSS tweaker or theme builder should be standalone software or a web-based server. I don’t understand why we aren’t all working on such a tool together with Nick. Building a theme building into the core of your CMS is a very, very bad idea for performance, security and maintenance reasons.

        Complexity killed the cat.

    • laur3ntv 12:19 pm on October 12, 2016 Permalink | Log in to Reply

      What I generally do is that I try all the CSS changes in the Chrome Inspector and they apply them in a custom CSS plugin or file. It’s not user friendly and I have to go back and forth between the two.
      So I really love this feature proposal and give a huge upvote 🙂
      Thank you Nick!

    • Timothy Jacobs 7:08 pm on October 12, 2016 Permalink | Log in to Reply

      This is great! Fantastic work. Excited to see where this goes over the next few releases.

    • Weston Ruter 8:58 pm on October 12, 2016 Permalink | Log in to Reply

      Since the only feature provided in the WP_Customize_Code_Editor_Control is line numbers, I think we should skip including this in favor of just using a regular textarea control. In the future when we actually have a code editing control powered by a library like CodeMirror, then the textarea control can be replaced.

    • Daniel Bachhuber 9:01 pm on October 12, 2016 Permalink | Log in to Reply

      Echoing my comments made in Slack, I’m -1 on this proposal for a couple of reasons:

      1. A lot of my (and others) post_type != 'revision' code is going to potentially break. There’s historical precedent that revisions are the only “hidden” post type.
      2. I’m not sold on adding more IDE features to WordPress (that we’ll eventually need to replicate in the REST API)

      I’m opinionated towards having WordPress make decisions as to which elements of the page are configurable and how they can be configured (e.g. header color or background image), over recreating an IDE within the WordPress admin.

      • Aaron Jorbin 2:48 am on October 13, 2016 Permalink | Log in to Reply

        Assuming revisions are the only post type with no UI is far from a best practice. `nav_menu_item` for instance is another non-public nonstandard UI post type already in core.

    • idealien 11:25 pm on October 12, 2016 Permalink | Log in to Reply

      Question: Would this respect the DISALLOW_FILE_EDIT config variable?

    • Aaron Jorbin 2:50 am on October 13, 2016 Permalink | Log in to Reply

      After playing with this, I wonder if it would make sense to add an “Import from Theme” selector of some sort. That might give you a leg up when you switch themes. Was this tested at all?

    • davetgreen 7:17 am on October 13, 2016 Permalink | Log in to Reply

      I’d like to see a couple of filters introduced so that developers can:

      • Hide the CSS editor completely.
      • Prevent the use of `!important` by removing all instances on save etc.
      • Pass in an array of banned properties.
      • Insert a custom notice/advisory directly above the editor.
    • justnorris 9:01 am on October 13, 2016 Permalink | Log in to Reply

      Why not keep this as a plugin ? Why add more bloat to the core? I don’t see the argument for killing CSS Plugins just because they’re popular.

      All plugins solve some problem that the core has. There are 300’000 people using bbPress, I don’t see WordPress becoming a forum software in it’s core any time soon.

      Regenerate thumbnails has 1m+ installs, maybe merge that into core too – people obviously need it and it helps people after they switch themes or thumbnail sizes.

      The list goes on – “Disable Comments”, “Google Analytics”, “Loco Translate”, etc.

      Plugins extend the core. That’s what they’re made for, that’s why WordPress is awesome – everyone can customize the software to their own liking.

      Features that aren’t useful to most users should not be added to the core.

      This is going to clutter the interface, it’s going to add bloat to the core. If it ain’t broke, don’t fix it

      I get it. Custom CSS is rad, I make themes too, I get people asking for CSS modifications too. That’s why you have plugins like Custom CSS. There is just no need for this to become core.

    • treykane 4:06 pm on October 13, 2016 Permalink | Log in to Reply

      I’m a few days late to this debate, but I see a fundamental problem here…

      I have conflicted feelings on this feature as I know I’ve had many clients in the past that wanted this ability, and plenty of good plugins have provided exactly already. But, it seems WordPress is starting to diverge down two different paths, which is a much deeper problem than this proposal.

      1.) WordPress has been going for some time in the direction of becoming a CMS that supports data in a REST API. I think this is great, it puts WordPress in a position to become the backend for web applications of all kinds. Its user friendly, gives content editors a familiar place to go and work on their content, while still providing the developer with the flexibility to do whatever they need to on the front end.

      2.) WordPress keeps adding features like this one, that allow the user to customize the front end, and empowers the user to do whatever they want to do on the site. While this isn’t bad and is in-fact GREAT for a consumer centric product, its in contention with my first point.

      TL;DR –
      It feels like WordPress is trying to be two different products at once and at some point this is going to become a serious problem, on one end or the other. It feels like this proposal just continues to push the potential for identity crisis another step further.

    • Ximbalo 4:52 pm on October 14, 2016 Permalink | Log in to Reply

      This is a welcome topic that I have often wondered “How long before WP adds this feature?”
      I can see quite clearly how this would be a valuable and helpful feature for “simple customization” requirements.

      As long as it does not imply a gradual “phasing out” of the continued ability for more advanced and experienced developers to still create child-themes as needed.

      In my projects at least 50% of all child-theme edits are specific to and focused on the PHP of the parent theme and not just the CSS.

      Here is my input on the topic:

      1. Must Remain: PHP File Overrides:
      As a professional developer, I almost always cannot properly complete a project, nor apply ideal code-and-content top-down flow optimizations, without resorting to PHP template overrides. Suffice it to say, rarely does any given theme’s built-in page header or body structure suffice for my client customization requirements. The built-in CSS editor feature sounds great… as long as it does not lead to my eventually not being able to create child-theme PHP page template & include file overrides.

      2. Unwanted: Long Streams of Embedded Inline CSS
      To me, one of the *very worst* and sloppy coding bad habits of WP Theme developers in recent years, is that of “dumping” custom CSS directly into the code-flow as inline CSS — rather than at least allowing for the custom CSS to be compartmentalized into a single “custom.css.php” file.

      I have seen some themes that include a checkbox for this option – and I always admire that. If it does not exist, I will add my own PHP to remove the hundreds or thousands of lines of inline CSS that get dumped into my would-be “clean and optimized code”.

      Thus, when this new feature is added to WordPress, it would be good to include an option for all custom CSS to be written into a PHP generated include file. (Understood and acknowledged is the idea that this option is not compatible with DISALLOW_FILE_EDIT or Security Plugins that turn off back-end file edits.)

      3. SUMMARY: As a professional developer…
      A) I would use and benefit from this feature in cases of small, simple edits to a relatively simple site.
      B) I would use this feature to make clearly accessible certain “global styles” that I actually WANTED my client to be able to edit on their own ( i.e. global use of font styles, colors, & such )
      C) But only if an option was available to encapsulate the cusotm CSS into a single file (avoid dumping reams of inline CSS)
      D) I would NOT use this feature when hundreds of lines of advanced custom CSS are required
      E) This feature should really not be confused with no longer actually needing child themes due to the requirement of being able to override PHP template files.

      Thank You,


    • Philip Ingram 3:39 pm on October 20, 2016 Permalink | Log in to Reply

      As mentioned here -> https://core.trac.wordpress.org/ticket/35395#comment:71, I still feel like this type of tool is more “developer-centric” as 99% of my clients would never use this nor would I expect them to however I do see value in power users using something like this to tweak and fix very minor css.

      Ultimately, yes I do want this…but in core? Not so sure about that. I want to be able to turn this off and leave no dependency on loading the actual css from the db on the front end. The db stored css should only be used for revisions and live editing in the customizer and I feel the front end should still reference actual files that can be post-processed, cached and even off-hosted such as a CDN.

      If we can figure out a way of writing logical files that WP automatically loads based on file naming structure, similar to how themes do this now with the php file naming conventions, we would be golden and no one can complain about bloat, extra db cost etc. But again, do we need IDE features like this built into the core or should we amend the core only to allow for bettering our IDE plugins we use for development?

      Maybe we should consider requiring a constant in wp-config to enable IDE development features of wordpress, like this, like the current theme/plugin editors?

    • Sebastian Pisula 7:45 am on October 21, 2016 Permalink | Log in to Reply

      Why CPT? Why not theme_mods?

    • Luke Cavanagh 9:34 pm on November 4, 2016 Permalink | Log in to Reply

      Will there be a global option for the custom css, so certain css could carry over if it was just plugin specific and not theme specfic and not be lost when a user changes themes.

    • Mahesh Waghmare 8:55 am on November 15, 2016 Permalink | Log in to Reply

      +1 for the Revisions.

  • Nick Halsey 7:00 pm on October 3, 2016 Permalink |
    Tags: , , , , , themes   

    Feature Proposal: A New Experience for Discovering, Installing, and Previewing Themes in the Customizer 

    This is the feature merge proposal for the new themes experience in the customizer introduced with #37661. Here’s an overview of the current proposed UI:

    Customizer themes design and user flow mockup

    Customizer themes design and user flow mockup by @folletto.

    A theme is the most fundamental aspect of customizing a site. This project seeks to unify the theme-browsing and theme-customization experiences by introducing a comprehensive theme browser and installer directly in the customizer.

    Walkthrough of the latest patch on #37661.

    Walkthrough of the latest patch on #37661.

    Background & History

    The customizer originated as a tool for previewing and customizing themes and as such, was closely integrated into the theme browsing experience in wp-admin when it was introduced in WordPress 3.4. The theme browser and installer were rewritten in WordPress 3.8 and 3.9, respectively, offering a fast JavaScript-based way to explore, install, and switch themes.

    Eventually, as the customizer’s role grew to that of a framework for live-previewing any change to a site, it became apparent that it would benefit from a more direct way to switch themes, without entering the wp-admin context. The Customizer Theme Switcher plugin was created, and after some refinement, merged into WordPress 4.2. However, while it initially included external links to install themes in the admin, these were eventually removed due to the jarring experience of unexpectedly leaving the customizer.

    Currently, there is no indication that additional themes can be installed when viewing available themes in the customizer. For new users, it may take quite a bit of time to discover the ability to install themes, via wp-admin, or they may give up on WordPress before making this discovery. This is a usability dead-end where a user’s flow is disrupted in the process of discovering, installing, previewing, and activating themes, both on initial site setup and when considering a redesign.

    When the theme switcher plugin was developed, the team made preliminary plans for a theme installation interface as a second phase of the project. Specifically, it would leave the “preview” context of the customizer but retain the same identity in the user experience. @folletto helped develop this initial concept in early 2015.

    Technical Constraints & Requirements

    There have been several technical limitations preventing theme installation in the customizer from being addressed previously. Most notably, such an interface requires “shiny” ajax-based theme installation, updates, and deletion, so that the user flow can persistently stay in the customizer themes interface rather than jumping to separate “installing” views. This is now possible with phase 2 of “Shiny Updates” in WordPress 4.6. Additionally, expansions of the customizer JavaScript and JS-templated controls APIs to better support dynamically-registered controls were needed to support theme installation within the customizer framework, and these were fully fleshed out for the customizer menus interface introduced in WordPress 4.3. With these technical constraints eliminated, theme installation in the customizer is now possible without additional significant improvements to the underlying themes or customizer APIs.

    The customizer must currently be completely reloaded from PHP to preview a different theme. To perform a theme switch without a reload, theme-defined settings, sections, and controls would need to be updated dynamically with JavaScript. While the customizer internals have been working toward making this possible for some time, significant work remains to make inline theme switches possible. Therefore, changes to this part of the theme-switching workflow are out of scope for the current project, which focuses on the user-facing flow.

    The biggest usability block that this limitation causes is that unsaved changes are lost when the theme is switched. Unsaved changes are currently handled by prompting users with an are-you-sure notice in the browser before making the switch. Unfortunately, limitations in JavaScript require the loading indicator to be hidden after the user decides to stay on the page or to continue to the new theme, causing confusion. In the new interface, this is further mitigated by displaying a warning that there are unsaved changes, with an inline button to save and publish them, at the top of the interface. With customize changesets (transactions) (#)30937, a “save draft” option could also become possible in the future, allowing changes to be saved (potentially automatically) without being published between theme previews.

    Previewing Themes

    One of the biggest challenges with theme installation in wp-admin, and opportunities in the customizer, is previewing themes. Currently, a customizer-like frame displays a preview hosted on WordPress.org, with limited content. Rather than opening this potentially-disorienting similar but different interface, the proposed flow de-emphasizes the distinction between installed and available themes. The primary action for available themes is now “Install & Preview”, which installs the theme and live previews it in one step.

    Users can now see any theme on their site with their content and play with its options in the customizer in one click. If they decide it’s the wrong theme for their site, the themes panel can be quickly reopened and another theme selected and previewed with no harm done. A secondary action allows themes to be installed without instantly previewing, so that the installed themes tab can become a personal theme library of sorts, where users can save themes that they might want to try on their site. Installed themes being a filter along with the available theme headings unifies the previously-disorienting separation of themes and add-new themes on separate screens, with confusingly-separate search and header (add new/upload theme) functionality.

    Proposed Themes Interface

    Due to the tight integration with the existing system, with the existing theme control and section as well as internal elements in the customizer manager and theme details template requiring moderate modifications, this project was implemented as a patch and cannot be reasonably converted into a plugin and back. The patch has been available on trac for six+ weeks, with iterations continuing to improve and polish the new experience.

    The technical implementation continues adapting the concepts present in the backbone.js-based themes experience in wp-admin to leverage the customizer API. With the themes experience natively built on the customizer framework, it should be much easier for developers to improve and maintain the core experience in the future as well as extending the core experience in a structured way.

    A few highlights of the proposed details:

    • Installed themes are no longer loaded every time the customizer is opened, resulting in potentially significant performance improvements by only calling wp_prepare_themes_for_js() when needed. This also allows themes in the customizer to be fully disabled with remove_panel( 'themes' ).
    • The themes experience is unchanged on the top level of the customizer, but selecting the change theme button now opens a panel that fills the entire screen, as the preview is not relevant when considering a theme change.
    • The UI diverges somewhat from what is found in the theme installer in wp-admin (which will remain), particularly around the filters.
    • The theme details view is unified between installed and available themes; clicking on a screenshot opens the details view to match the admin UI.
    • Primary buttons are used where clicking them takes you away from the current page (ie, for previews); secondary buttons are used elsewhere.
    • The loading strategy attempts to balance performance with wait time by loading theme data from Ajax in large batches (100 themes) and following up by rendering screenshots as they become visible (as the existing interface does).

    Usability Testing

    Four usability tests have been conducted so far. The full test screencasts are available on Make/Design, alongside key takeaways. These tests expose a lot of largely-known issues with themes and the customizer in general, but did not reveal any significant issues with the proposed new theme browser. Because the tests were conducted in-person with a limited set of volunteers, additional testing with a broader user base would be ideal.

    There has been design feedback since the user testing was conducted, resulting in some significant changes. @karmatosed has volunteered to coordinate additional testing in the next week to verify that the changes haven’t introduced usability regressions, and to test with a broader audience. Check out the call for user testing on make/design to help out here.

    A visual record on a phone of the revised design has been posted on make/flow.


    Because the new interface is built entirely on the customizer API, third-party plugins should now be able to integrate much more easily. This means that other theme marketplaces (including commercial themes) could realistically be browsed (and maybe even installed) from within WordPress, while leveraging the core UI exactly.

    The presentational flexibility is available via the customizer API (with custom theme sections for other theme sources, and theme controls for individual themes), but there are likely some gaps in the ability to do this seamlessly in the internals. If anyone is interested in building this sort of functionality, please evaluate whether any additional hooks are needed so that they can launch alongside the new feature.

    Review and Approval

    In addition to a general core approval of this proposal, the following sign-offs are required before the feature could be approved for merge, based on the applicable elements of this list:

    • Flow (and mobile) review (see also an initial post)
    • Docs review
    • Security audit
    • Polyglots/i18n review
    • Design/UX review – tentative approval has been provided from @karmatosed and @folletto (with additional input from others in last week’s design meeting) with an expectation that minor adjustments will continue to be required. General design feedback is still welcome, but major changes are unlikely to be feasible at this point.
    • Accessibility review – @afercia completed an initial review, with the issues fixed in a subsequent patch. A comprehensive final review would be a good idea as well, since there have been significant design changes.
    • Code review – to be handled by @westonruter once the patch is otherwise deemed “ready” based on review from other teams.

    To test, update to latest trunk and apply the latest patch on #37661. On your test site, open the customizer and “change” the theme. Try out the various filters, browse themes, and install and preview them. Also test the inline update and deletion functionality.

    To meet the feature merge deadline for 4.7 (10/19), reviews from various teams and any corresponding iterations need to be completed by October 12th, leaving a week for final code review and commit. General feedback and specific reviews and action items should be provided as comments on this post.

  • David A. Kennedy 3:38 pm on December 1, 2015 Permalink
    Tags: themes   

    Menu ids in wp_page_menu() 

    In changeset 34330, we added a menu_id argument to wp_page_menu(), allowing theme authors to use a unique id with the containing menu div.

    It also means that, by default, the fallback menus have the same attributes as wp_nav_menu(). So wp_page_menu() and wp_nav_menu() now have the same menu_id. We made this change to help accommodate accessibility and certain ARIA attributes that require an id to be associated with a control. Before this change, theme authors lacked an easy way to add an id to that container.

    This shouldn’t cause most themes to break, except in a few edge cases. If you rely on the absence of that id in your theme for wp_page_menu() or do any kind of detection around wp_page_menu() vs. wp_nav_menu(), read on. I’ll go over a few recommended ways you can avoid your theme breaking with the release of WordPress 4.4.

    If you need to add class names or id names to the HTML output of either function, you can use a filter for that. Like this, using Twenty Fourteen as an example:

    function twentyfourteen_page_menu_args( $args ) {
        $args['menu_id'] = 'page-menu';
        return $args;
    add_filter( 'wp_page_menu_args', 'twentyfourteen_page_menu_args' );

    If you need to do something similar with wp_nav_menu(), you can either change the id with an argument in the template tag itself, or use a filer, similar to the page menu. Again, using Twenty Fourteen as an example:

    function twentyfourteen_nav_menu_args( $args ) {
        $args['menu_id'] = 'nav-menu';
        return $args;
    add_filter( 'wp_nav_menu_args', 'twentyfourteen_nav_menu_args' );

    Note that wp_nav_menu() adds the id to the ul element and wp_page_menu() adds it to the container element around the ul. So your CSS may need adjusting depending on what you have in place. You may need to make it less specific in some cases.

  • John Blackbourn 3:15 pm on October 7, 2015 Permalink
    Tags: , , themes   

    single-{post_type}-{post_name}.php: New theme template in WordPress 4.4 

    A new theme template has been added to the theme hierarchy as of r34800: single-{post_type}-{post_name}.php.  This template follows the rules of is_single() and is used for a single post or custom post type. It’s most useful for targeting a specific post in a custom post type, and brings consistency to the templates available for pages and taxonomies. It comes in the hierarchy before single.php and single-{post_type}.php.

    Don’t forget, too, that in WordPress 4.3 singular.php was introduced and the hierarchy of attachment templates was fixed.

    • petermolnar 3:22 pm on October 7, 2015 Permalink | Log in to Reply

      wp-config should have an option that sets the max allowed depth for template searches. As in:
      1 -> single depth, eg. single.php, {taxonomy}.php
      2 -> 2 level depth, eg. single-{post_type}.php
      3 -> unlimited depth, eg. single-{post_type}-{post_name}.php

      I wouldn’t be surprised it’d result in a measurable speed gain.

      • John Blackbourn 3:36 pm on October 7, 2015 Permalink | Log in to Reply

        That would save a maximum of about five file_exists() calls, depending on whether you’re using a child theme or not. I doubt it would have any measurable impact at all. file_exists() checks are very fast when absolute file paths are used.

        Additionally, it would introduce inconsistency to the template hierarchy, and consistency is a huge benefit of the theming system in WordPress.

    • kjbenk 4:07 pm on October 7, 2015 Permalink | Log in to Reply

      This is really cool and I can see an immediate use case for this.

    • Ravinder Kumar 5:05 pm on October 7, 2015 Permalink | Log in to Reply

      Nice addition to WordPress.

    • Dinesh Kesarwani 5:28 am on October 8, 2015 Permalink | Log in to Reply

      Yes! nice addition. I also suggested similar template before some time ago. But, it was rejected.

    • BenRacicot 12:10 am on October 10, 2015 Permalink | Log in to Reply

      Golf clap

    • elzix 2:26 pm on November 5, 2015 Permalink | Log in to Reply

      I read in the Theme Developer Handbook and assumed single-{post_type}-{post_name}.php was in WordPress 4.3. Is there a way to add the function to my theme or must I convert my posts to pages and use ‘categories for pages’ plugin?

  • Dominik Schilling (ocean90) 5:41 pm on July 30, 2015 Permalink
    Tags: , , themes   

    Legacy Theme Preview Removed in 4.3 

    This release we removed the old code for the Legacy Theme Preview, which hasn’t been maintained since the introduction of the customizer in WordPress 3.5. Recently, we noticed that the theme preview no longer works when using a static front page. We kept the old theme preview for no-JS and some browsers that were less capable. But since browsers are doing a better job today we don’t need to continue fixing/shipping this legacy code. It’s removed in [33492].

  • Aaron Jorbin 7:34 pm on July 6, 2015 Permalink
    Tags: , , , themes   

    Singular.php: New Theme Template in WordPress 4.3 

    A new theme template has been added to the theme hierarchy as of r32846: singular.php.  This template follows the rules of is_singular and is used for a single post, irregardless of post type.  It comes in the hierarchy after single.php, page.php, and the variations of each. Themes that used the same code for both of those files (or included one in the other) can now simplify down to the one template.

  • Derek Herman 8:00 pm on March 11, 2015 Permalink
    Tags: , , themes,   

    HTML5 Widgets in WordPress 4.2 

    Note: HTML5 widgets theme support in 4.2 has been reverted pending a decision about the correct container to use

    With the upcoming WordPress 4.2 release, widgets have been added to the growing list of HTML5 supported markup. Once you’ve added HTML5 support for widgets, WordPress will use the <aside> element, instead of the generic list markup.

    To declare that your theme supports HTML5 widgets, add the following call to your theme’s functions.php file, preferably in a callback to the after_setup_theme action:

    add_theme_support( 'html5', array( 'widgets' ) );

    For forward compatibility reasons, the second argument cannot be omitted when registering support. Otherwise, a theme would automatically declare its support for HTML5 features that might be added in the future, possibly breaking it visually.

    If there are any questions about the current implementation, feel free to leave a comment below.

  • Nick Halsey 11:00 pm on February 11, 2015 Permalink
    Tags: , , , , , , themes   

    Customizer Theme Switcher Feature Plugin Merge Proposal 

    Ticket: #31303

    Customizer Theme Switcher brings theme-browsing and theme-switching functionality into the Customizer. By integrating themes directly into the Customizer, live-previewing workflows are greatly simplified, and the relationship between themes and theme/site options is clarified for the user.

    This plugin represents a significant step in moving all “Appearance” functionality into the Customizer, following Widgets. The future roadmap includes Menus, Theme-Install, and iterations on widgets that would allow the Customizer to entirely replace those admin screens for most users. Because the Customizer Theme Switcher plugin does not address theme-install, the admin page (themes.php) is fully intended to remain in use for now. We are proposing to redirect the front-end “Themes” link (in the admin bar) to the Customizer, as was done for widgets in 4.1.

    Technical Overview

    Customizer Theme Switcher is primarily about adding new UI for existing functionality using existing APIs, rather than introducing new functionality. The plugin operates entirely off of the WordPress 4.1 Customizer API, leveraging the new JavaScript API in particular. Themes is a custom section (that acts kind of like a panel). Each theme is a custom Customizer control.

    The code is heavily Backbone.js-inspired, leveraging JS-heavy portions of the Customizer API to do things like underscore JS templates for rendering theme data. Most of the code is directly adapted from the Backbone-driven themes.php system (and the theme data is retrieved with existing functions), but things like the search/filter are written from the ground up to leverage the Customizer API (in that case, conditionally activating/deactivating controls).

    In keeping with the goal to avoid back-end functionality changes, theme-switches are accomplished simply by leveraging the existing ability to pass a theme as a URL query arg when loading the Customizer; ie, the Customizer is simply reloaded to preview a different theme. Loading overlays are leveraged to make this process seem more instant. Unrelated 4.2 core work around Customizer Transactions could potentially improve how this works.

    Core Changes & Merge Implementation Details

    As outlined in the plugin’s readme there are several proposed technical and user-oriented changes that are best done as core patches (mostly in the merge patch):


    • Remove #customize-info for theme previews.
    • Change front-end admin bar Themes link to point to themes in the Customizer (deep-linked).
    • When a new theme is activated, go to the home page (front end), not the themes admin.
    • If user doesn’t confirm that they want to leave unsaved changes, remove the customize-loading body class (requires core patch).


    • Move custom section and control to class-wp-customize-control|section.php in wp-includes.
    • Merge all CSS into customize-controls.css, scope to .wp-customizer.
    • Move .themes-panel-back to the Customizer header, adjust JS accordingly.
    • Merge JS into customizer-controls.js, after the respective object types.
    • Merge customize_themes_template() into wp-admin/includes/theme.php, at the very end. Make sure that this file is included at the appropriate time as needed when adding the Customizer controls.
    • Merge remaining PHP (all in Customize Register callback) into register_controls() in class-wp-customize-manager.php.

    User Testing

    @designsimply has run four usertesting.com tests (see links in #core-customize), and we haven’t really seen any ongoing issues with the actual theme switcher. It has been difficult to get users to follow our instructions, but when they have used the themes-in-Customizer UI, the interactions have been fairly seamless and as-intended. Further testing could be beneficial after merge, but we think that in-person testing and feedback is generally going to be more effective for this particular plugin.

    Outstanding Issues

    The exact handling of the themes header display still needs some work – the backwards-sliding works well but the arrows to indicate it don’t. @folletto opened a ticket on core trac to work through some alternative options. Most of the accessibility issues have been fixed as well (@afercia please let me know if I’ve missed any), with the exception of the Themes section header, which will happen along with the UI changes there for everyone.

    Future Plans

    A future phase of this project will explore integrating theme-install in the Customizer and minimizing the distinction between installed and available themes. Due to the larger UI and UX changes proposed with that effort, we’ve decided to hold off on theme-install for now so that the basic theme-switching functionality could be built on a reasonable timeline for 4.2. This is similar to the manner in which the “THX” feature plugin team re-did themes in 3.8 and theme-install in 3.9.

    • bellfalasch 9:31 am on February 12, 2015 Permalink | Log in to Reply

      Looks good =) I personally would love something like a top positioned overlay with short text “You are previewing Theme X – [activate theme] – [cancel]”. Or wouldn’t that make sense in the customizer?

    • Andrea Fercia 1:52 pm on February 12, 2015 Permalink | Log in to Reply

      Thanks very much Nick and great job 🙂 will review all your feedback on the accessibility issues list and will let you know.

    • codeinwp 9:10 pm on February 12, 2015 Permalink | Log in to Reply

      Looks really cool!

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