computer 1873831 1920

If you’re designing WordPress themes for a client, or for publication purposes, you might wish to add controls to the customizer panel in WordPress.

This is not particularly difficult to achieve, so even if you don’t have much experience with basic PHP commands and WordPress functions in general, then don’t worry – we’ll guide you!

The structure

First of all, in the past 3-4 official themes I’ve looked at, the customizer script is removed from functions.php and placed in it’s own file named customizer.php and then called from functions.php with a require function. This means that we only need to open customizer.php and work with that single file, and all it contains relates to what we’re working with and not also stuff like sidebar functions or basic theme settings. Easy!

Theme generators, such as underscores.me which we’re very fond of using here at Incredible Planet, often splits up the customizer controls and settings into it’s own file as well.

In this customizer.php script, often times there will be this structure internally:

  • Settings
  • Controls
  • Sanitize functions

WordPress customizer settings API

We need to define a setting for WordPress to store the data, think of this like a database entry. At the other end of this we have controls, which are meant to capture the input and then store it in the setting. Also, we need to sanitize the control inputs, so there are 3 steps to adding a customizable field to the customizer.

So, before we think of creating the control or sanitize the input, let’s define the setting.

$wp_customize->add_setting( 'custom_field' , array(
    'default' => 'Default value',
    'type' => 'theme_mod',
    'sanitize_callback' => 'our_sanitize_function',
) );

This is the bare minimum we need for a simple custom text field in terms of what settings are like.

We won’t go over these in much detail, however suffice to say that in the array portion of the above snippet, it’s possible to add several other parameters.

WordPress customizer control API

Once we have our setting in place, we can now add a control for that particular one. For the above example, this would create a text input field, defined in the array parameter of “type”.

$wp_customize->add_control( 'custom_field', array(
    'label' => __( 'Custom text for custom field', 'placeholderfortextdomain' ),
    'section' => 'title_tagline',
    'settings' => 'custom_field',
    'type' => 'text'
) );

Now that we have this in place, we are ready to sanitize the input so no bad characters or malicious code will get injected by accident or purpose.

WordPress sanitize_callback customizer API

To properly sanitize a simple text field, we will pass our input value through a function which will handle the sanitizing. Personally, I use a snippet I found some time ago, but there are many variations out there.

function our_sanitize_function( $input ) {
    return wp_kses_post( force_balance_tags( $input ) );
}

Great. Now that this is done, we can actually login to our WordPress control panel, go to the theme customizer and save the value!

Displaying the custom fields in the WordPress theme

Well, we managed to save our data from the customize manager in the WordPress theme administration window, but how to display it?

Often times, we wish to have users type in their personalized copyright message in the customizer, and then automatically print that in the theme footer.

It’s a simple process to just display it, but with any PHP code, there are always safety issues to take care of as well.

First of all, let’s revisit the setting parameter called type. Because this is a theme_mod, we can use the following PHP code to display it:

<?php 

    if ( '' == get_theme_mod( 'custom_field' ) ) { $custom_field = 'Default set of data'; } else { $custom_field = get_theme_mod('custom_field'); } 

    echo $custom_field;
?>

The first line can look complicated so let’s break it down.

First of all, we load the if statement, and check if get_theme_mod(‘custom_field’) is empty. If that is the case, then we set a variable called $custom_field to be our default set of data. If get_theme_mod(‘custom_field’) is already set, then we get the data and use that instead as the variable of $custom_field.

The second lines simply echoes out the variable of $custom_field, so this will need to be placed in the correct position in theme files.

This way, when a user loads the customizer for the first time, there can be default data there, ready to go. And by declaring a variable to use instead of get_theme_mod() directly, we circumvent any issues that might occur if the user has not input data to that particular field.

Incredible Planet Staff

We deliver incredible facts from all around the world.
If the information is interesting, and fits into one of our five main categories; Animals, People, Places, Science or Space, we will feature it!

Leave a Reply

Your email address will not be published.