Documentation

Class: WidgetControl

wp.customize.Widgets. WidgetControl

new WidgetControl()

wp.customize.Widgets.WidgetControl Customizer control for widgets. Note that 'widget_form' must match the WP_Widget_Form_Customize_Control::$type
Since:
  • 4.1.0
Source:

Extends

Members

_toggleExpanded

Since:
  • 4.1.0
Source:

collapse

Since:
  • 4.1.0
Source:

defaults :object

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

expand

Since:
  • 4.1.0
Overrides:
Source:

Methods

<private> _getInputs(container)

Find all inputs in a widget container that should be considered when comparing the loaded form with the sanitized form, whose fields will be aligned to copy the sanitized over. The elements returned by this are passed into this._getInputsSignature(), and they are iterated over when copying sanitized values over to the form loaded.
Parameters:
Name Type Description
container jQuery element in which to look for inputs
Source:
Returns:
inputs
Type
jQuery

<private> _getInputsSignature(inputs)

Iterate over supplied inputs and create a signature string for all of them together. This string can be used to compare whether or not the form has all of the same fields.
Parameters:
Name Type Description
inputs jQuery
Source:
Returns:
Type
string

<private> _getInputState(input)

Get the state for an input depending on its type.
Parameters:
Name Type Description
input jQuery | Element
Source:
Returns:
Type
string | boolean | array | *

<private> _moveWidgetByOne(offset)

Parameters:
Name Type Description
offset Number 1|-1
Source:

<private> _setInputState(input, state)

Update an input's state based on its type.
Parameters:
Name Type Description
input jQuery | Element
state string | boolean | array | *
Source:

_setupControlToggle()

Show/hide the control when clicking on the form title, when clicking the close button
Source:

_setupHighlightEffects()

Highlight widgets in preview when interacted with in the Customizer
Source:

_setupModel()

Handle changes to the setting
Source:

_setupRemoveUI()

Set up event handlers for widget removal
Source:

_setupReorderUI()

Set up the widget-reorder-nav
Source:

_setupUpdateUI()

Set up event handlers for widget updating
Source:

_setupWideWidget()

Add special behaviors for wide widget controls
Source:

_setupWidgetTitle()

Update the title of the form if a title field is entered
Source:

<private> addNewPage()

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

collapseForm()

Collapse the widget form control
Deprecated:
  • 4.1.0 Use this.collapse() instead.
Source:

embed()

Embed the control into the page.
Inherited From:
Source:

embedWidgetContent()

Embed the actual widget form inside of .widget-content and finally trigger the widget-added event.
Since:
  • 4.4.0
Source:

embedWidgetControl()

Embed the .widget element inside the li container.
Since:
  • 4.4.0
Source:

expandControlSection()

Expand the accordion section containing a control
Source:

expandForm()

Expand the widget form control
Deprecated:
  • 4.1.0 Use this.expand() instead.
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
Inherited From:
Source:
Returns:
Setting validation message element.
Type
jQuery

getSidebarWidgetsControl()

Source:
Returns:
Type
Array:.<wp.customize.controlConstructor.sidebar_widgets:>

getWidgetSidebarPosition()

Get the position (index) of the widget in the containing sidebar
Source:
Returns:
Type
Number

highlightSectionAndControl()

Highlight the widget control and section
Source:

linkElements()

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

moveDown()

Move widget up one in the sidebar
Source:

moveUp()

Move widget up one in the sidebar
Source:

onChangeActive(active, args)

Update widget control to indicate whether it is currently rendered. Overrides api.Control.toggle()
Parameters:
Name Type Description
active Boolean
args Object
Properties
Name Type Description
completeCallback function
Since:
  • 4.1.0
Overrides:
Source:

onChangeExpanded(expanded, args)

Respond to change in the expanded state.
Parameters:
Name Type Description
expanded Boolean
args Object merged on top of this.defaultActiveArguments
Source:

ready()

Set up the control.
Since:
  • 3.9.0
Overrides:
Source:

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
Inherited From:
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
Inherited From:
Deprecated:
  • in favor of `control.notifications.render()`
Source:

setupNotifications()

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

toggle()

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

toggleForm( [showOrHide])

Expand or collapse the widget control
Parameters:
Name Type Argument Description
showOrHide boolean | undefined <optional>
 If not supplied, will be inverse of current visibility
Deprecated:
  • this is poor naming, and it is better to directly set control.expanded( showOrHide )
Source:

toggleWidgetMoveArea( [showOrHide])

Toggle visibility of the widget move area
Parameters:
Name Type Argument Description
showOrHide Boolean <optional>
Source:

updateWidget( [args])

Submit the widget form via Ajax and get back the updated instance, along with the new widget control form to render.
Parameters:
Name Type Argument Description
args object <optional>
Properties
Name Type Argument Default Description
instance Object | null <optional>
 null When the model changes, the instance is sent here; otherwise, the inputs from the form are used
complete function | null <optional>
 null Function which is called when the request finishes. Context is bound to the control. First argument is any error. Following arguments are for success.
ignoreActiveElement Boolean <optional>
 false Whether or not updating a field will be deferred if focus is still on the element.
Source: