Building and Managing Dynamic Multi-part Pages with WordPress

Twenty Seventeen is the first bundled theme to provide a way to create multi-part pages with WordPress, via a front page sections option that features multiple pages on the front page. This is useful for largely single-page sites, but limits the functionality of a front page as a showcase for and gateway to content throughout larger sites.

For sites with more content, and even multiple post types, there isn’t an established pattern for building pages that feature multiple pieces of content. Core archives exist for single taxonomy terms, authors, and post types, but widgets or custom implementations are needed to tie these pieces together. Twenty Fourteen explored strategies for high-content sites by providing numerous widget areas, specialized widgets, and featured content on the front page. The featured content concept provides two major benefits: visitors are exposed to a diverse array of content that would otherwise be buried deeper in a site, and the featured items are updated automatically as new content is created.

WordPress is especially strong in its use of taxonomies to group content together. Extending this functionality one more level to allow terms and posts to be grouped into navigational indexes provides immense power to build complex pages that can be managed within WordPress rather than being defined in code. Featuring taxonomy terms in addition to single posts makes these multi-part pages dynamic, with featured content updating automatically as new items are published.

It can be difficult to visualize the end goal for these types of pages, so here are a few examples of dynamic multi-part pages that should be possible to build and manage with WordPress:

Suggested Solution: Menus

WordPress menus organize navigation to different elements of a site. This is traditionally handled as vertical or horizontal lists, often with hierarchy. Recently, themes have expanded this concept by presenting additional layouts such as social menus that display icons in place of text labels. Some themes show the menu item’s description (a core feature) for additional context.

From a technical perspective, menus have a dedicated post type with a post for each menu item, and a taxonomy term for each menu to group the items together. I became far too familiar with the benefits and challenges of this approach in the year that I spent bringing menu management into the customizer with live preview. The potential to do more with menus struck me as the biggest opportunity for themes (and plugins) to innovate site management without major core changes.

The basic concept of a menu is a way to organize content on a site. And in core, menus can contain items for posts and terms of any type (that supports it), as well as custom links. What if we took this concept a step further, encouraging themes to pull additional elements such as featured images or even post excerpts or content from the objects associated with menus?

While this may seem like an odd proposal if you think of menus as primarily useful for navigation, setting this up in a dynamic way actually preserves the organizational intent by providing navigation to content within the site. The difference is that more context is available for each item, and some items may be presented largely in their entirety without linking off to a single post view, perhaps enabling the option for more of a single page site feel. Taxonomy terms featured in a menu could display the first few posts within them as well as any taxonomy meta and the term description, opening the doors for a deeper showcase of content with a menu and introducing dynamic hierarchy by showing content within terms.

Perhaps the biggest advantage of this approach is that it can be implemented right now with the support of a robust management interface with live preview in WordPress core. You don’t need to build any backend functionality – core provides it already with the ability to select any content from the site to add to a menu, reordering with drag and drop, and live preview of the end product in the customizer out of the box. Everything is easily portable across themes, with menus needing assignment to the appropriate locations but otherwise persisting across theme switches. There are things that core can do to improve the experience further for developers and users, but it works today. If theme developers begin to experiment with using menus to build and manage multi-part pages, users stand to benefit significantly in their ability to control how they present their content.

I should note that this is not “content blocks.” While that term typically refers to improved management of content within a post object, this proposal is intended to improve the way that different pieces of content can be organized.

Proof of Concept: Dynamic Seventeen Theme

To showcase this concept, in both code and a functional theme, I’ve created the Dynamic Seventeen theme. A child theme of Twenty Seventeen, it replaces the static page-based front page sections with dynamic menus-based content. It also adds a page template that turns any page into a dynamic content page, automatically creating an associated menu location for each page with the template. Page templates are not a fantastic experience currently, but this is a good example of how they can provide useful functionality.

Dynamic Seventeen sticks with the base design of Twenty Seventeen, featuring a list-type layout interspersed with large featured images. It also extends the concept of the two column layout by providing the ability to add subtitles or descriptive text to each section, under the post title. Leveraging the menu item description field for this is an example of how menus can provide additional functionality over other approaches without custom admin UI.

The child theme is available on WordPress.org repository. The code is not particularly complex, using a custom nav menu walker to retrieve information about objects associated with menu items and display templates matching the rest of the theme. I encourage theme developers to take this first example and adapt it to their themes, adjusting exactly what content is shown, what content types are supported (for example, not showing custom links), and the markup and styling of the results as needed.

Gif demonstration of setting up the Dynamic Seventeen themr in the customizer with menus.
Dynamic Seventeen dynamic content management with menus demonstration.

The Future of Dynamic Multi-part Pages in WordPress

Dynamic, multi-part pages are an important aspect of many larger sites because they offer a gateway to a diverse array of content in the site. But if site owners are unable to manage their content without hiring a developer, WordPress is only realistically useful in the long run for businesses with in-house development teams. Empower users to organize and showcase their own content by creating usable interfaces with live preview, allowing them to trust that their changes work as intended.

While the menus approach works without any core changes, there are several things that would make the user experience better for this and other innovative uses of menus:

  • #38957 – Customize Menus: Menu locations should be able to opt-out of menu item types that can be added to associated menus
  • #38956 – Customize Menus: menus assigned to locations with limited depths should not allow deeper depths
  • #18584 – Nav menus need more hooks for extensibility

There is also a core ticket to expand the functionality of static multi-part pages like Twenty Seventeen’s front page. I remain skeptical of this approach because of the significant technical debt and future maintenance associated with the major additions proposed, and the redundancy with the existing functionality of menus. Let’s improve what we have and build on it rather than turning to new features that duplicate functionality and ultimately further fragment the user experience.

Trust WordPress with Live Preview

When most of us walk into a building, we assume that it’s safe. We trust that it’s built to code and structurally sound. And we trust that the engineers and architects behind the building know what they’re doing.

