I’ve been working on a new project called the Customizer Library. It’s a collection of classes and functions that make it a bit easier to develop for the WordPress Customizer. It also includes helper functions for Google fonts and inline styles- though I’m considering moving these off into their own repositories as they might not be needed for all projects.

I’ve created a GitHub repository for the Customizer Library that can be included in a theme/plugin as a submodule. I also created a demo theme with example code so developers can get a quick idea of how it works and what it does. I’ve tried to document as much as possible on GitHub- so view the readmes there for implementation details.

I think the reason the Options Framework has been so successful is because it reduced a really complex task (developing an options page) to a really simple task (defining an array). It abstracted the complexity of adding an admin page, generating field markup, sanitizing the data, and saving the options.

The WordPress Customizer is simple in comparison. There’s just one spot to load the controls and WordPress handles the generation of field markup for the most part. But it still doesn’t provide a default data sanitization and the syntax is more complex than it needs to be.

If all essential information can be defined in a simple array and then passed to the Customizer, why aren’t we doing that? Can’t we assume data sanitization for certain fields (color, upload, checkbox), but easily allow custom sanitization for when it’s needed? The Customizer Library solves this.

Let’s look at how a logo section and option would be added without the Customizer Library:

function prefix_theme_customizer( $wp_customize ) {

	// Section
    $wp_customize->add_section( 'logo_section' , array(
	    'title'       => __( 'Logo', 'textdomain' ),
	    'priority'    => 30,
	    'description' => __( 'Upload a logo', 'textdomain' ),
	) );
	
	// Logo
	$wp_customize->add_setting( 'logo' );
	
	$wp_customize->add_control( new WP_Customize_Image_Control( $wp_customize, 'logo', array(
	    'label'    => __( 'Logo', 'textdomain' ),
	    'section'  => 'logo_section',
	    'settings' => 'logo',
	) ) );
	
}
add_action('customize_register', 'prefix_theme_customizer');

It’s not too bad, but there’s a couple ways this could be improved. Why should a setting need to be defined before the control is added? Let’s just add the control and define the setting there.

Also, adding an image control requires different syntax than adding a simple checkbox control.

$wp_customize->add_setting( 'checkbox' );

$wp_customize->add_control( 'checkbox',
    array(
        'type' => 'checkbox',
        'label'    => __( 'Checkbox', 'textdomain' ),
        'section'  => 'example_section',
    )
);

Shouldn’t the syntax be normalized? Could we simplify this further?

If you look at the two examples above (logo section, logo control, checkbox control) the relevant information can be condensed into this:

// Logo
$section = 'logo';

// Define New Section
$sections[] = array(
	'id' => $section,
	'title' => __( 'Logo', 'textdomain' ),
	'priority' => '30'
);

// Define Control
$options['logo'] = array(
	'id' => 'logo',
	'label'   => __( 'Logo', 'textdomain' ),
	'section' => $section,
	'type'    => 'upload',
	'default' => '',
);

// Pre-Existing Section
$section = 'example-section';

// Add Control
$options['example-checkbox'] = array(
	'id' => 'example-checkbox',
	'label'   => __( 'Example Checkbox', 'demo' ),
	'section' => $section,
	'type'    => 'checkbox',
	'default' => 0,
);

Once the array is defined, it is sent to the Customizer_Library, which handles everything else.

// Adds the sections to the $options array
$options['sections'] = $sections;

$customizer_library = Customizer_Library::Instance();
$customizer_library->add_options( $options );

What happens under the hood is actually not that complex. It’s just a simple switch statement that loads the array into the Customizer using core WordPress functions.

The Customizer Library is a work in progress. I’ve just recently extracted the code from my most recent theme and it needs some more thought on how to work best as a stand-alone project.

Should everything be wrapped in classes? Should the font/styles code be included? How should additional custom controls be added and/or extended? The name isn’t even settled. I’ve been thinking of “Customizer Kit” or “Customizer Extends”. Feedback is welcome! Please try it out and let me know what you think.

I haven’t touched on the styles or google fonts functions yet (which is code developed by The Theme Foundry), but you can see how it works in the demo code and I’ll be writing post about that next.

Check out the Customizer Library on GitHub.

Download an example theme showing how the Customizer Library can be used in practice.