Class: WP_Customize_Nav_Menu_Setting

Extends WP_Customize_Setting

Customize Setting to represent a nav_menu.

Subclass of WP_Customize_Setting to represent a nav_menu taxonomy term, and the IDs for the nav_menu_items associated with the nav menu.


Properties

Name Type(s) Default Value Summary
type string Inherited ⋅ Type of customize settings.
default string Inherited ⋅ The default value for the setting.
transport string Inherited ⋅ Options for rendering the live preview of changes in Theme Customizer.

Set this value to 'postMessage' to enable a custom Javascript handler to render changes to this setting as opposed to reloading the whole page.

term_id integer The term ID represented by this setting instance.

A negative value represents a placeholder ID for a new menu not yet saved.

previous_term_id integer Previous (placeholder) term ID used before creating a new menu.

This value will be exported to JS via the \'customize_save_response' filter so that JavaScript can update the settings to refer to the newly-assigned term ID. This value is always negative to indicate it does not refer to a real term.

is_updated boolean Whether or not update() was called.
update_status string Status for calling the update method, used in customize_save_response filter.

See \'customize_save_response'.

When status is inserted, the placeholder term ID is stored in $previous_term_id. When status is error, the error is stored in $update_error.

update_error WP_Error Any error object returned by wp_update_nav_menu_object() when setting is updated.
_current_menus_sort_orderby string Temporary non-closure passing of orderby value to function.
_widget_nav_menu_updates array Storage for data to be sent back to client in customize_save_response filter.

See \'customize_save_response'.

manager WP_Customize_Manager Inherited ⋅ Customizer bootstrap instance.
id string Inherited ⋅ Unique string identifier for the setting.
capability string | array Inherited ⋅ Capability required to edit this setting.
theme_supports string Inherited ⋅ Feature a theme is required to support to enable this setting.
validate_callback callable Inherited ⋅ Server-side validation callback for the setting's value.
sanitize_callback callable Inherited ⋅ Callback to filter a Customize setting value in un-slashed form.
sanitize_js_callback string Inherited ⋅ Callback to convert a Customize PHP setting value to a value that is JSON serializable.
dirty boolean Inherited ⋅ Whether or not the setting is initially dirty when created.

This is used to ensure that a setting will be sent from the pane to the preview when loading the Customizer. Normally a setting only is synced to the preview if it has been changed. This allows the setting to be sent from the start.

id_data array Inherited ⋅ ID Data.
is_previewed boolean Inherited ⋅ Whether or not preview() was called.
aggregated_multidimensionals array InheritedStatic ⋅ Cache of multidimensional values to improve performance.
is_multidimensional_aggregated boolean Inherited ⋅ Whether the multidimensional setting is aggregated.
_previewed_blog_id integer Inherited ⋅ The ID for the current site when the preview() method was called.
_original_value mixed Inherited ⋅ Original non-previewed value stored by the preview method.

Methods

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

Constructor. Since 3.4.0.

Any supplied $args override class property defaults.

Arguments

Name Type(s) Default Value Description
$manager WP_Customize_Manager
$id string

An specific ID of the setting. Can be a theme mod or option name.

$args array

Setting arguments.


WP_Customize_Nav_Menu_Setting:: _clear_aggregated_multidimensional_preview_applied_flag( )

Clear out the previewed-applied flag for a multidimensional-aggregated value whenever its post value is updated. Since 4.4.0.

This ensures that the new value will get sanitized and used the next time that WP_Customize_Setting::_multidimensional_preview_filter() is called for this setting.


WP_Customize_Nav_Menu_Setting:: _multidimensional_preview_filter( mixed $original )

Callback function to filter multidimensional theme mods and options. Since 4.4.0.

For all multidimensional settings of a given type, the preview filter for the first setting previewed will be used to apply the values for the others.

Arguments

Name Type(s) Default Value Description
$original mixed

Original root value.

Returns

mixed

New or old value.


WP_Customize_Nav_Menu_Setting:: _preview_filter( mixed $original )

Callback function to filter non-multidimensional theme mods and options. Since 3.4.0.

