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 currently pending review for the repository, so it is available here for now. 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 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.

A Strategy for Custom Colors in the Customizer

The customizer is a framework for live-previewing any change to a WordPress site, and it is particularly useful for previewing visual changes. It has always shipped with a color control and the ability to preview custom colors with little effort, but the previewing experience has often been a bit slow. This post outlines a strategy for custom color options that leverages instant JS-based previewing in conjunction with selective refresh.

Animated gif of the linework theme with its colors changing via the customizer
Demo of instant custom color previews in the customizer with the Linework theme.

Example Plugin: Custom Highlight Color

I’ll leverage the custom highlight color plugin as an example of this approach. I recommend downloading it from to follow along with, and I’ll provide a detailed walkthrough of the code with excerpts here.

This plugin only has one option – the highlight color. However, this approach can easily scale to additional options. As I’ll show later, it’s best to minimize your options and instead rely on code logic to generate or select variations as needed so that users can achieve custom results with minimal effort and decision-making. Finding the right balance of color options is an important step in the product design process, and one where even the past couple of default WordPress themes leaned a bit too far in the direction of options, in my opinion.

Adding Customizer Objects

The first step is to register your color options in the customizer via the PHP API. We can use the colors section provided by core, leaving the setting and control to be registered in your theme or plugin. The transport will be postMessage, indicating that we’ll preview the setting with JavaScript:

function custom_highlight_color_customize( $wp_customize ) {
	$wp_customize->add_setting( 'custom_highlight_color', array(
		'type' => 'option', // Change to theme_mod when using in a theme.
		'default' => '#ff0',
		'sanitize_callback' => 'sanitize_hex_color',
		'transport' => 'postMessage',
	) );

	$wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'custom_highlight_color', array(
		'section' => 'colors',
		'label' => __( 'Highlight Color', 'custom-highlight-color' ),
	) ) );
add_action( 'customize_register', 'custom_highlight_color_customize' );

The setting will use sanitize_hex_color, ensuring that a single secure hex color code is saved in the database for each option. For themes, you should set the type to theme_mod instead of option, and it’ll be stored with the rest of the theme-specific options automatically.

Color Patterns and Calculations

Next, we need to define the CSS that will display the custom color options. By putting this into a distinct function, the code can be leveraged in multiple preview and output contexts. When there’s a lot of CSS, I prefer to break this into a separate file to make it easier to maintain. You can even split distinct parts of the color CSS into different functions. For a simple example, here’s what Custom Highlight Color does:

function custom_highlight_color_css() {
	require_once( 'color-calculations.php' ); // Load the color calculations library.
	$background = get_option( 'custom_highlight_color', '#ff0' ); // The second argument is the default color when the theme mod is undefined.
	// Set the text color to black or white, whichever provides higher contrast with the highlight color.
	if ( custom_highlight_color_contrast_ratio( $background, '#000' ) > custom_highlight_color_contrast_ratio( $background, '#fff' ) ) {
		$color = '#000';
	} else {
		$color = '#fff';

	$css = '
		::-moz-selection {
			background: ' . $background . ';
			color: ' . $color . ';
		::selection {
			background: ' . $background . ';
			color: ' . $color . ';
	return $css;

You’ll notice that there are some color contrast checks here, which automatically set the text color to ensure that it contrasts with the highlight color. In this case it looks for the higher contrast between two colors, but typically you’ll want to ensure that the contrast is at least 4.5 between background and text colors. These checks leverage the color-calculations.php functions that I originally developed for the Fourteen Colors plugin. Feel free to take this file from the custom highlight color plugin and ship it with your project (make sure you update the function prefixes to match your plugin or theme).

In addition to the contrast check (which is done per the WCAG guidelines), the color calculations library has a handy function to “adjust” a color. You can use this to brighten or darken a color by a numeric amount, generating color variations automatically. The Fourteen Colors plugin uses this technique extensively.

Color Output

Now that our color patterns are defined, it’s easy to display the color CSS within style tags in wp_head. However, in the customizer preview, we also need an easy way to get the current colors in JavaScript. To do that, we’ll conditionally add the colors as data- attributes when is_customize_preview():

add_action( 'wp_head', 'custom_highlight_color' );
function custom_highlight_color() {
	if ( is_customize_preview() ) { 
		$data = 'data-color="' . get_option( 'custom_highlight_color', '#ff0' ) . '"'; 
	} else {
		$data = '';
	<style type="text/css" id="custom-highlight-color" <?php echo $data; ?>>
		<?php echo custom_highlight_color_css(); ?>
<?php }

The colors should now display on the front end, but they won’t preview in the customizer just yet.

Instant Custoizer Previews with JavaScript

To preview the color changes instantly in the customizer, we first need to enqueue a JS file to manage color previews (if your theme already loads a customizer JS file, you can add to that in lieu of introducing another one):

function custom_highlight_color_customize_preview_js() {
	wp_enqueue_script( 'custom_highlight_color_customizer', plugins_url( '/customizer.js', __FILE__ ), array( 'customize-preview' ), '20160830', true );
add_action( 'customize_preview_init', 'custom_highlight_color_customize_preview_js' );

In that file, we’ll follow the standard customizer preview conventions and bind to changes on our settings. For each of the colors, we’ll search for instances of the original color in the CSS, and replace them with the new color:

( function( $ ) {
	wp.customize( 'custom_highlight_color', function( value ) {
		value.bind( function( to ) {
			// Update custom color CSS
			var style = $( '#custom-highlight-color' ),
			    color = 'color' ),
			    css = style.html();
			//css = css.replace( color, to );
			css = css.split( color ).join( to ); // equivalent to css.replaceAll.
			style.html( css )
			     .data( 'color', to );
		} );
	} );
} )( jQuery );

You’ll need to bind changes to each of your color settings if you have multiple color options. Now, you’ll be able to preview color changes instantly in the customizer. But what about the colors generated using color calculations in PHP?

Adding Selective Refresh for Secondary Colors

To supplement the instant JS previewing that updates the CSS with a search-and-replace of the color value, we need to add selective refresh support so that the CSS is re-rendered from PHP with our color calculations applied. The color patterns and calculations could be duplicated in JS, but that would become quite difficult to maintain and offers only a slight usability benefit. With selective refresh, we can leverage the existing function in PHP; it’s only a matter of adding a customizer partial that will be refreshed when one of the associated colors changes:

$wp_customize->selective_refresh->add_partial( 'custom_highlight_color', array(
	'selector'        => '#custom-highlight-color',
	'settings'        => array( 'custom_highlight_color' ),
	'render_callback' => 'custom_highlight_color_css',
) );

This code should be added within the same callback to the customize_register action that we added earlier. Multiple settings can be associated with a single partial; add the other setting ids to the array of settings.

Once that’s complete, you should be able to preview all of your custom colors in the customizer, with instant updates to base colors and updates to generated colors happening on a slight delay. Colors are safely stored in the database without the security issues of saving CSS there, and styles are applied on the front end as expected. I’m now leveraging this approach in all of my themes and plugins as I find it to provide a nice balance between user experience and code simplicity.

The custom highlight color plugin is a simple example, built specifically to be an example, but this approach easily scales to more colors as needed. For a more complex example, check out the code for the Fourteen Colors Plugin or the Figure/Ground theme (which runs this site and lets users customize every color).