Hooking to the “Featured” areas

The Problem

The Theme Blvd framework provides many action hooks that work just like any other action hook in WordPress. However, if you’ve tried to hook a function specifically to themeblvd_featured or themeblvd_featured_below you’ve probably run into some issues.

For example, if you were to do the following, you will have noticed it simply does not work.

function my_featured(){
	echo "Hello World!";
}
add_action('themeblvd_featured', 'my_featured');

function my_featured_below(){
	echo "Hello World!";
}
add_action('themeblvd_featured_below', 'my_featured_below');

The Reason

So the question is: How come when I hook to “themeblvd_featured” or “themeblvd_featured_below” nothing gets displayed on my site?

When you display something in the featured area, you aren’t just displaying that function, you’re also displaying the actions that get called to structure the markup around the featured area.

For example, the featured area is setup with HTML markup something like this:

<div id="featured">
	<div class="featured-inner">
		<div class="featured-content">
			[Your hooked content here ...]
		</div><!-- .featured-content (end) -->
	</div><!-- .featured-inner (end) -->
</div><!-- #featured (end) -->

And so if this was just a normal action hook, the problem would be that if you have no content in the featured area, every time your site loads, you’d have this markup being outputted:

<div id="featured">
	<div class="featured-inner">
		<div class="featured-content">
		</div><!-- .featured-content (end) -->
	</div><!-- .featured-inner (end) -->
</div><!-- #featured (end) -->

And now, any CSS you’ve applied to these featured area classes, would be displaying a big, blank area at the top across your entire website. This is why the framework has a check for if the featured area is enabled before displaying it. Here’s a peak under the hood at how this works in header.php —

You can see in the screenshot that if the themeblvd_config('featured') returns false, that the featured area will not show. So, how to get this to return true is the key to all of this, and what I’ll cover in the section below.

Well, why not use has_action? — You might be wondering why we don’t just check for an action attached to themeblvd_featured (for example), and then display the HTML markup and content.

If only it were this easy, right? However, different themes attach different things to these featured areas with conditional content. Also, these featured areas have some more complex actions attached to them that make plugins like the Theme Blvd Layout Builder possible. In other words, the featured areas will inevitably already have actions hooked to them, however you still won’t want them to show in most situations. So, using WordPress’s has_action would not work here.

The Solution

Basically, in order to hook to a featured area, you first need to enable the featured area within the framework. Then you can hook to the action and have everything display. Let’s work through this with the following examples.

A basic example across your entire site

In this example, let’s assume you’re hooking your content to the featured area across the top of your entire website.

First, you need to enable the featured area. You do this by filtering “themeblvd_frontend_config” —

This filter is attached to an array of various items that get set every time your site loads. Within this array, there are keys called “featured” and “featured_below” that contain an array of CSS classes to be displayed with the markup of the featured area. By default this array of CSS classes is empty, and thus the featured area does not show. So, to get the featured area to show, you need to filter on at least one CSS class.

The last paragraph was a probably a little confusing. So I’ll just show you how it’s done; it’s more simple than it sounds.

function my_frontend_config( $config ){
	$config['featured'][] = 'my_featured_content'; // This class can be whatever you want
	return $config;
}
add_filter( 'themeblvd_frontend_config', 'my_frontend_config' );

The featured area is now enabled and so you can just hook your content as normal.

function my_featured(){
	echo "Hello World!";
}
add_action('themeblvd_featured', 'my_featured');

And so now you should have the following HTML markup displayed across the top of your entire website.

<div id="featured">
	<div class="featured-inner my_featured_content">
		<div class="featured-content">
			Hello World!
		</div><!-- .featured-content (end) -->
	</div><!-- .featured-inner (end) -->
</div><!-- #featured (end) -->

A more specific example

Most likely you won’t be hooking to the featured area across your entire website. A more practical situation is that you’d be targeting a specific page or scenario on your website. You’d do this by incorporating WordPress conditionals.

So, let’s say you want to hook to the featured area on top of a specific page with ID “123”. You’d do it like this:

