Documentation

Class: Control

wp.customize. Control

new Control(id, options)

A Customizer Control. A control provides a UI element that allows a user to modify a Customizer Setting.
Parameters:
Name Type Description
id string Unique identifier for the control instance.
options object Options hash for the control instance.
Properties
Name Type Argument Default Description
type object Type of control (e.g. text, radio, dropdown-pages, etc.)
content string <optional>
 The HTML content for the control or at least its container. This should normally be left blank and instead supplying a templateId.
templateId string <optional>
 Template ID for control's content.
priority string <optional>
 10 Order of priority to show the control within the section.
active string <optional>
 true Whether the control is active.
section string The ID of the section the control belongs to.
setting mixed <optional>
 The ID of the main setting or an instance of this setting.
settings mixed An object with keys (e.g. default) that maps to setting IDs or Setting/Value objects, or an array of setting IDs or Setting/Value objects.
Properties
Name Type Description
default mixed The ID of the setting the control relates to.
data string @todo Is this used?
label string Label.
description string Description.
instanceNumber number <optional>
 Order in which this instance was created in relation to other instances.
params object <optional>
 Deprecated wrapper for the above properties.
Source:
See:
  • PHP class WP_Customize_Control.
Returns:
Type
void

Extends

  • wp.customize.Class

Members

defaults :object

Default params.
Type:
  • object
Since:
  • 4.9.0
Source:

Methods

_toggleActive(active [, params])

Parameters:
Name Type Argument Description
active Boolean
params Object <optional>
Since:
  • 4.1.0
Source:
Returns:
False if state already applied.
Type
Boolean

activate( [params])

Parameters:
Name Type Argument Description
params Object <optional>
Source:
Returns:
False if already active.
Type
Boolean

<private> addNewPage()

Add a new page to a dropdown-pages control reusing menus code for this.
Since:
  • 4.7.0
Source:
Returns:
Type
void

deactivate( [params])

Parameters:
Name Type Argument Description
params Object <optional>
Source:
Returns:
False if already inactive.
Type
Boolean

embed()

Embed the control into the page.
Source:

expand( [params])

Normal controls do not expand, so just expand its parent
Parameters:
Name Type Argument Description
params Object <optional>
Source:

focus( [params])

Expand a panel, section, or control and focus on the first focusable element.
Parameters:
Name Type Argument Description
params Object <optional>
Properties
Name Type Argument Description
completeCallback function <optional>
Since:
  • 4.1.0
Source:

getNotificationsContainerElement()

Get the element inside of a control's container that contains the validation error message. Control subclasses may override this to return the proper container to render notifications into. Injects the notification container for existing controls that lack the necessary container, including special handling for nav menu items and widgets.
Since:
  • 4.6.0
Source:
Returns:
Setting validation message element.
Type
jQuery

linkElements()

Link elements between settings and inputs.
Since:
  • 4.7.0
Source:
Returns:
Type
void

onChangeActive(active, args)

Update UI in response to a change in the control's active state. This does not change the active state, it merely handles the behavior for when it does change.
Parameters:
Name Type Description
active Boolean
args Object
Properties
Name Type Description
duration Number
completeCallback function
Since:
  • 4.1.0
Source:

ready()

Triggered when the control's markup has been injected into the DOM.
Source:
Returns:
Type
void

renderContent()

Render the control from its JS template, if it exists. The control's container must already exist in the DOM.
Since:
  • 4.1.0
Source:

renderNotifications()

Render notifications. Renders the `control.notifications` into the control's container. Control subclasses may override this method to do their own handling of rendering notifications.
This:
Since:
  • 4.6.0
Deprecated:
  • in favor of `control.notifications.render()`
Source:

setupNotifications()

Set up notifications.
Since:
  • 4.9.0
Source:
Returns:
Type
void

toggle()

Deprecated:
  • 4.1.0 Use this.onChangeActive() instead.
Source: