WordPress.org

Codex

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

Class Reference/WP Customize Manager/add control

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

Arguments

label
Displayed label. Example: 'label' => __( 'Base Color Scheme', 'twentyfifteen' ),
description
Example: 'description' => __( 'Applied to the header on small screens and the sidebar on wide screens.', 'twentyfifteen' ),
section
Any readily available or user defined section. Some available sections: themes, title_tagline, colors, header_image (only when enabled), background_image (only when enabled), static_front_page. Example: 'section' => 'colors',
priority
Optional. themes (0), title_tagline (20), colors (40), header_image (60), background_image (80), static_front_page (120).
type
Example: 'type' => 'select',
settings
??? It does something but I don't know what. /wp-includes/class-wp-customize-control.php says: "If not defined, uses the $id as the setting ID."
choices, height, width etc.
It's possible to pass custom parameters for specific control types. These are available only for some control types. Example for "select" control only: 'choices'=> twentyfifteen_get_color_scheme_choices(),

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.