The WordPress Theme Customizer: Adding a New Setting To An Existing Section

Since the release of the WordPress Theme Customizer, my team and I have been more and more interested in using it as a way for users to make changes to the appearance of their theme without the use of the dashboard.

As powerful as the dashboard is, the “Appearance” section creates a disconnect between what the user toggles (or selects, or inputs, etc), and what they see on the front end.

The Theme Customizer mitigates that issue.

The thing is, there are a few nuances that come with implementing it in your theme. Though I’m not trying to cover everything here, the point of this post is show how you can introduce a new setting into an existing section.

The WordPress Theme Customizer: New Setting, Old Section

For those of you who aren’t familiar, the WordPress Theme Customizer is an API that was released in WordPress 3.4. Several of the more recent themes that ship with WordPress include it:

WordPress Theme Customizer

In short, it’s a way for you to make changes to the appearance of your theme on the fly. On top of that, it’s completely customizable such that whenever you introduce a new setting into your existing theme, you can add new sections, settings, and so on to the theme customizer.

But that’s another post.

Adding a New Setting To An Existing Section

Here, I’m more concerned with documentation how to add a new setting to an existing section as well as sharing how I organize my files for working with the theme customizer.

It’s not so much that I think my way is right anymore than someone else’s way, but I do prefer to keep my files as compartmentalized as possible so this should share that, and it should show how to introduce a new setting into an existing section.

The File Structure

As I mentioned, there are a number of ways that you implement the WordPress Theme Customizer, but there has been my preferred method for some time now:

  • Create an inc directory in the root of the theme
  • Create a theme-customizer.php file in the inc directory
  • Call an include_once to the theme-customizer.php file in functions.php
  • Create a js directory in the root of the theme
  • Create a theme-customizer.js file in the js directory

This should be clear enough.

WordPress Theme Customizer File Organization

Though I use CodeKit to manage my JavaScript, CSS, images, and other assets, this should provide you with enough information for how I organize my theme files.

Implementing The New Setting

So anyway, once you’ve done all of that, it’s really easy to begin implementing the theme customizer.

First, you need to register your JavaScript file with the customize_preview_init action:

function my_customizer_live_preview() {

	wp_enqueue_script(
		  'my-theme-customizer',
		  get_template_directory_uri() . '/js/theme-customizer.min.js',
		  array( 'jquery','customize-preview' ),
		  MY_THEME_VERSION,
		  true
	);

}
add_action( 'customize_preview_init', 'my_customizer_live_preview' );

Then you need to define a function that will be added to the theme’s theme customizer by using the customize_register function.

In this case, I’m looking to introduce a new option specifically for changing the link color and I am looking to add it to the existing Colors section in the theme customizer.

function my_theme_register_theme_customizer( $wp_customize ) {

	$wp_customize->add_setting( 'link_color',
		array(
			'default'     => '#000000',
			'transport'   => 'postMessage',
		)
	);

	$wp_customize->add_control(
		new WP_Customize_Color_Control(
			$wp_customize,
			'link_color',
			array(
				'label'        => __( 'Link Color', 'my_theme' ),
				'section'    => 'colors',
				'settings'   => 'link_color'
			)
		)
	);

	$wp_customize->get_setting( 'link_color' )->transport       = 'postMessage';

}
add_action( 'customize_register', 'my_theme_register_theme_customizer' );

Above, the key is that the add_setting must come before the add_control call.

At this point, this should introduce a new setting in your theme customizer, though it won’t actually be functional since there isn’t any JavaScript, yet.

WordPress Theme Customizer Link Color
Can’t show too much of this theme yet. :)

Next, you need to implement the necessary JavaScript in the theme-customizer.js file that was discussed earlier in the post.

To do this, you need to understand two things:

  • Implementing the WordPress Theme Customizer exposes a JavaScript object that offers a function that allows you to specify the setting that you’re going to modify.
  • You need to know the selector for which you’re going to modify. To keep it simple, I’m modifying all anchor elements.
(function( $ ){
	"use strict";

	// The Background Color of the Header
	wp.customizer( 'link_color', function ( value ) {
		value.bind( function( newVal ) ) {
			$( 'a' ).css( 'color', newVal );
		});
	});

}( jQuery ));

Finally, assuming that you’ve got it all wired up in functions.php, the implementation should be good to go within the theme customizer. Again, this is specifically for adding a new setting to an existing section.

Working with custom options isn’t bad, but it’s a whole other post.

8 Replies to “The WordPress Theme Customizer: Adding a New Setting To An Existing Section”

    1. Different people may have different takes on this, but this is how I’ve always implemented it in my work:

      • `lib` is normally for third-party assets and tools that are not written by the developer or the development team
      • `inc` is for assets that are developed in-house or by the main developer, but not meant to clutter up the core `functions.php` or whatever file(s)

      That’s how I’ve always used it. Perhaps I’ll do a longer blog post on this soon.

  1. ah..finally, i’ve been looking for a tutorials on this. thx tom
    btw is it possible to allow customize panel for none loggedin user? maybe exclude the save/publish button.

    1. If the feature is implemented correctly in the customizer, then you’ll use the ID that you specified – say `acme_color` – and then retrieve it by calling `get_theme_mod( ‘acme_color’ );`.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.