If switch_to_blog() was called after the preview() method, and the current site is now not the same site, then this method does a no-op and returns the original value.

Arguments

Name Type(s) Default Value Description
$original mixed

Old value.

Returns

mixed

New or old value.


WP_Customize_Nav_Menu_Setting:: _sort_menus_by_orderby( object $menu1, object $menu2 )

This method is deprecated.

Sort menu objects by the class-supplied orderby property. Since 4.3.0.

This is a workaround for a lack of closures.

Arguments

Name Type(s) Default Value Description
$menu1 object
$menu2 object

Returns

integer


WP_Customize_Nav_Menu_Setting:: _update_option( )

This method is deprecated.

Deprecated method. Since 3.4.0.


WP_Customize_Nav_Menu_Setting:: _update_theme_mod( )

This method is deprecated.

Deprecated method. Since 3.4.0.


WP_Customize_Nav_Menu_Setting:: aggregate_multidimensional( )

Set up the setting for aggregated multidimensional values. Since 4.4.0.

When a multidimensional setting gets aggregated, all of its preview and update calls get combined into one call, greatly improving performance.


WP_Customize_Nav_Menu_Setting:: amend_customize_save_response( array $data )

Export data for the JS client. Since 4.3.0.

Arguments

Name Type(s) Default Value Description
$data array

Additional information passed back to the 'saved' event on wp.customize.

Returns

array

Export data.


WP_Customize_Nav_Menu_Setting:: check_capabilities( )

Validate user capabilities whether the theme supports the setting. Since 3.4.0.

Returns

boolean

False if theme doesn't support the setting or user can't change setting, otherwise true.


WP_Customize_Nav_Menu_Setting:: filter_nav_menu_options( array $nav_menu_options )

Filters the nav_menu_options option to include this menu's auto_add preference. Since 4.3.0.

Arguments

Name Type(s) Default Value Description
$nav_menu_options array

Nav menu options including auto_add.

Returns

array

(Kaybe) modified nav menu options.


WP_Customize_Nav_Menu_Setting:: filter_nav_menu_options_value( array $nav_menu_options, integer $menu_id, boolean $auto_add )

Updates a nav_menu_options array. Since 4.3.0.

Arguments

Name Type(s) Default Value Description
$nav_menu_options array

Array as returned by get_option( 'nav_menu_options' ).

$menu_id integer

The term ID for the given menu.

$auto_add boolean

Whether to auto-add or not.

Returns

array

(Maybe) modified nav_menu_otions array.


WP_Customize_Nav_Menu_Setting:: filter_wp_get_nav_menu_object( object | null $menu_obj, string $menu_id )

Filters the wp_get_nav_menu_object() result to supply the previewed menu object. Since 4.3.0.

Requesting a nav_menu object by anything but ID is not supported.

Arguments

Name Type(s) Default Value Description
$menu_obj object | null

Object returned by wp_get_nav_menu_object().

$menu_id string

ID of the nav_menu term. Requests by slug or name will be ignored.

Returns

object | null


WP_Customize_Nav_Menu_Setting:: filter_wp_get_nav_menus( array<mixed,\WP_Term> $menus, array $args )

Filters the wp_get_nav_menus() result to ensure the inserted menu object is included, and the deleted one is removed. Since 4.3.0.

Arguments

Name Type(s) Default Value Description
$menus array<mixed,WP_Term>

An array of menu objects.

$args array

An array of arguments used to retrieve menu objects.

Returns

array<mixed,WP_Term>

Array of menu objects.


WP_Customize_Nav_Menu_Setting:: get_root_value( mixed $default = null )

Get the root value for a setting, especially for multidimensional ones. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$default mixed

Value to return if root does not exist.

Returns

mixed


WP_Customize_Nav_Menu_Setting:: id_data( )

Get parsed ID data for multidimensional setting. Since 4.4.0.

Returns

array

{ ID data for multidimensional setting.

@type string $base ID base
@type array  $keys Keys for multidimensional array.

}


WP_Customize_Nav_Menu_Setting:: is_current_blog_previewed( )

