Class: WP_Customize_Nav_Menu_Item_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.

post_id integer The post ID represented by this setting instance. This is the db_id.

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

value array Storage of pre-setup menu item to prevent wasted calls to wp_setup_nav_menu_item().
previous_post_id integer Previous (placeholder) post ID used before creating a new menu item.

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 post ID. This value is always negative to indicate it does not refer to a real post.

original_nav_menu_term_id integer When previewing or updating a menu item, this stores the previous nav_menu_term_id which ensures that we can apply the proper filters.
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 post ID is stored in $previous_post_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_item() when setting is updated.
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_Item_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_Item_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_Item_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_Item_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_Item_Setting:: _update_option( )

This method is deprecated.

Deprecated method. Since 3.4.0.


WP_Customize_Nav_Menu_Item_Setting:: _update_theme_mod( )

This method is deprecated.

Deprecated method. Since 3.4.0.


WP_Customize_Nav_Menu_Item_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_Item_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

Save response data.


WP_Customize_Nav_Menu_Item_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_Item_Setting:: filter_wp_get_nav_menu_items( array<mixed,\WP_Post> $items, WP_Term $menu, array $args )

Filters the wp_get_nav_menu_items() result to supply the previewed menu items. Since 4.3.0.

Arguments

Name Type(s) Default Value Description
$items array<mixed,WP_Post>

An array of menu item post objects.

$menu WP_Term

The menu object.

$args array

An array of arguments used to retrieve menu item objects.

Returns

array<mixed,WP_Post>

Array of menu item objects.


WP_Customize_Nav_Menu_Item_Setting:: flush_cached_value( integer $menu_id, integer $menu_item_id )

Clear the cached value when this nav menu item is updated. Since 4.3.0.

Arguments

Name Type(s) Default Value Description
$menu_id integer

The term ID for the menu.

$menu_item_id integer

The post ID for the menu item.


WP_Customize_Nav_Menu_Item_Setting:: get_original_title( object $item )

Get original title. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$item object

Nav menu item.

Returns

string

The original title.


WP_Customize_Nav_Menu_Item_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_Item_Setting:: get_type_label( object $item )

Get type label. Since 4.7.0.

Arguments

Name Type(s) Default Value Description
$item object

Nav menu item.


WP_Customize_Nav_Menu_Item_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_Item_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_Item_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_Item_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_Item_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_Item_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_Item_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_Item_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_Item_Setting:: populate_value( )

Ensure that the value is fully populated with the necessary properties. Since 4.3.0.

Translates some properties added by wp_setup_nav_menu_item() and removes others.


WP_Customize_Nav_Menu_Item_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_Item_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_Item_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_Item_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_Item_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_Item_Setting:: sort_wp_get_nav_menu_items( array<mixed,\WP_Post> $items, WP_Term $menu, array $args )

Re-apply the tail logic also applied on $items by wp_get_nav_menu_items(). Since 4.3.0.

Arguments

Name Type(s) Default Value Description
$items array<mixed,WP_Post>

An array of menu item post objects.

$menu WP_Term

The menu object.

$args array

An array of arguments used to retrieve menu item objects.

Returns

array<mixed,WP_Post>

Array of menu item objects.


WP_Customize_Nav_Menu_Item_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_Item_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_Item_Setting:: value( )

Fetch the value of the setting. Since 3.4.0.

Returns

mixed

The value.


WP_Customize_Nav_Menu_Item_Setting:: value_as_wp_post_nav_menu_item( )

Get the value emulated into a WP_Post and set up as a nav_menu_item. Since 4.3.0.

Returns

WP_Post

With wp_setup_nav_menu_item() applied.


WordPress Developer Newsletter

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