Putting Posts on a Pedestal with Jetpack’s Featured Content

Automattic quietly introduced a new Jetpack feature in 2.2. Online documentation is still in process, and it’s not even listed in the changelog; but it’s something all theme developers can take advantage of right now. It’s called Featured Content (FC), and you want to start using it with your themes.

WordPress.com users may already be familiar with Featured Content; it allows users to mark content with a tag of their choice, and have that material presented in a unique way (determined by the supporting theme’s design). Its settings are located at Settings > Reading (the same location is used for WordPress.com and standalone Jetpack installs).

To see it in action, check out a recent Automattic theme, like Superhero (Featured Content is used for the full-width slider).

Let’s take a closer look.

Preparation

1. Make sure you have the latest version of Jetpack installed (2.2.2 at the time of writing).
2. Go to Settings > Reading, and set a tag under Tag Name in Featured Content.
3. Go tag some content!

Since Featured Content is part of Jetpack, your settings here will persist between theme changes. If your theme supports it, you’re good to go, and if not, your settings and content are untouched until you choose a supporting theme.

Adding Support

Adding support for Featured Content is simple:

/**
 * Add support for Jetpack's Featured Content
 */
 add_theme_support( 'featured-content', array(
     'featured_content_filter' => 'themeslug_featured_content',
     'max_posts' => 10,
 ) );

Make sure it’s part of your theme’s setup function in functions.php, hooked to after_setup_theme. The first argument is required, while ‘max_posts’ is optional (it will default to 15 maximum posts).

What’s that filter business, you say? This is how FC is going to get its posts into our theme. The value you give will be the filter name for an add_filter call in FC, which will receive the results (an array) of FC’s own get_posts call. Just think of it more as the source for our FC posts, as opposed to a traditional filter.

Our Theme Function

Let’s create a function that will return our theme’s filter with our FC posts:

/**
* Get our Featured Content posts
*/
function themeslug_get_featured_content() {
    return apply_filters( 'themeslug_featured_content', array() );
}

Our second argument, the empty array, will only be returned if FC has no posts to give us (this way, our function should always return an array). Being a theme function, it will go in our functions.php file.

We’ve added support, and have a way of getting our FC posts – let’s do this!

Slider

A typical use-case for FC is a slider. We can create a template part to hold our HTML and a loop for our Featured Content.

Since our themeslug_get_featured_content function will return an array, we’ll use foreach to loop through our results. This can be saved as slider.php, and called in another template file with get_template_part.

<?php
// Get our Featured Content posts
$slider = themeslug_get_featured_content();

// If we have no posts, our work is done here
if ( empty( $slider ) )
	return;

// Let's loop through our posts ?>
<div class="slider">
	<?php foreach ( $slider as $post ) : setup_postdata( $post ); ?>
		<div class="slide">
			<?php the_post_thumbnail(); ?>
			<h1><?php the_title(); ?></h1>
 			<?php the_excerpt(); ?>
 		</div><!-- .slide -->
	<?php endforeach; ?>
</div><!-- .slider -->
<?php wp_reset_postdata(); ?>

And with some styling, voilà – your Featured Content posts!

Let’s also create a function to serve as a conditional check for two or more FC posts:

/**
 * Conditional function for checking if we have at least two Featured Content posts
 */
function themeslug_has_featured_posts() {
	$featured_posts = apply_filters( 'themeslug_get_featured_posts', array() );
	if ( is_array( $featured_posts ) && 1 < count( $featured_posts ) )
		return true;

	return false;
}

Now we can conditionally enqueue any scripts our slider might need. We check for two or more posts, as only one post wouldn’t require our fancy slider animations.

if ( is_home() && themeslug_has_featured_posts() )
    wp_enqueue_script( 'themeslug-slider-script', get_template_directory_uri() . '/js/awesome-slider.js', array( 'jquery' ) );

Wrapping Up

Featured Content is a simple way for users to tag and highlight certain posts, while providing theme developers with a simple method of getting those posts into their theme.

It will be interesting to see how Featured Content develops; while exciting, it still has plenty of room to grow. It would be great to be able to filter or modify the get_posts call that FC makes, allowing for more creative applications (including custom post types or sorting by meta key come to mind). Also, both user-centric and developer-grade documentation online will only help adoption (in the meantime, the inline commenting is comprehensive).

To see the above slider example in a less trivial, more realistic context, check out Superhero (look at the slider.php template file, as well as inc/jetpack.compat.php), or my starter theme Debut, on GitHub.

What do you think of Featured Content, and how do you see yourself using it in your themes?