If a room is too hot or cold, bright or dim, spacious and sprawling or tight and cramped, many people are uncomfortable and may even complain. Human comfort is the most important aspect of the design of physical space, yet it is nearly impossible comprehensively assess the experience of a space before it’s built.

The disconnect between designing a space and experiencing the end product is the biggest challenge in the building design industry. Digital products face similar challenges in bridging the gap between designing something and publishing it, but physical constraints pose fewer challenges here. WordPress has evolved to provide the potential to close this gap all the way to an end user managing content, by providing a framework for live previewing changes to a site before publishing them.

To fully understand the significance of live preview in the WordPress context, it is informative to consider examples of similar challenges and solutions in other industries. We’ll start with a few examples before returning to the topic of live preview and WordPress, and examining the importance of trust.

Previews in Structural Engineering

Most people trust structural engineers to design safe buildings and bridges. And engineers work diligently to consider every possible scenario that each structural element and connection may experience. But at the end of the day, most structural engineering problems are ultimately educated guesses.

In structural engineering, the governing equation is design < capacity. In other words, the load on the structure, from its own weight, the weight of its occupants, and environmental forces such as wind, snow, and earthquakes, must be less than the amount of load a given element can support. But both sides of these equations make numerous assumptions. Vertical loads are typically estimated as distributed area loads based on the design usage, while the capacity of a structural element is based on the expected properties of its material and shape. Demand loads are amplified and capacity reduced by safety factors to account for the potential uncertainties in both estimates; these factors of safety help engineers trust their designs despite these uncertainties.

In addition to making significant assumptions at every step of the design process, structural engineers are limited in their ability to preview the performance of a structure before it’s built. Small scale tests can be performed, and newer digital tools can apply known forces, such as historical earthquake data, to digital building models. But it’s impossible to know exactly what forces a structure may encounter throughout its lifetime, or how exactly the structural members will react. At best, structural engineers can be confident in their designs based on the relative safety factors between the estimated demand and capacity of a structure.

Animated gif showing a building frame bent in different vibration modes
Animated modal analysis demonstrating the potential (exaggerated) vibration modes of a building structure during earthquakes. Created with SAP 2000.

I have personal experience in the challenge of previewing the performance of structural designs via my work with concrete canoes. Last year, our team spent three months researching, developing a new design based on theoretical principles, and conducting tests and small scale experiments, to create a new structural design for our concrete canoe. We even built a full-size practice canoe with the new design and tested it in the water before finalizing the design. But despite hundreds of hours of work, our canoe failed during the race competition. We had not considered the ultimate failure mode in our evaluation of structural theory and small scale tests. And despite full scale testing with the practice canoe, this oversight combined with construction variances between the two canoes to result in the failure. Even building and testing a copy of a full structure does not guarantee that the final product will perform as intended, meaning that true previews of structural designs are not possible to create.

Two concrete canoes with three paddlers racing them in the water
USC’s colorful 2016 concrete canoe, That ’70s Canoe in competition at the American Society of Civil Engineers Pacific Southwest Conference, prior to the canoe’s structural failure.

Previewing Architectural Designs

As I mentioned earlier, architects face immense challenges in previewing the experience of the spaces they design. Working with consultants to design every aspect of a space from the shape, layout and dimensions, to the lighting, climate control, and finishes, architects typically draw two-dimensional representations of their designs so that they can be constructed. Technological advances have enabled three-dimensional modeling, from which two-dimensional construction documents are produced, along with more-fully-rendered images that convey the appearance of the finished product.

While construction drawings and renderings provide a visual preview of the appearance of a design, they do not offer a way to experience the space before it’s built. Full-scale mockups of smaller spaces can be built, but they can’t fully represent the context – views, natural lighting, etc. – of the final product. Walkthrough videos rendered from digital models and virtual reality experiences further the ability to visually preview designs, but lack comprehensive consideration of context and environmental comfort factors.

As building information modeling (BIM) evolves, the building design industry will continue to work toward an ability to preview designs as accurately as possible before they’re built. But the biggest challenge is the effort required to preview changes to a design. Current standard procedures for producing high-quality renderings can take weeks and thousands of dollars to produce updated images to reflect design adjustments. Changes can’t be previewed live, maintaining a disconnect between the design process and the finished product.

Live Previewing Music Compositions

Music composition and the design of aural space present similar challenges to the design of physical space. However, with music, every performance and recording will be different. Each group of musicians will interpret the music in their unique way, and the acoustics of the space they perform in will drastically influence their sound. These differences are actually welcomed by musicians, as every performance of a piece is unique.

Despite these challenges, composers have the closest thing to live preview of the examples I’m presenting here, via music notation software. Modern notation software, which typesets music much like Word does for text documents, typically has the ability to play music back after it’s written. Much of this already happens within a composer’s head, or as a piece is composed at the piano or another instrument; the playback functionality is a way to validate that everything comes together as it’s intended. A composer can change a note and immediately play back any part of the piece as needed to evaluate the impact of the change in context. Here’s an example of how this playback sounds, via a woodwind quintet I wrote last year:

Of course, this nearly-live preview is quite helpful but leaves a lot to be desired. Compare it to the following recording from a reading session. There are of course mistakes as it’s a first reading, not a performance. But the music really comes to life with the complex textures interwoven between the different instruments combined with the interpretations of the musicians:

With no two performances identical, the ability to fully preview a work before it’s first performed is limited. But composers can preview their work with a high degree of accuracy via digital playback, in an experience that’s almost live and ultimately does an excellent job facilitating the creative process. Live preview provides composers with instant validation that their ideas are correctly represented in a written piece, building trust that the work will be performed largely as intended.

Live Previewing Digital Publications

Working our way back to WordPress, let’s look at what’s possible with digital works. Many programs enable content to be created and previewed simultaneously by presenting an interface where content elements are directly editable. PowerPoints, PhotoShop projects, and even (to a high degree) Excel spreadsheets offer a preview of the final product as you build it. Other software for creating digital content has (sometimes necessary) disconnects between making changes and previewing the results – video and audio editing software, or things that can’t be immediately rendered such as sharelatex.com show how disruptive this can be to an end user.

