Featured Content

Featured Content allows users to spotlight their posts and have them uniquely displayed by a theme. The content is intended to be displayed on a blog's front page; by using the module consistently in this manner, users are given a reliable Featured Content experience on which they can rely even when switching themes.

To get started you can follow these easy steps:

Enable theme support for Featured Content
Go to Settings → Reading, and set a tag under Tag Name in Featured Content
Tag some content.

For more detailed information, read on! Or jump directly to usage tips, steps for adding support to your theme, and template tips.

Usage

Adding Support to a Theme

The first step in adding Featured Content support to your theme is to call add_theme_support() passing 'featured-content' as the first parameter. This call to add_theme_support() should happen during the after_setup_theme action.

add_theme_support( 'featured-content', array(
	'featured_content_filter' => 'mytheme_get_featured_posts',
	'max_posts'   => 20,
	'additional_post_types' => 'page',
) );

The second parameter, $args, is an array that may contain 3 separate values. The first is required and the 2 others are optional:

featured_content_filter – The name of a custom filter that is used to return featured content. This should be prefixed with the theme slug.
max_posts – The maximum number of posts that may be contained in the area. It's possible that a theme might only be able to fit six posts into the area. In cases like this, max_posts should be set to six.
additional_post_types – By default, the Featured Content module will pull posts only. However, you can add Featured Content support for additional registered post types by defining an additional_post_types argument (in the form of a string or an array).

Getter Function

A function should be created that returns the value of the filter defined in add_theme_support( 'featured-content' ). This will be used to assign featured posts to a variable in a template file.

function mytheme_get_featured_posts() {
	return apply_filters( 'mytheme_get_featured_posts', array() );
}

Conditional Function

To avoid markup being printed and scripts being enqueued when they are not needed, we can define a function to help us make these decisions. This function should return a Boolean value and accept a single parameter. The parameter is used to declare the minimum number of featured posts required to return a true value.

function mytheme_has_featured_posts( $minimum = 1 ) {
	if ( is_paged() )
		return false;

	$minimum = absint( $minimum );
	$featured_posts = apply_filters( 'mytheme_get_featured_posts', array() );

	if ( ! is_array( $featured_posts ) )
		return false;

	if ( $minimum > count( $featured_posts ) )
		return false;

	return true;
}

For example, in the case of a slider, we can use mytheme_has_featured_posts() in different ways for adding markup and enqueuing scripts. As our slider only shows one post at a time, we may have markup we need to output as long as there is one featured post, but we'll only need to enqueue our slider Javascript if there are two or more posts.

// Found in our template file
<?php if ( mytheme_has_featured_posts( 1 ) ) : ?>
	<div class="featured-content">
		<?php get_template_part( 'content-featured.php' ); ?>
	</div>
<?php endif; ?>

// In functions.php, in a function hooked to wp_enqueue_scripts
if ( mytheme_has_featured_posts( 2 ) ) {
	wp_enqueue_script( 'mytheme-slider-script', get_template_directory_uri() . '/js/awesome-slider.js', array( 'jquery' ) );
}

Templates

To standardize the user experience across themes, we have developed the concept of a front page featured content area. This area will always display on the "front page" of a WordPress installation – in other words, this area will always be rendered when is_front_page() returns true. Depending on the theme's design and the site's settings, is_front_page() may return true in multiple different templates. The Featured Content area should be rendered in the following templates if present in a theme:

Themes that include front-page.php

The front-page.php template will always be used to render the frontpage if it exists in a theme. If your theme provides this template, it is the only one to which the featured content area needs to be added.