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 feature 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 Appearance → Customize, 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

Featured Content options as shown with Twenty Fourteen.

If your theme supports Featured Content, you can activate the Featured Content area by navigating to Appearance → Customize and entering the name of a tag into the “Tag name” field in the “Featured Content” section. If you enter the name of a tag that does not exist already a new tag will be created for you. Once this value has been set, published posts tagged with this value will be included in the Featured Content Area.

You can control the amount of featured posts by the amount of posts you tag with the above set featured content tag. By default, Featured Content will return a maximum of 15 posts; however, the theme itself may define its own maximum number of posts. This may be necessary if the theme uses large featured images in its Featured Content presentation, for example.

“Hide tag from displaying in post meta and tag clouds” can be checked to ensure that the tag selected for Featured Content doesn’t show up in that post’s list of tags or the Tag Cloud widget. Your tag’s archive will continue to be displayed in normal fashion.

The “Display tag content in all listings” option can be checked to ensure that the Featured Content tag will display in all pages and archives.

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(
	'filter'     => 'mytheme_get_featured_posts',
	'max_posts'  => 20,
	'post_types' => array( 'post', 'page' ),
) );

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

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.
post_types – By default, the Featured Content feature will pull posts only. However, you can add Featured Content support for registered post types by defining an 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' ); ?>
    </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' ) );
}

How can I add a “fallback” image?

If no Featured Image is set for a post, Jetpack will look for slideshows, galleries, or single images you may have attached to or inserted into the post.

However, if no image is associated with a post, no Featured Image will appear. If you want a “fallback” image to display in these instances, you can add this code snippet to your theme’s functions.php file:

function jeherve_custom_image( $media, $post_id, $args ) {
	if ( $media ) {
		return $media;
	} else {
		$permalink = get_permalink( $post_id );
		$url = apply_filters( 'jetpack_photon_url', 'YOUR_LOGO_IMG_URL' );

		return array( array(
			'type'	=> 'image',
			'from'	=> 'custom_fallback',
			'src'	=> esc_url( $url ),
			'href'	=> $permalink,
		) );
	}
}
add_filter( 'jetpack_images_get_images', 'jeherve_custom_image', 10, 3 );

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.