Class: WP_Customize_Control

Customize Control class.


Properties

Name Type(s) Default Value Summary
instance_count integer Static ⋅ Incremented with each new class instantiation, then stored in $instance_number.

Used when sorting two instances whose priorities are equal.

instance_number integer Order in which this instance was created in relation to other instances.
manager WP_Customize_Manager Customizer manager.
id string Control ID.
settings array All settings tied to the control.
setting string The primary setting for the control (if there is one).
capability string Capability required to use this control.

Normally this is empty and the capability is derived from the capabilities of the associated $settings.

priority integer Order priority to load the control in Customizer.
section string Section the control belongs to.
label string Label for the control.
description string Description for the control.
choices array List of choices for 'radio' or 'select' type controls, where values are the keys, and labels are the values.
input_attrs array List of custom input attributes for control output, where attribute names are the keys and values are the values.

Not used for 'checkbox', 'radio', 'select', 'textarea', or 'dropdown-pages' control types.

allow_addition boolean Show UI for adding new content, currently only used for the dropdown-pages control.
json array
type string Control's Type.
active_callback callable Callback.

Methods

WP_Customize_Control:: __construct( WP_Customize_Manager $manager, string $id, array $args = array() )

Constructor. Since 3.4.0.

Supplied $args override class property defaults.

If $args['settings'] is not defined, use the $id as the setting ID.

Arguments

Name Type(s) Default Value Description
$manager WP_Customize_Manager

Customizer bootstrap instance.

$id string

Control ID.

$args array

{ Optional. Arguments to override class property defaults.

@type int                  $instance_number Order in which this instance was created in relation
                                            to other instances.
@type WP_Customize_Manager $manager         Customizer bootstrap instance.
@type string               $id              Control ID.
@type array                $settings        All settings tied to the control. If undefined, `$id` will
                                            be used.
@type string               $setting         The primary setting for the control (if there is one).
                                            Default 'default'.
@type int                  $priority        Order priority to load the control. Default 10.
@type string               $section         Section the control belongs to. Default empty.
@type string               $label           Label for the control. Default empty.
@type string               $description     Description for the control. Default empty.
@type array                $choices         List of choices for 'radio' or 'select' type controls, where
                                            values are the keys, and labels are the values.
                                            Default empty array.
@type array                $input_attrs     List of custom input attributes for control output, where
                                            attribute names are the keys and values are the values. Not
                                            used for 'checkbox', 'radio', 'select', 'textarea', or
                                            'dropdown-pages' control types. Default empty array.
@type array                $json            Deprecated. Use WP_Customize_Control::json() instead.
@type string               $type            Control type. Core controls include 'text', 'checkbox',
                                            'textarea', 'radio', 'select', and 'dropdown-pages'. Additional
                                            input types such as 'email', 'url', 'number', 'hidden', and
                                            'date' are supported implicitly. Default 'text'.

}


WP_Customize_Control:: active( )

Check whether control is active to current Customizer preview. Since 4.0.0.

Returns

boolean

Whether the control is active to the current preview.


WP_Customize_Control:: active_callback( )

Default callback used when invoking WP_Customize_Control::active(). Since 4.0.0.

Subclasses can override this with their specific logic, or they may provide an 'active_callback' argument to the constructor.

Returns

true

Always true.


WP_Customize_Control:: check_capabilities( )

Checks if the user can use this control. Since 3.4.0.

Returns false if the user cannot manipulate one of the associated settings, or if one of the associated settings does not exist. Also returns false if the associated section does not exist or if its capability check returns false.

Returns

boolean

False if theme doesn't support the control or user doesn't have the required permissions, otherwise true.


WP_Customize_Control:: content_template( )

An Underscore (JS) template for this control's content (but not its container). Since 4.1.0.

Class variables for this control class are available in the data JS object; export custom variables by overriding WP_Customize_Control::to_json().


WP_Customize_Control:: enqueue( )

Enqueue control related scripts/styles. Since 3.4.0.


WP_Customize_Control:: get_content( )

Get the control's content for insertion into the Customizer pane. Since 4.1.0.

Returns

string

Contents of the control.


Get the data link attribute for a setting. Since 3.4.0. Since 4.9.0.

Arguments

Name Type(s) Default Value Description
$setting_key string

Returns

string

Data link parameter, a data-customize-setting-link attribute if the $setting_key refers to a pre-registered setting, and a data-customize-setting-key-link attribute if the setting is not yet registered.


WP_Customize_Control:: input_attrs( )

Render the custom attributes for the control's input element. Since 4.0.0.


WP_Customize_Control:: json( )

Get the data to export to the client via JSON. Since 4.1.0.

Returns

array

Array of parameters passed to the JavaScript.


Render the data link attribute for the control's input element. Since 3.4.0.

Arguments

Name Type(s) Default Value Description
$setting_key string

WP_Customize_Control:: maybe_render( )

Check capabilities and render the control. Since 3.4.0.


WP_Customize_Control:: print_template( )

Render the control's JS template. Since 4.1.0.

This function is only run for control types that have been registered with WP_Customize_Manager::register_control_type().

In the future, this will also print the template for the control's container element and be override-able.


WP_Customize_Control:: render( )

Renders the control wrapper and calls $this->render_content() for the internals. Since 3.4.0.


WP_Customize_Control:: render_content( )

Render the control's content. Since 3.4.0.

Allows the content to be overridden without having to rewrite the wrapper in $this::render().

Supports basic input types text, checkbox, textarea, radio, select and dropdown-pages. Additional input types such as email, url, number, hidden and date are supported implicitly.

Control content can alternately be rendered in JS. See WP_Customize_Control::print_template().


WP_Customize_Control:: to_json( )

Refresh the parameters passed to the JavaScript via JSON. Since 3.4.0.


WP_Customize_Control:: value( string $setting_key = 'default' )

Fetch a setting's value. Since 3.4.0.

Grabs the main setting by default.

Arguments

Name Type(s) Default Value Description
$setting_key string

Returns

mixed

The requested setting's value, if the setting exists.


WordPress Developer Newsletter

Stay informed of new chapter releases, important WordPress API updates and more.