Eben Gilkenson

Displaying a Custom Taxonomy Archive on a WordPress Home Page

After building a theme with a custom post type and taxonomy to display galleries of paintings, I got what seemed like a simple request to set one of these galleries as the home page. Unfortunately, out of the box, WordPress doesn’t give you any way to choose anything for the front page beyond a drink-from-the-firehose feed of posts or a static page. Further customization would be required.

My first thought was to create a page template that would display a gallery based on a new query that would draw from a custom field on that page. The user could then set this custom field to the slug or ID of the gallery that they wanted and set this page as the static home page.
This works. It’s just not terribly elegant and may be confusing for a tech-averse artist to deal with if she wants to change her featured gallery in a few years.

Moving on from Options Pages

After seeing what’s already possible and what’s planned for the Customizer, which has been receiving steady updates since being introduced in 3.4, I don’t expect to be creating many options pages going forward. For user-focused customization features, the Customizer, with its single-page design and live previews, is definitely where it’s at. For things like changing fonts, colors and element layouts, not having to click save and then go view the page makes for a much, much better user experience.

In this case, we only have one simple option that we need to be available: Which gallery should be on the front page? Like my original plan to use a page template, I could just ask the user to remember the gallery slug or ID and enter it into a plain text field, but it’s only a couple of lines of PHP to display a select menu with a list of all the galleries.

/**
 * Customizer Options
 */

function dlk_customizer( $wp_customize ) {

  // Get all of the galleries as an array
  $terms = get_terms( array(
    'taxonomy'   => 'gallery',
    'hide_empty' => false,
  ));

  // Pull the IDs and names from the galleries and place them
  // in a new array of key/value pairs for the select control
  $choices = array();
  foreach($terms as $term) {
    $choices[$term->term_id] = $term->name;
  }

  // Add the section to appear in the Customizer
  $wp_customize->add_section(
    'dlk_front_page',
    array(
      'title'       => 'Front Page',
      'description' => 'Choose a gallery for the front page.',
      'priority'    => 35,
    )
  );

  // Create the setting that to store the selected gallery
  // and set it to the first gallery as the default
  $wp_customize->add_setting(
    'dlk_featured_gallery',
    array(
      'default' => $choices[0],
    )
  );

  // Create the select control and populate it with the list
  // of galleries with their IDs as the input value
  $wp_customize->add_control(
    'dlk_featured_gallery',
    array(
      'type' => 'select',
      'label' => 'Featured Gallery:',
      'section' => 'dlk_front_page',
      'choices' => $choices
    )
  );

  // Remove the normal Front Page options from the Customizer
  $wp_customize->remove_section( 'static_front_page');
}

add_action( 'customize_register', 'dlk_customizer' );

To add a setting to the Customizer, we first create a section in which to place it. We’ve named it dlk_front_page here. As always, it’s smart to prefix everything in WordPress, so as not to conflict with any plug-ins the might be installed.

Once we have a section, we create the setting itself and (optionally) set a default value. In this case we’re going to set dlk_featured_gallery with the first record in the $choices array that we created from the get_terms() values.

Finally, we create the control that allows the user to choose a value for the setting. The add_control() method accepts the setting name and an array detailing the control field, including the section in which it appears. We’re creating a select control passing it the $choices array that contains the gallery names and IDs as key/value pairs.

We now have a simple drop-down menu under its own section in the Customizer… Front Page customization menu

And by getting the gallery ID, as well as the name, using get_terms(), we can present the user with the display name for the gallery, while saving the more reliable numeric ID as the value which we use to determine which gallery should be shown.

The Front Page

Now that we have the selected gallery ID stored in the database, setting up the front page to display it is pretty straightforward. We’re going to create a new WP_Query object to overwrite the default query using our stored gallery ID and then load the template for displaying the gallery taxonomy…

<?php
/* home.php */

$args = array(
  'tax_query' => array(
    array(
      'taxonomy' => 'gallery',
      'field'    => 'term_id',
      'terms'    =>  get_theme_mod('dlk_featured_gallery'),
    ),
  ),
  'posts_per_page' => 1,
);

$wp_query = new WP_Query( $args );

get_template_part('taxonomy-gallery');

get_theme_mod() is the WordPress function that we use to retreive our saved setting from the database. This will allow our new query to find all of the items with the gallery taxonomy that matched our saved ID.

The 'posts_per_page' => 1 argument is required by the custom gallery template, which shows one item at a time and uses Ajax and WordPress’s built-in pagination to navigate through the gallery on a single page. Another write-up on Ajax pagination is probably called for, but is beyond the scope of this article.

What’s Next?

While this works very well and should be easy enough for most users to understand, it’s pretty limited in what it can do. Ideally, it should integrate the default WordPress options for the front page, allowing the user to choose a static page or a post feed, beyond that, allowing a specific post type or even multiple queries to format the front page. All of that is easily possible using the Customizer.

← Code