Return true if the current site is not the same as the previewed site. Since 4.2.0.

Returns

boolean

If preview() has been called.


WP_Customize_Nav_Menu_Setting:: js_value( )

Sanitize the setting's value for use in JavaScript. Since 3.4.0.

Returns

mixed

The requested escaped value.


WP_Customize_Nav_Menu_Setting:: json( )

Retrieves the data to export to the client via JSON. Since 4.6.0.

Returns

array

Array of parameters passed to JavaScript.


WP_Customize_Nav_Menu_Setting:: multidimensional( &$root, $keys, boolean $create = false )

Multidimensional helper function. Since 3.4.0.

Arguments

Name Type(s) Default Value Description
$root
$keys
$create boolean

Default is false.

Returns

array | void

Keys are 'root', 'node', and 'key'.


WP_Customize_Nav_Menu_Setting:: multidimensional_get( $root, $keys, mixed $default = null )

Will attempt to fetch a specific value from a multidimensional array. Since 3.4.0.

Arguments

Name Type(s) Default Value Description
$root
$keys
$default mixed

A default value which is used as a fallback. Default is null.

Returns

mixed

The requested value or the default value.


WP_Customize_Nav_Menu_Setting:: multidimensional_isset( $root, $keys )

Will attempt to check if a specific value in a multidimensional array is set. Since 3.4.0.

Arguments

Name Type(s) Default Value Description
$root
$keys

Returns

boolean

True if value is set, false if not.


WP_Customize_Nav_Menu_Setting:: multidimensional_replace( $root, $keys, mixed $value )

Will attempt to replace a specific value in a multidimensional array. Since 3.4.0.

Arguments

Name Type(s) Default Value Description
$root
$keys
$value mixed

The value to update.

Returns

mixed


WP_Customize_Nav_Menu_Setting:: post_value( mixed $default = null )

Fetch and sanitize the $_POST value for the setting. Since 3.4.0.

During a save request prior to save, post_value() provides the new value while value() does not.

Arguments

Name Type(s) Default Value Description
$default mixed

A default value which is used as a fallback. Default is null.

Returns

mixed

The default value on failure, otherwise the sanitized and validated value.


WP_Customize_Nav_Menu_Setting:: preview( )

Add filters to supply the setting's value when accessed. Since 3.4.0. Since 4.4.0.

If the setting already has a pre-existing value and there is no incoming post value for the setting, then this method will short-circuit since there is no change to preview.

Returns

boolean

False when preview short-circuits due no change needing to be previewed.


WP_Customize_Nav_Menu_Setting:: sanitize( string | array $value )

Sanitize an input. Since 3.4.0.

Arguments

Name Type(s) Default Value Description
$value string | array

The value to sanitize.

Returns

string | array | null | WP_Error

Sanitized value, or null/WP_Error if invalid.


WP_Customize_Nav_Menu_Setting:: save( )

Checks user capabilities and theme supports, and then saves the value of the setting. Since 3.4.0.

Returns

false | void

False if cap check fails or value isn't set or is invalid.


WP_Customize_Nav_Menu_Setting:: set_root_value( mixed $value )

Set the root value for a setting, especially for multidimensional ones. Since 4.4.0.

Arguments

Name Type(s) Default Value Description
$value mixed

Value to set as root of multidimensional setting.

Returns

boolean

Whether the multidimensional root was updated successfully.


WP_Customize_Nav_Menu_Setting:: update( mixed $value )

Save the value of the setting, using the related API. Since 3.4.0.

Arguments

Name Type(s) Default Value Description
$value mixed

The value to update.

Returns

boolean

The result of saving the value.


WP_Customize_Nav_Menu_Setting:: validate( mixed $value )

Validates an input. Since 4.6.0.

Arguments

Name Type(s) Default Value Description
$value mixed

Value to validate.

Returns

true | WP_Error

True if the input was validated, otherwise WP_Error.


WP_Customize_Nav_Menu_Setting:: value( )

Fetch the value of the setting. Since 3.4.0.

Returns

mixed

The value.


WordPress Developer Newsletter

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