Creating Your Own Controller (Field)
Customizer allows you to easily create your own fields (UI elements). Let's create support for the field type="range" (range slider). This field allows selecting values by dragging the slider.
Core controllers:
Basic fields:
color— WP_Customize_Color_Controldate_time— WP_Customize_Date_Time_Controltheme— WP_Customize_Theme_Control
Basic fields:
text,checkbox,textarea,radio,select,dropdown-pages, andemail,url,number,hidden,datework through the main class WP_Customize_Control. See method WP_Customize_Control::render_content().
Nav Menu:
new_menu— WP_Customize_New_Menu_Controlnav_menu_name— WP_Customize_Nav_Menu_Name_Controlnav_menu_location— WP_Customize_Nav_Menu_Location_Controlnav_menu_item— WP_Customize_Nav_Menu_Item_Controlnav_menu_locations— WP_Customize_Nav_Menu_Locations_Controlnav_menu_auto_add— WP_Customize_Nav_Menu_Auto_Add_Control
Widget:
widget_form— WP_Widget_Form_Customize_Controlsidebar_widgets— WP_Widget_Area_Customize_Control
Image:
media— WP_Customize_Media_Controlimage— WP_Customize_Image_Controlbackground— WP_Customize_Background_Image_Controlcropped_image— WP_Customize_Cropped_Image_Controlheader— WP_Customize_Header_Image_Controlupload— WP_Customize_Upload_Control
Others:
background_position— WP_Customize_Background_Position_Controlcode_editor— WP_Customize_Code_Editor_Control
To create a new field, you need to create a class based on WP_Customize_Control:
<?php
if( class_exists( 'WP_Customize_Control' ) ) {
class WP_Customize_Range extends WP_Customize_Control {
public $type = 'range';
public function __construct( $manager, $id, $args = array() ) {
parent::__construct( $manager, $id, $args );
$defaults = [
'min' => 0,
'max' => 10,
'step' => 1
];
$args = wp_parse_args( $args, $defaults );
$this->min = $args['min'];
$this->max = $args['max'];
$this->step = $args['step'];
}
public function render_content(){
?>
<label>
<span class="customize-control-title"><?php echo esc_html( $this->label ); ?></span>
<input class="range-slider"
min="<?php echo $this->min ?>"
max="<?php echo $this->max ?>"
step="<?php echo $this->step ?>"
type="range"
<?php $this->link(); ?>
value="<?php echo esc_attr( $this->value() ); ?>"
oninput="jQuery(this).next('input').val( jQuery(this).val() )">
<input type="text" value="<?php echo esc_attr( $this->value() ); ?>" onKeyUp="jQuery(this).prev('input').val( jQuery(this).val() )">
</label>
<?php
}
}
}
We extend the base class WP_Customize_Control. We declare the property $type and the method render_content(). In the method, we need to output the HTML element (form field), in which we should use the methods:
- $this->value() — the current value of the field.
- $this->link() — the name attribute of the field.
min, max, step — these are arbitrarily created properties that can then be used in the class.
Usage
Now an example of how to use our new controller to create a new field.
add_action( 'customize_register', 'my_customize_register' );
function my_customize_register( WP_Customize_Manager $wp_customize ){
$section = 'section_id';
$wp_customize->add_section( $section, [
'title' => 'My Settings',
'priority' => 220, // at the bottom of customizer
//'panel' => $panel,
] );
$wp_customize->add_setting( 'my_range' , array(
'default' => 0,
'transport' => 'postMessage',
) );
$wp_customize->add_control( new WP_Customize_Range( $wp_customize, 'my_range', [
'label' => 'My Range',
'min' => 10,
'max' => 9999,
'step' => 10,
'section' => 'section_id',
] ) );
}
Note that the section 'section_id' must already be created. How to do this see here.
Live Preview
All you need to do to support live preview is to update the field in HTML with the new value of the range using JavaScript.
wp.customize( 'my_range', function( value ) {
value.bind( function( newval ) {
$( '#my_range span' ).html( newval );
} );
} );
As a result, we will get something like this:
