PIA17171

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?

6 thoughts on “Putting Posts on a Pedestal with Jetpack’s Featured Content

  1. Thanks for sharing this. It’s a great tutorial.

    I’m tempted to use it but a little unsure of how it’s actually better than the alternative. I’m curious as to the major advantages you see for this as compared to just setting up a taxonomy term-driven system independent of Jetpack where one at least has full control over the query.

    1. For those using Jetpack, it’s great to be able to have your posts tagged and identified as you know how (in Settings > Reading), and to have those posts treated appropriately when switching between themes. It’s simply a way of giving a more consistent user experience between themes, and not recreating the wheel every time.

      As the feature improves, I’m sure we’ll start to see more filters for better control over the query (that would be one of my top requests at this point).

      1. Thanks for the response! Having just played around with it a bit now, I agree with your assessment. I’d also add that’s it’s really nice that this Featured Content setup takes care of excluding the category from displaying on the front end (if you want it to).

  2. I would suggest anyone who is interested in improving the featured content experience in WordPress to head on over http://make.wordpress.org/core/features-as-plugins/
    and check the Featured Content team as they are working on loosely using the jetpack plugin as a base for a much better Core Plugin. Which over time will be added directly into the Core of WordPress. Developer contributions is needed.
    If you would like to take part in the IRC chats I suggest using my embeded IRC chat: http://easywebdesigntutorials.com/wordpress-developer-irc/

  3. Anyone having any problems getting this to work, note that there appears to have been a bit of cutting and pasting going on which has mixed up the name of the filter in the above code, which

    There are a few problems with the code examples above. One, simple, error is mixing up the filter name which is themeslug_get_featured_content but is also referred to as themeslug_get_featured_posts.

    Also, I had issues with the titles and thumbnails being mixed up, as predicted by the codex article for setup_postdata() (http://codex.wordpress.org/Function_Reference/setup_postdata) if you fail to declare global $post before your foreach loop in the template.

    Minor trip-ups to be aware of, but thanks very much for writing the piece, it proved invaluable for me to get Featured Content working.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s