Getting Started With The WordPress Theme Customizer

The WordPress Theme Customizer was introduced in version 3.4 of WordPress, it provides the ability for a site owner to change colours, images, fonts and almost whatever you can think of, on the fly, so they can see if the change looks good. If the change they have made looks good in the live preview then they can save their changes and those settings will be put live. It’s a great addition to WordPress and one I have been using a lot.

Developing for the Theme Customizer

The Theme Customizer is really nice to work with, once you have your head around the basic principles of what it does and what benefit it gives the user. Take a look at a code snippet, this will give you a basic set of options you can use to get started. Further down I will go through the code and see exactly what it is we are doing.

Theme Customizer Options Code Snippet

This code snippet will add all you need to get the options showing inside Appearance > Customize. It won’t do anything until you add the front end code, but once you do you will realise just how powerful this really is.

/**
* Theme Customiser Options (goes into functions.php)
**/
add_action( 'customize_register', 'ew_register_theme_customizer' );
function ew_register_theme_customizer( $wp_customize ) {

	$wp_customize->add_section( 'ew_font_section' , array(	'title' => __( 'Fonts', 'epicwebs' ), 'priority' => 20 ) );
	$wp_customize->add_section( 'ew_style_section' , array(	'title' => __( 'Styling', 'epicwebs' ), 'priority' => 120 ) );
	
	// Background Color
    $wp_customize->add_setting( 'ew_background_color', array( 'default' => '#ffffff' ) );
    $wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'background_color', array( 'label' => __( 'Background Color', 'epicwebs' ), 'section'    => 'colors', 'settings'   => 'ew_background_color' ) ) );

	// Body Font
    $wp_customize->add_setting( 'ew_main_body_font', array( 'default' => 'Arial' ) );	
	$wp_customize->add_control( 'ew_main_body_font', array( 'section'  => 'ew_font_section', 'label' => __('Main Font', 'epicwebs'), 'type' => 'select', 'choices'  => array("Arial","Verdana"), 'priority' => 3 ) );
	
	// Border Radius
    $wp_customize->add_setting( 'ew_border_radius', array( 'default' => 'None' ) );	
	$wp_customize->add_control( 'ew_border_radius', array( 'section'  => 'ew_style_section', 'label' => __('Smooth Corners', 'epicwebs'), 'type' => 'select', 'choices'  => array("0" => "None","5" => "Slightly Rounded","10" => "Rounded", "20" => "Very Rounded"), 'priority' => 6 ) );
	
}

First of all we set our action which is customize_register, we give it a function ew_register_theme_customizer. Make sure you pass $wp_customize to the function so that we can actually add sections and settings to it. After we have our function, we need to add any sections that we want, these are sections for different settings to sit in, this becomes clear when you insert the code and go to Appearance > Customize.

In the example above I have added two sections, one for font and one for style. We call the add_section method and give it a name, a title and a priority. The higher the number on the priority the further down it shows on the customize admin page.

$wp_customize->add_section( 'ew_style_section' , array(	'title' => __( 'Styling', 'epicwebs' ), 'priority' => 120 ) );

Adding a setting is very easy using the customizer, you simple call the add_setting method and set the parameters to a name, and an array for extra parameters like a default. You don’t need to worry about the section until you add a control.

$wp_customize->add_setting( 'ew_border_radius', array( 'default' => 'None' ) );

Next we add a control so that we can actually change that setting. For the border radius we use a select control which is determined by the type. The add_control method takes a name than an array of arguments. We set the section to whatever section we added earlier, in this case ew_style_section. Then we give it a Label, type and some choices for the select. The final thing to add is a priority which determines how high up the control appears inside it’s own section.

$wp_customize->add_control( 'ew_border_radius', array( 'section'  => 'ew_style_section', 'label' => __('Smooth Corners', 'epicwebs'), 'type' => 'select', 'choices'  => array("0" => "None","5" => "Slightly Rounded","10" => "Rounded", "20" => "Very Rounded"), 'priority' => 6 ) );

Theme Customizer Front End Code Snippet

This is the code which will make your options do something when you actually select them. This is a stripped down version of a theme I am developing, but it’s a great started.

/**
* Theme Customiser Front End CSS
**/
add_action( 'wp_footer', 'ew_customizer_css', 100 );
function ew_customizer_css() {	
	echo "<style type='text/css'>";
	
	$background_color = get_theme_mod( 'ew_background_color', '#767d87' );
	if(!empty($background_color)) {		
		echo "body { background: {$background_color}; }" . PHP_EOL;
	}
	
	$main_font = get_theme_mod( 'ew_main_body_font', 'Arial' );
	if(!empty($main_font)) {		
		echo "body { font-family: '{$main_font}', sans-serif; }" . PHP_EOL;
	}
	
	$border_radius = get_theme_mod( 'ew_border_radius', '0' );
	if(!empty($border_radius)) {
		echo ".border-radius { border-radius: {$border_radius}px; -webkit-border-radius: {$border_radius}px; }" . PHP_EOL;
	}
	
	echo "</style>";
}

This code is relatively simple, if you have ever created your own options page in the past then you will see exactly what this does. We grab the settings by using get_theme_mod, which takes the name of setting and then a default, in case it returns nothing, which is optional.

We then just echo out the CSS using the settings we have grabbed and apply it to any elements that we wish to apply it to.

I have a fairly large list of settings which I have been working on, but if there is any you would like to see then please leave a comment below and I might already have them or be able to create them to share with you.

Comments