Despite technological challenges, most publications intended to be distributed digitally should be able to be previewed live as they’re created. Considering a diverse array of content types on the web and elsewhere, this can certainly be challenging but is possible. Physical constraints such as the context of a particular building site, musicians’ unique interpretations of a piece, or fundamental uncertainty in the estimation of structural demands and load capacity do not apply to most digital works. In designing digital interfaces, software used to publish and distribute content should prioritize providing users with a live preview of changes as they’re made, at the expense of potential technical complexity, because live preview builds user trust in their work.

History of Live Preview with WordPress

As a platform whose goal is to democratize publishing, live preview is imperative to the usability of WordPress. Back in WordPress 3.4, a first attempt to incorporate this functionality was introduced with the theme customizer, Over time this evolved to support widgets (3.9), strategically expand in scope to become a framework for live-previewing any change to a site (4.0), support menu management (4.3), add selective refresh and device preview (4.5), and continue expanding its capabilities as a framework for live preview in 4.7. User trust is the core goal in providing live previews in WordPress.

The WordPress editor has also evolved to leverage live preview (as long as themes provide editor styles), with inline media/shortcode previews helping users trust that pasting a link on its own line creates an embed, for example. The biggest problem here is that the content is taken out of context, making it difficult to accurately preview the results. Opening a static preview in a separate window is the unfortunate current solution, creating an unnecessary disconnect between the writing and previewing processes. Bringing these together in a unified live preview experience would allow users to trust that their content will display perfectly, helping to stimulate their creative process as they publish content with WordPress.

Themes and plugins can extend the core frameworks for live preview that exist currently in WordPress. Implementing features like selective refresh in the customizer is critical for ensuring that the preview is as fast and preserves as much context as possible. Themes and plugins can also leverage live preview for managing dynamic portions of complex sites, extending menus or widgets to control the content featured on a page, for example. These implementations could eventually lead to improved core functionality for site management or even more direct site building with live preview.

Future Potential

As live preview becomes more integrated into the everyday workflow of publishing content with WordPress, users will become ever more confident in the publishing process. Trusting that the end product will match what you’re creating as you make it offers a faster workflow for everyone and improves the quality of content published with WordPress.

There are many ways to expand the scope of live preview in core, plugins, and themes. I see the most substantial potential in content editing – integrating it with the functionality currently in the “customizer” to offer a unified interface for live-preivewing most aspects of a site as users build content. This will surely take substantial effort from core contributors but if more volunteers continue stepping forward to contribute, we could conceivably see content editing with live preview in core within the next year.

Themes and plugins should also continue expanding their use of live preview as a mechanism for managing their functionality. Custom sites with complex frontends are great places to implement live preview – give your users confidence to manage their own content by letting them do so with the context of live preview.

In closing, I want to highlight that the customizer is WordPress’ framework for live-previewing any change to a site. With over four years of development to date, the customize API is already the easiest and most powerful way for developers to extend WordPress, and it’s getting even better with every release. And it supports live preview for any option. Let’s build on that framework, rethinking elements (such as the interface) that should be improved, to make WordPress better for everyone that uses it. With live preview, users can truly trust WordPress.

The Customizer is the Future for Themes and Theme Options

There has been a lot of backlash from the WordPress community recently over the theme review team’s decision to require theme options to be implemented in the Customizer. But this decision really is in everyone’s best interest.

WordPress 4.2 shipped with the ability to switch themes in the Customizer. When theme-installation is incorporated in a future release, the entire theme selection and customization process will be streamlined to a seamless workflow in which the user never enters the WordPress admin. This functionality is specifically targeted to users that leverage free WordPress.org themes, so it just makes sense for all themes hosted there to be Customizer-optimized. But the real win is the ability to live-preview changes before publishing them. With the Customizer, users know exactly what their site will look like when they publish their changes, a critical feature for anyone who cares what their site looks like when it’s publicly available.

Many people have been critical of the user-oriented nature of the Customizer. But its power is much stronger than most realize; one of my favorite use-cases for the customizer is custom CSS. This is the easiest way for users who want to go further to get into coding and offers a seamless experience that is infinitely better than the easy-to-kill-your-site-or-lose-your-changes-with code editor in the admin. In fact, I’d love to see a customizer-based custom CSS functionality in core as a replacement for the code editor, although I have a feeling that proposal may be too political to advance to an implementation. Bottom line, the customizer lowers the barrier to entry into WordPress development, contrary to many people’s thinking.

Yes, free themes requiring use of the Customizer will lead to a similar movement for client themes and premium themes. And that’s okay. In fact, by having everyone using the same underlying framework, users know where to look for options and have the confidence that live previewing provides. And WordPress will provide a more consistent visual experience for users as well.

You can really build any functionality into the Customizer. Theme-switching, widgets, and menus were all built as plugins first and continue to use the publicly available customizer API to run. So if you must, you can still create ridiculously complicated UI elements that no one will be able to figure out how to use, but you really don’t need to.

And complaints about the amount of screen real estate available and the 300px default width show a lack of creativity and resistance for the sake of resistance to change. Start by removing all of the ads, external links, unnecessary branding, unnecessary options, and general clutter. Make your options self-explanatory – if you need a paragraph to describe what it does, it probably shouldn’t be a user-facing option. Do you still have so much UI that the experience is completely unusable? Try an outside-the-box solution, like utilizing the core media modal (header images and core media controls use it), a custom modal (theme details modal in core), or a slide-out panel (widgets in core and eventually menus in core as well).

No, the customizer isn’t perfect. But it’s time to give it the respect it deserves as a significant part of WordPress. After three years of slow adoption, the theme review team’s decision to enforce its use is a welcome sign for users and a positive decision for the WordPress community as a whole. I’m excited to see what developers do with the Customizer’s amazingly powerful API and what core contributors come up with to improve its design and usability.

