Customizer Panels and Field Types

WordPress 4.0 introduced a few new features for the customizer, including panels and input field types. This post on the Core Make blog explains the updates well- but since I was experimenting with it today I thought I’d post a few more examples.

new-controls

I put together a code snippet that registers a custom panel, section, and then displays a few of the new field types: url, e-mail, password, textarea, date, and range. Arguably the only real useful ones are textarea and range as you’ll see in the notes below.

Panel

Here’s the basics of adding a new panel and section:

function prefix_customizer_register( $wp_customize ) {

	$wp_customize->add_panel( 'panel_id', array(
	    'priority' => 10,
	    'capability' => 'edit_theme_options',
	    'theme_supports' => '',
	    'title' => __( 'Example Panel', 'textdomain' ),
	    'description' => __( 'Description of what this panel does.', 'textdomain' ),
	) );

	$wp_customize->add_section( 'section_id', array(
	    'priority' => 10,
	    'capability' => 'edit_theme_options',
	    'theme_supports' => '',
	    'title' => __( 'Example Section', 'textdomain' ),
	    'description' => '',
	    'panel' => 'panel_id',
	) );

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

This won’t show up until some controls are added to the section.

URL Field

I’m not sure there’s any advantage over using a standard input field. I guess it could be considered more semantic. Chrome doesn’t appear to do any front-end validation.

$wp_customize->add_setting( 'url_field_id', array(
	'default' => '',
	'type' => 'theme_mod',
	'capability' => 'edit_theme_options',
	'transport' => '',
	'sanitize_callback' => 'esc_url',
) );

$wp_customize->add_control( 'url_field_id', array(
    'type' => 'url',
    'priority' => 10,
    'section' => 'section_id',
    'label' => __( 'URL Field', 'textdomain' ),
    'description' => '',
) );

Email Field

Again, I’m not sure there’s any advantage to the email field over a standard input field as long as you are sanitizing correctly.

$wp_customize->add_setting( 'email_field_id', array(
	'default' => '',
	'type' => 'theme_mod',
	'capability' => 'edit_theme_options',
	'transport' => '',
	'sanitize_callback' => 'sanitize_email',
) );

$wp_customize->add_control( 'email_field_id', array(
    'type' => 'email',
    'priority' => 10,
    'section' => 'section_id',
    'label' => __( 'Email Field', 'textdomain' ),
    'description' => '',
) );

Password Field

Displays characters as dots rather than the actual input. I’ve had a few people ask for this option when they were required to enter API keys or details they may not have wanted folks to see over their shoulder, but I’m not sure how useful it is.

Using password fields also triggered 1Password every time the customizer saves, which I wasn’t so excited about.

$wp_customize->add_setting( 'password_field_id', array(
	'default' => '',
	'type' => 'theme_mod',
	'capability' => 'edit_theme_options',
	'transport' => '',
	'sanitize_callback' => 'sanitize_text_field',
) );

$wp_customize->add_control( 'password_field_id', array(
    'type' => 'password',
    'priority' => 10,
    'section' => 'section_id',
    'label' => __( 'Password Field', 'textdomain' ),
    'description' => '',
) );

Textarea Field

Finally, no longer a custom control!

$wp_customize->add_setting( 'textarea_field_id', array(
	'default' => '',
	'type' => 'theme_mod',
	'capability' => 'edit_theme_options',
	'transport' => '',
	'sanitize_callback' => 'esc_textarea',
) );

$wp_customize->add_control( 'textarea_field_id', array(
    'type' => 'textarea',
    'priority' => 10,
    'section' => 'section_id',
    'label' => __( 'Textarea Field', 'textdomain' ),
    'description' => '',
) );

Date Field

Very poor browser support: http://caniuse.com/#feat=input-date. You’re much better off using a custom control here.

$wp_customize->add_setting( 'date_field_id', array(
	'default' => '',
	'type' => 'theme_mod',
	'capability' => 'edit_theme_options',
	'transport' => '',
	'sanitize_callback' => ''
) );

$wp_customize->add_control( 'date_field_id', array(
    'type' => 'date',
    'priority' => 10,
    'section' => 'section_id',
    'label' => __( 'Date Field', 'textdomain' ),
    'description' => '',
) );

Range Field

Pretty good browser support: http://caniuse.com/#feat=input-range.

$wp_customize->add_setting( 'range_field_id', array(
	'default' => '',
	'type' => 'theme_mod',
	'capability' => 'edit_theme_options',
	'transport' => '',
	'sanitize_callback' => 'intval',
) );

$wp_customize->add_control( 'range_field_id', array(
    'type' => 'range',
    'priority' => 10,
    'section' => 'section_id',
    'label' => __( 'Range Field', 'textdomain' ),
    'description' => '',
    'input_attrs' => array(
        'min' => 0,
        'max' => 100,
        'step' => 1,
        'class' => 'example-class',
        'style' => 'color: #0a0',
    ),
) );

Are there any important ones I missed? Thoughts?

About Devin

I am a developer based in Austin, Texas. I run a little theme shop called DevPress and help manage a WooCommerce shop with Universal Yums. Find me on twitter @devinsays.

13 Responses

  1. I really like the new input types for the customizer, unfortunately, since this was only added in 4.0, using this technique causes options not to be displayed on older versions of WordPress. Is there any polyfill or way around this?

  2. Alfred Crosby

    Hi Devin, nice article :) I just take a look at WordPress Theme Customization API page, but looks like WordPress isn’t ready to publish the Customizer Panel and new HTML5 field or I missed something?

  3. Hi,
    Im trying to modify the textarea, to display more rows, and limit characters.
    This is what i added, but no luck…
    Can you possibly put me in the right direction?
    Thank you.

    `$wp_customize->add_control(‘home_text’, array(
    ‘label’ => ‘Home Text:’,
    ‘section’ => ‘tsum_home_section’,
    ‘type’ => ‘textarea’,
    ‘priority’ => 30,
    ‘input_attrs’ => array(
    ‘rows’ => 50,
    ‘maxlength’ => 130,
    ),
    ));
    `

    1. Kimzi

      I did it like this :

      // create class to define textarea controls in Customizer
      class sj_customize_textarea_control extends wp_customize_control {

      public $type = ‘textarea’;
      public function render_content() {

      echo ”;
      echo ” . esc_html( $this-> label ) . ”;
      echo ” . esc_html( $this-> description ) . ”;
      echo ‘link();
      echo ‘>’ . esc_textarea( $this->value() ) . ”;
      echo ”;
      }
      }

  4. blackhawk

    How to we the range value and display it on page. I’m having trouble doing that based on the example code mentioned in the article. thanks!

  5. is there any idea about slider type in customizer ?
    i need to put values between specific number for example a slider option to choose a number between 24-48 ? is there any way to add that ?

Leave a Reply