Featured Content

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.

Themes without front-page.php

If front-page.php is not included in the theme, the Featured Content area should be added to the following templates if present:

• page.php
• home.php
• index.php
• All custom page templates.