// Enable featured area for page "123"
function my_frontend_config( $config ){
	if(is_page(123))
		$config['featured'][] = 'my_featured_content'; // This class can be whatever you want
	return $config;
}
add_filter( 'themeblvd_frontend_config', 'my_frontend_config' );

// Hook content to page "123"
function my_featured(){
	if(is_page(123))
		echo "Hello World!";
}
add_action('themeblvd_featured', 'my_featured');

And now you’ll have an output like this at the top of page 123:

<div id="featured">
	<div class="featured-inner my_featured_content">
		<div class="featured-content">
			Hello World!
		</div><!-- .featured-content (end) -->
	</div><!-- .featured-inner (end) -->
</div><!-- #featured (end) -->

And here, because we’re dealing with a specific featured area we’ve setup, we can utilize the class “my_featured_content” we filtered on to style that specific featured area within our CSS.

#featured .my_featured_content { ... }
#featured .my_featured_content .whatever { ... }

As you start to create more unique featured areas displayed in different scenarios, you’ll see how you may want to utilize these CSS classes to do some cool things.

A complicated example from Swagger

Just for fun and to give you an example of a theme doing something more complex with these hooks, let’s checkout Swagger.

In this theme, the main goal was to display the title of pages and posts up in the featured area above the main content area. We hooked several functions to the featured area with conditional content, and we enabled the featured area conditionally, as well.

Here’s what it all looks like together:

/**
 * Adjust frontend global config to enable featured areas
 */
function swagger_frontend_config( $config ) {
	global $post;
	
	if( is_page() )
		if( 'hide' != get_post_meta( $post->ID, '_tb_title', true ) )
			$config['featured'][] = 'has_page_featured';

	if( is_single() )
		$config['featured'][] = 'has_single_featured';

	if( is_archive() || is_search() )
		if( themeblvd_get_option( 'archive_title' ) != 'false' )
			$config['featured'][] = 'has_archive_featured';

	return $config;
}
add_filter( 'themeblvd_frontend_config', 'swagger_frontend_config' );

/**
 * Featured Titles on posts
 */
function swagger_featured_single() {
	global $post;
	
	// Only for single posts
	if( ! is_single() )
		return;

	// Determine if meta info should show
	$show_meta = true;
	if( themeblvd_get_option( 'single_meta' ) == 'hide' )
		$show_meta = false;
	if( get_post_meta( $post->ID, '_tb_meta', true ) == 'hide' )
		$show_meta = false;
	else if( get_post_meta( $post->ID, '_tb_meta', true ) == 'show' )
		$show_meta = true;
	if( is_attachment() )
		$show_meta = false;
	?>
	<div class="element element-headline featured-entry-title">
		<h1 class="entry-title"><?php the_title(); ?></h1>
		<?php if( $show_meta ) themeblvd_blog_meta();	?>
	</div><!-- .element (end) -->
	<?php
}
add_action( 'themeblvd_featured', 'swagger_featured_single' );

/**
 * Featured Titles on pages
 */
function swagger_featured_page() {
	global $post;
	if( is_page() ) {
		if( 'hide' != get_post_meta( $post->ID, '_tb_title', true ) ) {
			$tagline = get_post_meta( $post->ID, '_tb_tagline', true );
			echo '<div class="element element-headline featured-entry-title">';
			echo '<h1 class="entry-title">'.get_the_title( $post->ID ).'</h1>';
			if( $tagline ) 
				echo '<p class="tagline">'.stripslashes( $tagline ).'</p>';
			echo '</div><!-- .element (end) -->';
		}
	}
}
add_action( 'themeblvd_featured', 'swagger_featured_page' );

/**
 * Featured Titles on archives
 */
function swagger_featured_archive() {
	if( is_archive() ) {
		?>
		<div class="element element-headline featured-entry-title">
			<h1 class="entry-title"><?php themeblvd_archive_title(); ?></h1>
		</div><!-- .element (end) -->
		<?php
	}
}
add_action( 'themeblvd_featured', 'swagger_featured_archive' );