Proposed WordPress Customizer Theme-Switching UX

This is a proposal for how theme-switching and theme-installation could be incorporated into WordPress’ Customizer. This will eventually be attempted in some form as a feature-plugin to later be merged into WordPress core. The goal is to soften the distinction between themes and theme options and to make theme switching a fast, streamlined experience built-in with other Customization options in a unified interface.

Themes is a panel, but with backwards-sliding, coming in from the left instead of the right. This implies a new layer of hierarchy above the top-level controls. Switching contexts to the theme-browser is just like switching contexts to a panel, but to exit the themes context, you select a theme. The currently active/currently previewed theme is selected and has an arrow back to the right, to slide back to the top-level controls. All of this sliding can also be triggered by swiping on touch devices.

When a different theme is selected from the theme browser, it instantly slides back to the main panel of top-level controls, but now reflects the controls available in the new theme. This is accomplished by rendering the controls specific to the new theme via ajax and the new customizer sections/panels JS API, and then deleting the controls that were specific to the old theme. This should be doable in a back-compatible way by working some trickery with the existing customizer APIs, caching stuff, and/or leveraging WP-API.

The preview would instantly need to switch to a loading indicator until the front-end re-rendered with the new theme, but that shouldn’t take too long and is unavoidable regardless of the implementation here.

In the theme browser, the add-new-theme functionality would be present via a + new theme tile matching the one in the current interface, and bring up a modal containing the 3.9 pieces of THX. From there, the theme-installer previewer (also containing the theme details) would need to either remain in the (almost-full-screen) modal or open in a new tab that closed on install/close-button-click (or, do a full-screen iframe on top of the customizer and modal with the theme-install-preview, although that might get a bit crazy).

We would need a solution for unsaved changes in previewed themes that are not activated, as theme-specific controls are hidden/removed when previewing another theme.

Prerequisites:

  • JS API for adding and deleting panels, sections, settings, and controls, to complement the existing controls API.
  • Distinction/ability to save changes without publishing and/or the ability to save without activating a new theme. Although, not distinguishing between saving and saving and activating would probably make more sense here.

WordPress 4.0 Customizer API Improvements

I cross-posted much of this post to Make WordPress Core before WordPress 4.0 Beta 1. I’ll be updating this version with more examples throughout the beta period.

WordPress 4.0 features several new additions to the Customizer API (see also Theme Customization API). In this post, I’ll discuss the improvements in detail.

Customizer Panels

The Customizer now includes a new way to group options together: panels. Just like a section is a container for controls, a panel is a container for sections. This was implemented in #27406. In WordPress Core, widget management in the customizer has been consolidated into the “Widgets” panel. Instead of having as many sections as there are widget areas making a mess out of the customization experience, only one widgets section appears alongside the other customizer sections. But when you select it, rather then sliding down like regular sections, it slides over to reveal a new context for the entire customizer controls area. My Menu Customizer project also relies on this new panels functionality, as all menus can be consolidated into one panel. But themes and/or plugins with extensive options may also wish to create their own panels to better organize their controls, so we built an API for customizer panels. The Panels API is easy-to-use and works almost identically to the existing customizer section API. Add a panel with the following, within the customize_register action:

$wp_customize->add_panel( 'panel_id', array(
	'priority' => 10,
	'capability' => 'edit_theme_options',
	'theme_supports' => '',
	'title' => '',
	'description' => '',
) );

As always, only use the arguments where you aren’t using the default values. Note that the panel will not be displayed unless sections are assigned to it. To add a section to a panel, just use the panel id for the new panel argument:

$wp_customize->add_section( 'section_id', array(
	'priority' => 10,
	'capability' => 'edit_theme_options',
	'theme_supports' => '',
	'title' => '',
	'description' => '',
	'panel' => 'panel_id',
) );

You may notice that $wp_customize->add_panel and $wp_customize->add_section have the same arguments (other than panel, of course). This is because panels are a special type of section; technically speaking, WP_Customize_Panel extends WP_Customize_Section. Your sections are backwards-compatible: you can add the panel argument to existing sections without issues. However, you do need to check for the existence of WP_Customize_Manager->add_panel() if you’re maintaining pre-4.0 compatibility. As with Customizer Sections, you can access and modify Panels via:

  • $wp_customize->get_panel( $id );
  • $wp_customize->remove_panel( $id );

New Built-in Customizer Controls

WordPress core now provides support for a much wider array of Customizer controls. Implemented in #28477, these changes eliminate the need to create custom controls for most common use cases. The textarea type is now supported in core. For any type of input that uses an input element, you can simply specify the type attribute using the type parameter of $wp_customize->add_control(). Here’s an example:

$wp_customize->add_control( 'setting_id', array(
	'type' => 'url',
	'priority' => 10,
	'section' => 'title_tagline',
	'label' => 'URL Field',
) );

Which results in the following markup in the Customizer:

<li id="customize-control-setting_id" class="customize-control customize-control-url">
<label>
<span class="customize-control-title">URL Field</span>
<input type="url" value="" data-customize-setting-link="setting_id">
</label>
</li>

This is pretty powerful, as you can now use the built-in WP_Customize_Control for most common use-cases rather than creating a custom control. But what about input types like number and range that require additional attributes like min, max, and step?

New Built-in Customizer Control Parameters

