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 accessibilityAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility) 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 HTMLHTML HyperText Markup Language. The semantic scripting language primarily used for outputting content in web browsers. output of either function, you can use a filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. 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 tagtag A directory in Subversion. WordPress uses tags to store a single snapshot of a version (3.6, 3.6.1, etc.), the common convention of tags in version control systems. (Not to be confused with post tags.) 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 CSSCSS Cascading Style Sheets. may need adjusting depending on what you have in place. You may need to make it less specific in some cases.

#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 typeCustom Post Type WordPress can hold and display many different types of content. A single item of such a content is generally called a post, although post is also a specific post type. Custom Post Types gives your site the ability to have templated posts, to simplify the concept.. 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.

#dev-notes, #templates, #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 customizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings. in WordPress 3.5. Recently, we noticed that the theme preview no longer works when using a static front pageStatic Front Page A WordPress website can have a dynamic blog-like front page, or a “static front page” which is used to show customized content. Typically this is the first page you see when you visit a site url, like wordpress.org for example.. We kept the old theme preview for no-JSJS JavaScript, a web scripting language typically executed in the browser. Often used for advanced user interfaces and behaviors. 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].

#4-3, #dev-notes, #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.

#4-3, #dev-notes, #templates, #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.

#4-2, #html5, #themes, #widgets

Customizer Theme Switcher Feature Plugin Merge Proposal

Ticketticket Created for both bug reports and feature development on the bug tracker.: #31303

Customizer Theme Switcher brings theme-browsing and theme-switching functionality into the CustomizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings.. 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 pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party 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 adminadmin (and super 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 UIUI User interface for existing functionality using existing APIs, rather than introducing new functionality. The plugin operates entirely off of the WordPress 4.1 Customizer APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways., leveraging the new JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. 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 JSJS JavaScript, a web scripting language typically executed in the browser. Often used for advanced user interfaces and behaviors.-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/filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. 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 URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org 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 coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. 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 patchpatch A special text file that describes changes to code, by identifying the files and lines which are added, removed, and altered. It may also be referred to as a diff. A patch can be applied to a codebase for testing.):

UXUX User experience

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

Code

  • Move custom section and control to class-wp-customize-control|section.php in wp-includes.
  • Merge all CSSCSS Cascading Style Sheets. into customize-controls.css, scope to .wp-customizer.
  • Move .themes-panel-back to the Customizer headerHeader The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes., 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 PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher (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 tracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. to work through some alternative options. Most of the accessibilityAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility) 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 “THXfeature pluginFeature Plugin A plugin that was created with the intention of eventually being proposed for inclusion in WordPress Core. See Features as Plugins. team re-did themes in 3.8 and theme-install in 3.9.

#4-2, #customize, #feature-plugins, #merge, #proposal, #theme-switcher, #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 SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/.. The accessibilityAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility) team did an extensive review and we’ve addressed nearly all of the issues that can be fixed in the pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party (big props to @afercia especially for reviewing and patching some of the issues). I made several coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. 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 CustomizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings. 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 filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. 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 adminadmin (and super 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 patchpatch A special text file that describes changes to code, by identifying the files and lines which are added, removed, and altered. It may also be referred to as a diff. A patch can be applied to a codebase for testing./merge plan and timing – @MarkJaquith, me, @DrewAPicture

#customize, #theme-switcher, #themes

Customizer Theme Switcher Update

The Customizer Theme Switcher feature-pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party brings theme switching into the CustomizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings.. 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 adminadmin (and super 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 pluginFeature Plugin A plugin that was created with the intention of eventually being proposed for inclusion in WordPress Core. See Features as Plugins. is focusing on the switching UIUI User interface, 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.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://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 accessibilityAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility) (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 patchpatch A special text file that describes changes to code, by identifying the files and lines which are added, removed, and altered. It may also be referred to as a diff. A patch can be applied to a codebase for testing.).

Known issues (see also a list of coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. merge notes in the plugin’s readme):

  • Animation closing the themes panel is broken (see commented-out CSSCSS Cascading Style Sheets.) (@celloexpressions)
  • Persist “return” & “url” URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org parameters in the switch-themes links (@celloexpressions)
  • Don’t show the loading animation if there are unsaved changes to avoid getting stuck. Actually fixing the underlying issue requires a minor core patch. (@DrewAPicture)
  • Break out of the customize.php iframeiframe iFrame is an acronym for an inline frame. An iFrame is used inside a webpage to load another HTML document and render it. This HTML document may also contain JavaScript and/or CSS which is loaded at the time when iframe tag is parsed by the user’s browser. if the Customizer was loaded with the customize-loader script (@celloexpressions)
  • PostMessage setting transport may not be working immediately after switching themes, cause unknown (@celloexpressions)

#customize, #theme-switcher, #themes, #thx38

Support for Screen Reader Text in Themes

Support for Screen Reader Text in Themes.

#accessibility, #themes

New Template Tags in 4.1

Working on a new default theme is always an opportunity to improve coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.’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 taxonomyTaxonomy A taxonomy is a way to group things together. In WordPress, some common taxonomies are category, link, tag, or post format. https://codex.wordpress.org/Taxonomies#Default_Taxonomies. 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 tagtag A directory in Subversion. WordPress uses tags to store a single snapshot of a version (3.6, 3.6.1, etc.), the common convention of tags in version control systems. (Not to be confused with post tags.) 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.

#4-1, #bundled-theme, #dev-notes, #themes, #twentyfifteen