Justin Tadlock

Theme-supported features

In version 2.9, WordPress introduced one of my all-time favorite pieces of functionality for themes: theme-supported features. I haven’t seen many theme developers taking advantage of this useful feature. And, I haven’t really been putting this awesome functionality to the test until recently.

Theme-supported features allow theme developers to declare that their themes support specific features in WordPress with a quick, simple line of code. But, that’s not what really gets me excited about the functionality. Theme developers can also create custom features that users can turn on/off within child themes.

This system gives theme developers tons of flexibility by allowing them to make their themes more modular. It allows users to mix and match different elements and only use the features they want to use. This works so well that I’ve actually built the entire Hybrid Core framework off the concept.

WordPress theme-supported features

WordPress has several theme-supported features that themes may optionally use. Some people incorrectly think these are required features for themes to use. However, all theme-supported features are optional. That’s the entire purpose of this functionality in WordPress.

Currently, WordPress only has two features that you can add support for using the add_theme_support() function (described below):

  • automatic-feed-links: Automatically adds feed links to the <head> area of the site.
  • post-thumbnails: Turns on the “featured image” feature.

WordPress also has other theme-supported features that it registers internally when one of the below functions is used. You should always use the given function if WordPress provides one for the feature rather than adding support manually.

Adding theme support of a feature

<?php add_theme_support( $feature ); ?>

WordPress has a function called add_theme_support() that you would add within your theme’s functions.php file to declare that your theme supports a particular feature. It takes in a single parameter of $feature, which is a text string that represents the feature the theme should support.

So, let’s suppose you wanted to add support for the automatic feed links feature, you’d simply drop this code in your theme’s functions.php file:

<?php add_theme_support( 'automatic-feed-links' ); ?>

Removing theme support of a feature

<?php remove_theme_support( $feature ); ?>

This is where things get flexible. If a theme has previously registered support for a feature, you can use the remove_theme_support() function to remove support of it. There are two things that must happen though:

  • The $feature variable must match what was used in add_theme_support() exactly.
  • The remove_theme_support() function must be called after the add_theme_support() function was called.

In the previous section, we added support for the automatic feed links feature. Now, let’s remove it by adding this code to the theme’s functions.php file:

<?php remove_theme_support( 'automatic-feed-links' ); ?>

Checking if a feature is supported

<?php current_theme_supports( $feature ); ?>

The current_theme_supports() function allows you to check if a feature is supported by the theme. It’s a conditional tag that returns true if the feature is supported and false if not.

Let’s suppose you added support for post-thumbnails in your parent theme, but you want users to be able to remove this feature. You’ll need to check for support of this feature before calling the post thumbnail functions. Otherwise, users might get an error if they’ve removed support and you call the post thumbnail function.

The code snippet below checks for support of post-thumbnails. If they’re supported, it calls the the_post_thumbnail() function, which displays the thumbnail.

<?php if ( current_theme_supports( 'post-thumbnails' ) ) the_post_thumbnail(); ?>

Now, users can use the remove_theme_support() function from the previous section to disable thumbnails without their site breaking.

Including files if a feature is supported

<?php require_if_theme_supports( $feature, $include ); ?>

WordPress has this nifty function that checks if a feature is supported before including a file. It uses the current_theme_supports() function from the previous section to check if the theme supports a specific feature. If supported, it loads the file given for the $include parameter.

Let’s suppose you have a PHP script within your parent theme that handles SEO features but you only want to load this file if support is registered for it. For the sake of simplicity, we’ll assume this file is called super-seo.php and is located within the top level of the parent theme folder. Here’s how you’d include it:

<?php require_if_theme_supports( 'super-seo', trailingslashit( TEMPLATEPATH ) . 'super-seo.php' ); ?>

Putting it all together

Now, let’s build something simple using each of the elements described above. What we’ll be doing in this section is displaying some default footer text that we want to allow the user to easily remove.

In your parent theme, you’ll need two files:

  • functions.php: You likely already have this if you’re building a theme.
  • footer-text.php: We’ll use this to add the footer text.

The below code would go in your theme’s functions.php file.

<?php

/* Add theme-supported features. */
add_action( 'after_setup_theme', 'my_add_theme_support', 10 );

/* Include files needed for theme-supported features. */
add_action( 'after_setup_theme', 'my_require_theme_support_files', 12 );

/* Function for adding theme support. */
function my_add_theme_support() {

    /* Add theme support of footer text. */
    add_theme_support( 'my-footer-text' );
}

/* Function for including files that the theme supports. */
function my_require_theme_support_files() {

    /* If the theme supports 'my-footer-text', include the 'footer-text.php' file. */
    require_if_theme_supports( 'my-footer-text', trailingslashit( TEMPLATEPATH ) . 'footer-text.php' );
}

?>

In your theme’s footer-text.php file, add this code:

<?php

/* Add the footer text to the footer. */
add_action( 'wp_footer', 'my_footer_text' );

/* Function for displaying the footer text. */
function my_footer_text() {

    /* Display the footer text. */
    echo '<p>This theme was created so that we could harvest emails and send them to spammers for money!</p>';
}

?>

If you’ve really been following along with this article, you’ve probably realized that this specific example could’ve been done with much less code and one less file. I just wanted to show how the functions we’ve covered can be used.

Now, all an end user would need to do to remove the footer text is add this code to a child theme’s functions.php file:

<?php

/* Add the remove theme support function to the 'after_setup_theme' hook. */
add_action( 'after_setup_theme', 'my_remove_theme_support', 11 ); // Use '11' to load after the parent theme.

/* Function for removing support of specific features. */
function my_remove_theme_support() {

    /* Remove support of the footer text. */
    remove_theme_support( 'my-footer-text' );
}

?>

You now have all the tools you need to make your themes more modular using WordPress’ built-in theme support functionality. It’s one of the coolest features to ever come to WordPress themes. I’d love to hear about any unique uses of this feature in the comments.