WordPress: Adding Fields to the Theme Customization Panel

Posted in Tutorials

In previous tutorial, we showed you how to use the theme customization panel to customize the Twenty Fourteen theme in terms of changing the layout of featured posts.  In this tutorial, we will get a bit more advance and show you how to add a new field to this customization panel.   This will provide you with coding experience as to how the customization panel and theme are connected.

This is how the Twenty Fourteen customization panel looks like when you go to “Appearance -> Customize” …

In this tutorial, we will alter this customization panel to add a new field called “Second Tagline” like this …

First we cloned the default “Twenty Fourteen” theme to “Twenty Fourteen Custom” (see how) so that we don’t loose our customization if we ever update the Twenty Fourteen theme.

Adding Hooks to Functions.php

Then we edit the functions.php file of the “Twenty Fourteen Custom” theme.   You can edit this by going to “Appearance -> Editor” and then selecting “Theme Functions (functions.php)”.  Or FTP the file changes to the server.

At the bottom of functions.php, we add the following …

We called the customize_register hook to invoke our to-be-defined function “add_second_tagline” …

add_action('customize_register', 'add_second_tagline');

The wordpress codex writes that …

“This hook gives you access to the $wp_customize object, which is an instance of the WP_Customize_Manager class. It is this class object that controls the Theme Customizer screen.”

So we use the $wp_customize object as follow when we define our function “add_second_tagline” at the bottom of our functions.php file …

function add_second_tagline($wp_customize) {

 $wp_customize->add_setting( 'second_tagline', array(
 'default' => '',

 'capability' => 'edit_theme_options'

) ); }

Here we called the add_setting method of $wp_customize object which you can read more about in the codex.  This gives us a setting variable to store our second tagline.  We let the default value of this variable be an empty string.  We make sure only people with the “edit_theme_options” capability can use this setting.

Next inside our add_second_tagline function, we have to call add_control (see codex) to add a textbox control to our panel…

function add_second_tagline($wp_customize) {

 $wp_customize->add_setting( 'second_tagline', array(
 'default' => '',
 'capability' => 'edit_theme_options'
 ) );

 $wp_customize->add_control( 'second_tagline', array(
 'label' => 'Second Tagline',
 'section' => 'title_tagline',
 'type' => 'text'
 ) );
}

Make the first parameter match the first parameter of add_setting.   For the second parameter, feed it an array containing values for ‘label’, ‘section’, and ‘type’.

For “label”, the label for our control is “Second Tagline”.

For “section”, we want this control placed in the section identified by “title_tagline”.   How did we know that “title_tagline” is the value for this customization panel?   We browsed the code for the WP_Customize_Manager class (search “function register_controls” in wp-includes folder.

For the “type”, we put value of “text” for textbox.  See other type values available here.  For adding more complicated controls, see Otto on WordPress tutorial.

At this point, you customization panel should be able to save new values for “Second Tagline”.  Try it out to make sure you can set new value …

 Accessing Custom Fields

Now we need to access this new field in our template.  The wordpress function to do this is get_theme_mod().

Just add a call to this function in our sidebar.php file like so …

Now whatever we have set for second tagline will show up on the sidebar …

 

 

 

---