Otto on WordPress

Okay, a quick one today. Let’s make a custom control for the customizer.

Back in the first tutorial, I talked about the various controls available in the customizer. Specifically I mentioned image handling, color wheels, text boxes, radios, dropdowns, and checkboxes.

Let’s try a new one? How about a textarea? It’s not in the core code, but it’s easy enough to add one.

Create a Class

So first, we have to create our class. Now, where we create this class is important. Specifically, we have to create it in the function called by the customize_register action. You remember that, right? It started like this:

add_action( 'customize_register', 'themename_customize_register' );
function themename_customize_register($wp_customize) {
	// ... do stuff ...

The reason we have to create our class in here is because we need to make our new class extend the built in WP_Customize_Control class, and that class only gets loaded and defined when we’re actually using the customizer. An alternate means of doing this would be to wrap the class definition in an “if (class_exists(‘WP_Customize_Control’))” statement, if you prefer to not have your classes defined inside a function. Personal preference, I don’t think it makes a difference either way.

So, here’s our textarea control. All we’re doing is to override the render_content() function and make it display a textarea.

class Example_Customize_Textarea_Control extends WP_Customize_Control {
	public $type = 'textarea';

	public function render_content() {
		?>
		<label>
		<span class="customize-control-title"><?php echo esc_html( $this->label ); ?></span>
		<textarea rows="5" style="width:100%;" <?php $this->link(); ?>><?php echo esc_textarea( $this->value() ); ?></textarea>
		</label>
		<?php
	}
}

You can see how simple it is to do, really. We just output a span with the value from $this->label for the name displayed above the textarea, then output the textarea itself.

Note that the textarea has no “name” parameter. It doesn’t need one. The $this->link() function outputs the information for the customizer script. Specifically, it will create a “data-customizer-setting-link” attribute, to link the textarea to the proper setting it’s controlling.

Now, we just have to use the new control.

Add a setting and control

Let’s go back to the theme demo I used in the second customizer tutorial post, and add a new setting and control to demonstrate this:

$wp_customize->add_setting( 'textarea_setting', array(
	'default'        => 'Some default text for the textarea',
) );

$wp_customize->add_control( new Example_Customize_Textarea_Control( $wp_customize, 'textarea_setting', array(
	'label'   => 'Textarea Setting',
	'section' => 'themedemo_demo_settings',
	'settings'   => 'textarea_setting',
) ) );

Nothing complicated there. We create the setting, then we create our control, using the new class we made for this purpose earlier.

Use the setting in the theme

Now let’s add to that index.php file I made in the theme demo to show the results of our work.

echo 'textarea_setting => '.get_theme_mod( 'textarea_setting', 'default_value' )."\n";

And that’s pretty much that. We now have a textarea control, and changing/saving results in the setting changing as well.

You can extend this further to use postMessage for real-time changing of settings, if you like.

Custom controls using complex javascript and such can be done as well. Examine the core WP_Customize_Color_Control, which uses the farbtastic Javascript for the color wheel. That one has special JS in the customize-controls.dex.js file to handle receiving the input and passing it along to the customizer JS. Look for “api.ColorControl” and how it gets the setting from the HTML and sets it. I’m not a JS guru, that sort of thing is slightly outside my own scope. 🙂

Any ideas for other controls that themes might need? Leave a comment, maybe somebody has a solution.