Make WordPress Core

Tagged: themes Toggle Comment Threads | Keyboard Shortcuts

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

  • Nick Halsey 12:46 am on February 3, 2015 Permalink
    Tags: , , themes   

    Customizer Theme Switcher Update – 2/2 

    We’ve made lots of progress in the past week and will be holding another meeting tomorrow, Tuesday February 3 2015 16:00 UTC, in #core-customize Slack. The accessibility team did an extensive review and we’ve addressed nearly all of the issues that can be fixed in the plugin (big props to @afercia especially for reviewing and patching some of the issues). I made several core tickets (some with patches, some good-first-bugs) for some of the other issues that came up during the review.

    @designsimply and @vizkr have been working on formal and informal user tests as well. It’s been a little tricky to try to nudge users in the direction of the Theme Switcher in the Customizer without explicitly asking them to change the theme, but they haven’t had any negative feedback or expressed that having themes in the Customizer felt at all out of place. We’ve made a couple of minor adjustments both to the plugin (improving the filter to search for tags without hyphens) and the prompts, and additional tests are in-progress. We’d like to encourage anyone that can to do informal in-person testing, asking for feedback on the workflows and/or comparing the themes admin screen to themes in the Customizer.

    Our biggest remaining decision is whether to change the title of the “themes” section in the Customizer. Currently, it’s “Theme: Current Theme”. Open to suggestions here; we’ll tweak it for screen readers regardless if it works for everyone else as-is, but I’m not convinced that it’s the most discoverable option currently.

    Here’s an agenda for the meeting:

    • Usertesting.com testing update – @designsimply
    • Theme section heading title discussion
    • Informal testing/feedback updates – anyone
    • Accessibility updates: ready for (or do we need) another round of testing for the plugin? – @afercia
    • Outstanding issues – anyone
    • Final proposal and core patch/merge plan and timing – @MarkJaquith, me, @DrewAPicture
  • Nick Halsey 8:11 am on January 26, 2015 Permalink
    Tags: , , themes,   

    Customizer Theme Switcher Update 

    The Customizer Theme Switcher feature-plugin brings theme switching into the Customizer. This project aims to clarify the relationship between themes and theme options by introducing a themes “panel” (it’s actually a custom section since it contains controls, not a multi-level hierarchy of sections and controls) to the Customizer. The themes panel slides in from the left instead of the right, implying a hierarchy of:

    1. Themes – change the entire layout of the site
    2. Theme/site options – tweak various options (default view)
    3. Panels – edit larger groups of site appearance options, such as Widgets and Menus

    Essentially, the phase of the project proposed for WordPress 4.2 (and that exists in the plugin currently) brings the “THX38” theme browsing experience into the Customizer. Installed themes are browse-able directly in the Customizer controls panel, and have a details modal like the admin page. Functionally, theme-switching is accomplished by reloading the Customizer to live-preview a different theme. @westonruter is working on several related improvements that could further streamlining the experience from a technical perspective, but this feature plugin is focusing on the switching UI, with other improvements considered “nice to have”. @folletto and I have also started planning a second phase of the project for a future release that would also address installing new themes, and simplifying the distinction between installed and available themes. @designsimply is currently in the process of user-testing the plugin.

    Get Involved

    We’ll hold a meeting in #core-customize Slack to discuss the progress of the plugin this Tuesday, January 27, 2015 16:00 UTC, and continue at that time weekly as needed at that time. Development is happening directly in the WordPress.org plugins repo – I’ll give commit access to anyone interested in contributing code. Outstanding issues are noted below, but the plugin is generally ready for review of code, inline-docs, design, and accessibility (with each of those being theoretically good-to-go in the plugin). Note that the plugin can’t really work on mobile because the Customizer doesn’t really work on mobile, see #28784 (great 4.2 candidate if it gets a patch).

    Known issues (see also a list of core merge notes in the plugin’s readme):

    • Weston Ruter 9:53 pm on January 29, 2015 Permalink | Log in to Reply

      PostMessage setting transport may not be working immediately after switching themes, cause unknown

      I can’t reproduce this. See Slack conversation.

    • Rian Rietveld 7:40 am on January 31, 2015 Permalink | Log in to Reply

    • Devin Price 12:04 am on February 5, 2015 Permalink | Log in to Reply

      Hi Nick. Great work on this. A couple thoughts:

      I might recommend is that the theme panel stays open (retains focus) after switching. If someone is testing the look of a few different themes, it might be annoying to have to open that panel again each time and lose context.

      I’m not sure if the theme switcher should have such a high priority (in terms of order). I feel like switching themes has a lot of ramifications, and perhaps shouldn’t be the first option. I’d probably hook it in below the “widgets” (just a personal feeling though).

      Also, looks like the open/close arrows for the panel are pointing the wrong way.

      Maybe you’re already working through some of those. Just wanted to add my 2 cents.

  • Konstantin Obenland 5:50 am on January 26, 2015 Permalink
    Tags: , themes   

    Support for Screen Reader Text in Themes.

  • Konstantin Obenland 8:04 pm on December 4, 2014 Permalink
    Tags: , , , themes,   

    New Template Tags in 4.1 

    Working on a new default theme is always an opportunity to improve core’s Theme APIs too. With the release of Twenty Fifteen there are quite a few improvements that made it in:

    Archive Template Tags

    Theme authors get to use four new functions to use in their archive templates:

    • get_the_archive_title() and the_archive_title() for returning/displaying the title of the current term, date, post type, post format, or author archive.
    • get_the_archive_description() and the_archive_description() for returning/displaying the description associated with the current term archive.

    They are especially handy when a theme doesn’t have dedicated templates for taxonomy or date archives, but can essentially be used in all archive templates. The description functions only display term descriptions, since no other archive type really offers descriptions.

    Worked on in #21995 and then introduced in r30223.

    Navigation Template Tags

    Core has provided template tags for links between posts and pages of posts for a long time. Now theme authors can resort to higher-level template tags to display an entire navigation snippet. If you’ve built your themes off of recent default themes, or created child themes from them, these should look very familiar. As a heads up: Since default themes have been developed in HTML5 for five years now, there is no HTML4 version of these tags.

    • get_the_post_navigation() and the_post_navigation() for navigation to the next and previous post.
    • get_the_posts_navigation() and the_posts_navigation() for navigation to the next and previous page of posts.
    • get_the_posts_pagination() and the_posts_pagination() for paginated navigation between pages of posts. (Updated for 4.1 RC1, see this post)

    All functions use the same wrapping markup with semantic class names, so it’s easy to style them in one go. The navigation functions accept custom link texts and screen-reader-texts, in case the defaults are not applicable. The pagination functions even accept all arguments that paginate_links() does, too! (Except for the 'type' argument, we need that to be plain so the template tag doesn’t break 😉 )

    Worked on in #29808, introduced in r30065, improved in r30457.

    Also in 4.1:

    Theme Support for Title Tags

    I’ve written about title tags before and will refer to that post for more information about the groundbreaking changes that happened here.

    Page Template Body Classes

    They got a minor update that simplifies those class names and allows theme authors to target folders of page templates. With this /page-templates/full-width.php will produce page-templatepage-template-page-templates, page-template-full-width and page-template-page-templatesfull-width-php. Worked on in #23470 and then introduced in r30100.

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