WordPress.org

Ready to get started?Download WordPress

Codex

Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Class Reference/WP Customize Manager/add control

Contents

Description

Displays a new controller on the Theme Customization admin screen (available in WordPress 3.4 or newer). Controls serve two purposes: they create a "physical" control that allows a user to manipulate a setting, and it also binds a pre-defined setting to a pre-defined section.

This is a method of the WP_Customize_Manager() class and can only be accessed through the $wp_customize object within the customize_register action hook.

Usage

$wp_customize->add_control($id, $args);

Parameters

$id
(mixed) (required) A string or a specific customization controller object.
Default: None
$args
(array) (required) Not used if $id is a control object, otherwise an instance of WP_Customize_Control() (plain text) is created using the specified arguments.
Default: None

Classes

WP_Customize_Control()
Creates a control that allows users to enter plain text. This is also the parent class for the classes that follow.
WP_Customize_Color_Control()
Creates a control that allows users to select a color from a color wheel.
WP_Customize_Upload_Control()
Creates a control that allows users to upload media.
WP_Customize_Image_Control()
Creates a control that allows users to select or upload an image.
WP_Customize_Background_Image_Control()
Creates a control that allows users to select a new background image.
WP_Customize_Header_Image_Control()
Creates a control that allows users to select a new header image.

Custom controls can also be created. For more information, see this post on Ottopress.com

Example

Remember that this example assumes you are already working within the customize_register action hook.

$wp_customize->add_control( new WP_Customize_Color_Control( 
	$wp_customize, 
	'your_control_id', 
	array(
		'label'      => __( 'Header Color', 'mytheme' ),
		'section'    => 'your_section_id',
		'settings'   => 'your_setting_id',
	        'priority'   => 1
	)
));

Alternatively, it is not required to instantiate a WP_Customize_Control object. WordPress will check to see if you are passing in an object and, if absent, will create a new WP_Customize_Control object with the arguments you have passed in.

$wp_customize->add_control(
	'your_control_id', 
	array(
		'label'    => __( 'Control Label', 'mytheme' ),
		'section'  => 'your_section_id',
		'settings' => 'your_setting_id',
		'type'     => 'radio',
		'choices'  => array(
			'left'  => 'left',
			'right' => 'right',
		),
	)
);

Note the 'type' argument is available to specify the input type of the control form element. For more information on these arguments, please refer to WP_Customize_Control

Related

See also index of Class Reference and index of Function Reference.