First of all, all of the built-in Customizer controls (including the custom controls such as WP_Customizer_Color_Control) now support descriptions, just like Customizer sections have descriptions (see #27981). This was much-needed and allows for inline help text at the control level. More interestingly, to complement the new support for arbitrary input types, a new input_attrs parameter allows you to add attributes to the input element (also implemented in #28477). This extends beyond just using min, max, and step for number and range, to the ability to add custom classes, placeholders, the pattern attribute, and anything else you need to the input element. Here’s an example:

$wp_customize->add_control( 'setting_id', array(
	'type' => 'range',
	'priority' => 10,
	'section' => 'title_tagline',
	'label' => 'Range',
	'description' => 'This is the range control description.',
	'input_attrs' => array(
		'min' => 0,
		'max' => 10,
		'step' => 2,
		'class' => 'test-class test',
		'style' => 'color: #0a0',
	),
) );

Which results in the following markup in the Customizer:

<li id="customize-control-setting_id" class="customize-control customize-control-range">
	 <label>
		 <span class="customize-control-title">Range</span>
		 <span class="description customize-control-description">This is the range control description.</span>
 <input type="range" min="0" max="10" step="2" class="test-class test" style="color: #0a0;" value="" data-customize-setting-link="setting_id">
	 </label>
 </li>

Which displays as follows (in Chrome 35): customizer-4.0-range-control

The ability to add classes is particularly useful if you need to target specific controls with CSS or JS, but it doesn’t need to have any special markup. I’m using this in the Menu Customizer for the Menu Name field, which is just an ordinary text control with a special setting type.

Contextual Controls

Customizer controls can now be displayed or hidden based on the Customizer’s preview context. For example, options that are only relevant to the front page can be shown only when the user is previewing their front page in the Customizer (see #27993). This is already implemented in core for Widgets; Widgets have always been contextually faded and shown/hidden based on their visibility in the preview, but this functionality is now built off of the core active_callback API in both PHP and JS. There are three different ways to specify whether a given control should only be displayed in a certain context. The first, and most straightforward, is to use the active_callback argument in $wp_customize->add_control().

$wp_customize->add_control( 'front_page_greeting', array(
	'label'      => __( 'Greeting' ),
	'type' => 'textarea',
	'section' =>
	'title_tagline',
	'active_callback' => 'is_front_page',
) );

Note that you may use either built-in conditional functions or a custom function. If you have a custom control (via a subclass of WP_Customize_Control) and a custom callback function, you can skip the active_callback argument and override the active_callback function instead:

class WP_Greeting_Control extends WP_Customize_Control {
	// ...

	function active_callback() {
		return is_front_page();
	}
}

Finally, the customize_control_active filter will override all of the other active callback options and may be a better solution in certain cases (note that this particular example will be avoidable with future work on expanding the Customizer’s JS API, and does not hide the title_tagline section, only the controls in it):

function titletagline_customize_control_active_filter( $active, $control ) {
	if ( 'title_tagline' === $control->section ) {
		$active = is_front_page();
	}
	return $active;
}
add_filter( 'customize_control_active', 'titletagline_customize_control_active_filter', 10, 2 );

In addition to the PHP API for contextual controls, you can override the control-visibility-toggle function on the JS side. By default, controls will slideUp and slideDown as they become visible or hidden when the Customizer preview is navigated. If you’re familiar with the Customizer control JS API (see wp-admin/js/customize-controls.js, and wp.customize.Control), the Widgets implementation of a custom toggle function is a good example:

api.Widgets.WidgetControl = api.Control.extend({
// ...
   /**
    * Update widget control to indicate whether it is currently rendered.
    *
    * Overrides api.Control.toggle()
    *
    * <a href='http://profiles.wordpress.org/param' class='mention'>@param</a> {Boolean} active
    */
    toggle: function ( active ) {
        this.container.toggleClass( 'widget-rendered', active );
    },
// ...
) };

/**
 * Extends wp.customize.controlConstructor with control constructor for widget_form.
 */
$.extend( api.controlConstructor, {
    widget_form: api.Widgets.WidgetControl,
} );

Changes to the customize_update_ and customize_preview_ Actions

You probably already know that the Customizer supports both option and theme_mod types for settings. But did you know that you can register arbitrary types? Since this is generally undocumented, I’ll show how it works (this has been in place since 3.4):

$wp_customize->add_setting( 'setting_id', array(
	'type' => 'custom_type',
	'capability' => 'edit_theme_options',
	'theme_supports' => '',
	'default' => '',
	'transport' => 'refresh',
	'sanitize_callback' => '',
	'sanitize_js_callback' => '',
) );

There are a few actions that you can use to handle saving and previewing of custom types (option and theme_mod are handled automatically). Namely, customize_update_$type and customize_preview_$type are useful here. Previously, the value of the setting was passed to these actions, but there was no context. In 4.0, via #27979, the WP_Customize_Setting instance is passed to these actions, allowing more advanced saving and previewing operations. Here’s an example from my Menu Customizer project:

function menu_customizer_update_menu_name( $value, $setting ) {
...
	// Update the menu name with the new $value.
	wp_update_nav_menu_object( $setting->menu_id, array( 'menu-name' => trim( esc_html( $value ) ) ) );
}
add_action( 'customize_update_menu_name', 'menu_customizer_update_menu_name' );

This part of the Customizer API is a bit too complex to fully explain here, as most of it already existed, but suffice to say that the addition of the setting instance to these actions greatly expands the possibilities of working with custom setting types in the Customizer.

New “customize” Capability

Note: this API component is coming in 4.0 beta 2.

The Customizer has been decoupled from edit_theme_options in favor of a customize meta capability, which is mapped to edit_theme_options by default. This allows for wider use of the Customizer’s extensive capability-access options, which are built into panels, sections, and settings. Additionally, this makes it possible to allow non-administrators to use the customizer for, for example, customizing posts. This change is an important step to expanding the scope of the Customizer beyond themes. See #28605. To allow users with lower capabilities to access the Customizer, use something like the following:

function allow_users_who_can_edit_posts_to_customize( $caps, $cap, $user_id ) {
        $required_cap = 'edit_posts';
        if ( 'customize' === $cap && user_can( $user_id, $required_cap ) ) {
                $caps = array( $required_cap );
        }
        return $caps;
}
add_filter( 'map_meta_cap', 'allow_users_who_can_edit_posts_to_customize', 10, 3 );

Customizer Conditional Function

The new is_customize_preview() conditional function can be used to check whether the front-end is being displayed in the Customizer. The naming derives from the fact that the term “preview” applies to both theme previews and previewing changes before saving them. See #23509 for some sample use-cases from WordPress.com.

Examples

Look at the Widget Customizer and Menu Customizer code for more examples of many of these features. Please feel free to ask in the comments if you have you questions with any of these implementations; I spent a good amount of time preparing and reviewing the associated patches and soliciting feedback in the process of adding these changes to core.

Use This API for Good, not Evil

These new additions to the Customizer API greatly expand the ability to create intricate options for users. But please don’t forget about WordPress’ core philosophies. So, before you go adding entire panels full of new options, remember to strive for simplicity and design for the majority, even in themes and plugins. These additions make the Customizer better for developers; now, let’s make it as good as it can be for our end-users.

GSoC Menu Customizer Revised Schedule/Scope

Previously: GSoC Project Proposal: WordPress Menu Customizer.

Week 1 – 5/19: Introduce the ability to view all existing menus as customizer sections with menu items as customizer controls.

Week 2 – 5/26: Add the ability to edit menus (change labels, attributes, re-order items), including a temporary solution that includes the screen options found on the existing menus screen. Run user tests on the existing menu management screen to inform UI decisions for the initial iteration, coordinating with the WordPress core UI team.

Week 3 – 6/2: Implement an input-type-agnostic re-ordering mode, merging the existing UIs on the Menus screen and in the Widget Customizer (should particularly help with touch & keyboard input). Implement a version of #27406 into the plugin (pending its completion for core, potentially also assist with the core patch if needed), to maintain 3.9 compatibility. Move all menus (customizer sections) to the menus/navigation super-section, and implement the theme location controls in the new interface. Begin implementing a panel to add new widgets, potentially re-using components from the Widget Customizer’s equivalent UI (and potentially making it more easily re-usable outside of core).

Week 4 – 6/9: Create the ability to add items to menus, utilizing the slide-out panel from the Widget Customizer. For the first iteration, include sections containing pages, custom links, and categories, similar to those on the existing menus page.

Week 5 – 6/16: Second iteration of the add-new interface. Introduce a global search feature, an experimental approach to adding custom links, add all appropriate post types and taxonomies, and create a one-click add/remove menu items mode. Implement any additional ideas for adding items proposed by the WordPress core UI team.

Week 6 – 6/23: Midterm evaluations – critical functionality should be complete (editing & adding to menus, changing menu locations). Publish plugin (with WordPress 3.9 compatibility) on WordPress.org repository to facilitate community testing & feedback. Begin extensive user testing to facilitate further UI iterations. Add ability to create new menus, and delete menus, with the appropriate corresponding menu location UIs adapting accordingly.

Week 7 – 6/30: Address the need to implement screen options into the new menus interface. Work through the list of outstanding issues with the implementation, and begin responding to community feedback. Much of these will likely be UI/UX quirks that come up through the development process and are delayed in favor of completing the basic functionality. Examples could include dealing with deep menu-nesting (sub-menus) within the narrow customize controls area.

Week 8 – 7/7: Implement refinements for simplified use-cases, such as those added in WordPress 3.6 (#23119). Continue addressing bug fixes and enhancements based on community feedback. Add new hooks and create usage examples for them (#18584), if scaling issues can be resolved.

Weeks 9 – 12 – 7/14-8/4: Run user tests on the existing menus screen and the Menu Customizer. Iterate the UI and codebase based on user tests and feedback from WordPress core designers and developers, giving special attention to the experience for new users and a stronger emphasis on the ability to use menus in widget areas. Ensure the code is thoroughly documented and meets all core style guidelines. Test in all supported browsers and devices, with as many themes as possible, and with as many edge-cases as is feasible (ie, massive menus, huge numbers of menus, deep hierarchies, etc.). Fix bugs as they come up. Address whether the functionality is ready for core. If all goes well, consider whether the Menu Customizer could potentially replace the existing menus screen for supported users and develop approaches for user-discovery (for example, deep-linking).

Week 13 – 8/11: Prepare a core patch for the plugin merge, and draft final proposals for inclusion of the feature in core. Final project, as both a functioning plugin and a core patch, should be competed by the firm pencils-down date of 8/18. In the event that the plugin is unlikely to be accepted for core inclusion, continue development of outstanding issues and gathering feedback from the community, with the goal of reaching a good stopping point for the official end of GSoC.

GSoC Project Proposal: WordPress Menu Customizer

Please note that this post only contains the Project Description and Schedule of Deliverables sections, as they are the most relevant to public discussion.

Project Description

Describe your idea in detail:

WordPress 3.9 introduces the Widget Customizer: a better way to edit widgets. This is a major step in the process of migrating every component of WordPress’ Appearance menu to the Theme Customizer, where users can live-preview their changes before publishing them. The remaining features that should be incorporated into the Customizer are theme-switching, menu management, and improved background-image handling. Once the Customizer is feature-complete, we can begin to experiment with alternative approaches to accessing the customizer, making it feel more like an editing mode on the front-end of the site, alongside the front-end content-editor.

Menu management would be a particularly useful addition, as it could address long-standing usability concerns with menus and theme locations. The Menu Customizer would offer the ability to visualize where menus are located, as well as how the order of menu items and sub-menus are displayed in the theme. The menus screen was refreshed a year ago in WordPress 3.6, and the research and user testing completed during that process provides a good starting point for implementing menu management in the customizer.

The user interface of menu management in the customizer would be comparable to that of the Widget Customizer. The first step would be to either implement or abstract functionality for super-sections in customizer controls, where the top-level section heading slides over to reveal sub-sections containing each menu (and for widgets, each widget area, see #27406). The scope of my work here depends somewhat on whether this is addressed before GSoC starts, but the goal will be for this functionality to exist in an API in core, which is utilized by both menus and widgets.

Unlike widgets, menus are not theme-specific, and new menus can be created at-will. The existing menus / theme locations paradigm should be maintained by migrating the existing theme locations selector to the new interface, and adding the ability to create, edit, and add to individual menus, all within the super-section of customizer controls. There should be a mechanism to easily identify the currently active menu in the preview, and to identify the corresponding menu in the controls when exploring the preview. Menu items should be able to be re-ordered and moved into and out of sub-menus several levels deep. New items should be able to be added from all of the sources available on the menu management screen (post types, taxonomies, and custom links). Ideally, support for custom post types and taxonomies should be added as well (see #16075). Adding menu items could work similarly to adding widgets, with a slide-out panel, but the visual organization of items within the panel would need work, as widgets do not have hierarchy. The entire interface must be accessible for all input types, including keyboard, mouse, and touch. Since the Customizer doesn’t have a concept of “Screen Options,” the screen options in the current menus interface should be ported to the Menu Customizer in some way if possible.

The technical implementation would likely be similar to that of the Widget Customizer feature. Like many JavaScript-based features in WordPress, including the Widget Customizer, the Menu Customizer would be implemented with Backbone.js. Technical improvements to menu-management could also potentially be ported back to the existing menu management screen, eliminating the current issues with scaling by only saving data that is changed (#14134). While re-factoring nav-menus.php would not be in scope for the Menu Customizer project initially, the work done here should be able to be ported to the old interface easily and could potentially be added to the scope of the project if it is ahead of schedule. The Menu Customizer would provide a workaround for users affected by #14134, too, as the new Backbone-powered UI shouldn’t have scaling issues. If the Menu Customizer provides all of the features of the existing menu management screen, while clearly demonstrating that it is a better solution than the existing screen in user tests, it could potentially replace the existing screen entirely for users that can access the Customizer (JS enabled, IE8+, IE 10+ with domain-mapped front-end).

In addition to adding the menu management functionality, this project would make other small improvements to the customizer as necessary, such as an API for super-sections and the slide-out item-adding panel, and better documentation and code examples of the customizer, as time allows.

What have you done so far with this idea:

I have shared a broader customizer-improvements proposal on wp-hackers and discussed it with Andrew Nacin and Lance Willett. Of the ideas I proposed, menu management and theme switching in the customizer are the most intriguing, and the most complex.

Lance indicated that there is ongoing work in many of the areas of the customizer, including background image improvements and conceptual theme-switching ideas. Other ideas I proposed, such as adjusting the way users access the customizer to make it feel more like an editing mode, like front-end-editing, would benefit from the customizer being more feature-complete first. Theme-switching would require extensive new UI/UX development, while Menu Management would use a similar UI to the Widget Customizer. Therefore, menu-management in the customizer seems to be a good place for a GSoC project to develop a new solution.

Nacin suggested that menus should be implemented in Backbone.js, and that the current menu management screen could also benefit from this improved approach. Perhaps both UIs could share the same core interface and code. I’ve began investigating existing Backbone.js implementations in WordPress core, such as the new “THX” themes screen, as well as researching the principles behind Backbone.js. I’ve also added consideration for potential improvements to the existing screen to my project description, although if the Menu Customizer is implemented well enough it could potentially replace the existing screen entirely for supported users. Unlike with widgets, it should be possible to incorporate all of the existing features within the customizer to the extent that there is no compelling reason to maintain the standalone menus screen. However, this consideration would be made near the end of the project and is more of a long-term implementation consideration than a definite objective.

Plugin, theme, or core: The Menu Customizer will be developed in a plugin, with every intention of being included in core. This means that all core coding and inline documentation standards must be observed throughout the project, and it should be as lean as possible in terms of both code and UI. Given the project timeline, it is likely that this plugin would be a proposed feature plugin for inclusion in WordPress 4.1.

Supporting code such as super-section and slide-out panel APIs in the customizer would likely be developed directly as core patches, but would potentially also be included with the plugin to facilitate testing the plugin while running older versions of WordPress.

Anticipated challenges: Menus are tricky, and core may not have found the best UI for them yet. While the Menu Customizer aims to fix many of the issues with the current interface, there is always the chance that it introduces additional usability issues. It has been proposed that menus should be tied to pages rather than site “appearance,” but there are inherent issues with this approach that have caused much pushback from the WordPress community. Therefore, the Menu Customizer project aims to maintain the paradigms of the existing system, while providing a new interface with which to manage it. Once the functionality is completed, any issues should be easy to identify by running user tests. If the internals are well-constructed, tweaking the interface to adapt to any issues that arise should be straightforward. The Backbone.js-based implementation will enable this flexibility. There is a good chance that the Menu Customizer combined with the Widget Customizer will make the ability to add menus to widgets clearer; some effort will be dedicated to ensuring that this interaction works well (adding a menu, then adding it to a widget).

Finding a good way to highlight menu edit-ability in the preview will likely be one of the more challenging UI aspects to consider after the functionality is complete, as that issue affected the Widget Customizer project.

Potential mentors: No preference.

Schedule of Deliverables

Milestones and deliverables schedule:

I plan to work 40-hour weeks throughout the project to ensure that the Menu Customizer can be completed and prepared for a potential core merge by the end of GSoC. Each week would function as a cycle with clearly defined progress goals to ensure that the entire project stays on schedule. Once enough of the functionality is in place, the plugin where the Menu Customizer is developed would be released on WordPress.org with updates being pushed every Friday at the completion of each cycle.

  • Community Bonding Period: work with mentor to adjust project scope and implementation strategies. Research the Widget Customizer implementation as well as other uses of Backbone.js in WordPress core to determine a specific plan for implementation. Research the WordPress 3.6 menus refresh for potential UI/UX considerations. Monitor potential progress of Customizer super-section support in core (for widgets), and adjust project schedule accordingly (much of the work scheduled for the first few weeks could be eliminated if someone else picks this up before GSoC starts, in which case more time could be devoted to working on the Menu Customizer itself). Super-sections are a prerequisite for implementing the Menu Customizer, but could be implemented via the plugin first if needed.
  • Week 1 – 5/19: develop (or abstract from widgets) an API for WordPress core that allows super-sections in the Theme Customizer, depending on potential work by others during the community bonding period (after the release of WordPress 3.9). Post a complete draft patch to core trac by the end of the week. Determine Menu Customizer plugin structure and create the plugin files and outline the structure with documentation. Continue researching specific implementation strategies based on existing work in WordPress Core.
  • Week 2 – 5/26: work with core developers to improve and finalize the Customizer super-section API and get it committed to core trunk. Develop an API for a slide-out panel in the customizer (this is the panel that is used to add widgets and would be used to add menu items; may end up being a full-fledged addition to the Customizer API, may only be extracting re-usable functionality from the add widgets panel to be used more generically), and submit as core patches. Begin modifying the core Widget Customizer implementation to utilize the new super-sections. Continue outlining the plugin structure.
  • Week 3 – 6/2: Begin working on the Menu Customizer itself in earnest. Introduce the ability to view all existing menus as customizer sections with menu items as customizer controls in the plugin by the end of the week. Migrate theme locations controls to the new interface. Submit core patches for using the new super-section API for managing widgets.
  • Week 4 – 6/9: Add the ability to edit menus (change labels, attributes, re-order items), with the Customizer’s live preview updating accordingly. Release initial version of plugin on WordPress.org.
  • Week 5 – 6/16: Add ability to add items to menus, utilizing the slide-out panel abstracted from the Widget Customizer.
  • Week 6 – 6/23: Midterm evaluations – critical functionality should be complete (editing & adding to menus, changing menu locations). Add ability to create new menus, and delete menus, with the theme location selectors adapting accordingly.
  • Week 7 – 6/30: Work through the list of outstanding issues with the implementation. Much of these will likely be UI/UX quirks that come up through the development process and are delayed in favor of completing the basic functionality. Examples could include addressing the screen options in the existing menu management interface and dealing with deep menu-nesting (sub-menus) within the narrow customize controls area.
  • Week 8 – 7/7: Complete all features and fixes in-scope for a solid 1.0 by the end of this cycle.
  • Weeks 9 – 12 – 7/14-8/4: Run user tests on the existing menus screen and the Menu Customizer. Iterate the UI based on user tests and feedback from WordPress core designers and developers. Ensure the code is thoroughly documented and meets all core style guidelines. Test in all supported browsers and devices, with as many themes as possible, and with as many edge-cases as is feasible (ie, massive menus, huge numbers of menus, deep hierarchies, etc.). Fix bugs as they come up. Address whether the functionality is ready for core. If all goes well, consider whether the Menu Customizer could potentially replace the existing menus screen for supported users and develop approaches for user-discovery (for example, deep-linking).
  • Week 13 – 8/11: Prepare a core patch for the plugin merge, and draft final proposals for inclusion of the feature in core. Goal to have final project, as both a functioning plugin and a core patch, competed by the firm pencils-down date of 8/18. In the event that the plugin is unlikely to be accepted for core inclusion, continue development of outstanding issues and gathering feedback from the community, with the goal of reaching a good stopping point for the official end of GSoC.

Other commitments: I will be taking exams during the community bonding period, but my semester ends the week before GSoC officially starts. Otherwise, I am available for the entire summer.

 

On Contributing to WordPress Core

I’m honored to be featured on the WordPress 3.8 Credits page as a Contributing Developer/Recent Rockstar (Matt decided to list everyone in one big group this time instead of breaking it up, but the group is ordered randomly by a level of regularly active developers—the traditional “Contributing Developers”–and a level of developers who showed increased involvement and significant help in WordPress 3.8, the traditional “Recent Rockstars”).

My journey to this point has been surprisingly quick, and I’ve enjoyed every step of the way. Just a year ago, I was first discovering the Make WordPress Core blog, reading all of the discussions from the end of WordPress 3.5 development and into the beginning of WordPress 3.6 planning. I started reading some of the IRC logs, trying to understand how core development worked, how decisions were made, etc.

I think this initial phase of absorbing knowledge of the WordPress development system, procedures, and cultures is one of the reasons why I was able to become a fairly regular contributor so quickly. But making the jump from following discussions to becoming involved wasn’t easy. I saw several discussions on trac tickets or in the IRC logs that I felt like I wanted to comment on, and I eventually dived in, first on trac and much later on IRC.

I remember my firsts quite clearly. First ticket: #23841- Twenty Thirteen: Fixed Navbar not activated in IE10. First patch: 23996.3.diff, I realized that I knew how to fix a bug I’d reported, once it’d been discussed some on the ticket. First props: [23959], committing that first patch. First PHP patch, and subsequent commit: for Accent Colors (also a feature request) – #25220 and [25418], which was eventually extracted to the Fourteen Colors plugin.

After dabbling in the (unfortunately fairly unorganized) feature plugin teams at the beginning of 3.7/3.8 development, I decided to focus on Twenty Fourteen, since my first few contributions were to Twenty Thirteen in WordPress 3.6. I attended almost every IRC meeting and created a lot of trac tickets. I spurred several discussions and fixed several bugs. What I didn’t realize until recently was just how many tickets I created for Twenty Fourteen, and that’s not counting others that I patched.

Looking back, I think I made a pretty big impact on Twenty Fourteen, and that’s a good feeling. It’s definitely my favorite default theme to date, and I’m already running it on the USC ASCE website that I maintain. Going forward, I’d like to contribute more to core itself (as apposed to bundled themes). While it’s much easier to make an impact on a feature team like Twenty Fourteen, I don’t want to try to wade through the still-in-progress features-as-plugins system, where communication and work is currently happening all over the place. I really like how default theme development is managed, so I’ll definitely contribute to Twenty Fifteen. Until then, I think I’ll focus on smaller contributions to core tickets, most likely starting with addressing the lack of media support in the Theme Customizer(and other customizer improvements), and some WordPress projects outside of core, including my first publicly available theme, Figure/Ground.