Using the WordPress Theme Customizer to choose between excerpts or full content

The Theme Customizer, introduced in WordPress 3.4, is a powerful tool for theme settings and options. In this tutorial, we’ll give our users a choice of how they would like their posts presented on the blog page: excerpts, or full post content. Our setting will be displayed as radio buttons, with a default value of “excerpt”.

Check out another tutorial of mine to see how we can add a logo uploader to the Theme Customizer.

If you haven’t yet, now would be a good time to at least skim through Otto’s excellent tutorials on the Theme Customizer. He goes over a lot of the details, options and methods necessary for using the Theme Customizer API that will not be covered here. For those going straight to the core source code for answers, you can start with the class-wp-customize-*.php class definitions in wp-includes.

There are three general steps when adding an option to the Theme Customizer: creating a section for our setting, creating the setting itself, and adding a controller for that setting. It’s also possible to add a new setting to an existing, core-defined section; refer to the Codex for details. The following three code blocks will go in our theme’s functions.php file.

First, we’ll add a new section called “Layout”, under which we’ll add our new post content setting.

$wp_customize->add_section( 'themeslug_layout_section' , array(
        'title'       => __( 'Layout', 'themeslug' ),
        'priority'    => 30,
        'description' => 'Change how Debut displays posts',
    ) );

Next, let’s actually create that setting, and assign a default value. Note: when defining the default value, we use the key name when working with radio buttons, not the value of that key (this will be clearer in the code block defining our setting’s control).

$wp_customize->add_setting( 'themeslug_post_content', array(
        'default'   => 'option1',
    ) );

Wrapping things up in functions.php, we define what sort of control we would like to use when interacting with our setting (in our case, radio buttons). Again, refer to Otto’s tutorials for more detail (specifically his custom controls tutorial), or class-wp-customize-control.php in wp-includes.

$wp_customize->add_control( new WP_Customize_Control( $wp_customize, 'themeslug_post_content', array(
        'label'     => __( 'Post content', 'themeslug' ),
        'section'   => 'themeslug_layout_section',
        'settings'  => 'themeslug_post_content',
        'type'      => 'radio',
        'choices'   => array(
            'option1'   => 'Excerpts',
            'option2'   => 'Full content',
            ),
    ) ) );

Lastly, we need to make our theme aware of our new setting, which will go in our loop. Since we only have two options for our setting, I’ll add the following to the content.php template of my own Debut starter theme. In your own theme, this would go in whichever templates have loops. Of course, it’s always an option to create a function in your functions.php to handle the logic, and call that function from your templates; the choice is yours (moving to functions.php is often more desirable if dealing with more than a simple “if” statement).

if ( 'option2' == get_theme_mod( 'themeslug_post_content' ) ) :
    the_content( __( 'Continue reading <span class='meta-nav'>→</span>', 'themeslug' ) );
else :
    the_excerpt();
endif;

That’s it! Now users in our Theme Customizer can see a preview of their blog when choosing between excerpts or full content for their posts. The same methods could be used for other aspects of theme layout; check out the most recent version of Twenty Eleven to see an example of sidebar positioning.

To see the above code in context, you can refer to Debut’s GitHub page.

If you have any questions, please post in the comments. Have fun!