[ Index ]

WordPress 5.4.1

[ Index ]     [ Classes ]     [ Functions ]     [ Variables ]     [ Constants ]     [ Statistics ]    




/wp-includes/ -> class-wp-customize-manager.php (summary)

WordPress Customize Manager classes

File Size: 6065 lines (200 kb)
Included or required: 2 times
Referenced: 0 times
Includes or requires: 42 files

Defines 117 functions


Functions that are not part of a class:

__construct( $args = array()   X-Ref

param: array $args {

doing_ajax( $action = null )   X-Ref
Return true if it's an Ajax request.

param: string|null $action Whether the supplied Ajax action is being run.
return: bool True if it's an Ajax request, false otherwise.

wp_die( $ajax_message, $message = null )   X-Ref
Custom wp_die wrapper. Returns either the standard message for UI
or the Ajax message.

param: string|WP_Error $ajax_message Ajax return.
param: string          $message      Optional. UI message.

wp_die_handler()   X-Ref
Return the Ajax wp_die() handler if it's a customized request.

return: callable Die handler.

setup_theme()   X-Ref
Start preview and customize theme.

Check if customize query variable exist. Init filters to filter the current theme.

establish_loaded_changeset()   X-Ref
Establish the loaded changeset.

This method runs right at after_setup_theme and applies the 'customize_changeset_branching' filter to determine
whether concurrent changesets are allowed. Then if the Customizer is not initialized with a `changeset_uuid` param,
this method will determine which UUID should be used. If changeset branching is disabled, then the most saved
changeset will be loaded by default. Otherwise, if there are no existing saved changesets or if changeset branching is
enabled, then a new UUID will be generated.

after_setup_theme()   X-Ref
Callback to validate a theme once it is loaded

start_previewing_theme()   X-Ref
If the theme to be previewed isn't the active theme, add filter callbacks
to swap it out at runtime.

stop_previewing_theme()   X-Ref
Stop previewing the selected theme.

Removes filters to change the current theme.

settings_previewed()   X-Ref
Gets whether settings are or will be previewed.

return: bool

autosaved()   X-Ref
Gets whether data from a changeset's autosaved revision should be loaded if it exists.

return: bool Is using autosaved changeset revision.

branching()   X-Ref
Whether the changeset branching is allowed.

return: bool Is changeset branching.

changeset_uuid()   X-Ref
Get the changeset UUID.

return: string UUID.

theme()   X-Ref
Get the theme being customized.

return: WP_Theme

settings()   X-Ref
Get the registered settings.

return: array

controls()   X-Ref
Get the registered controls.

return: array

containers()   X-Ref
Get the registered containers.

return: array

sections()   X-Ref
Get the registered sections.

return: array

panels()   X-Ref
Get the registered panels.

return: array Panels.

is_theme_active()   X-Ref
Checks if the current theme is active.

return: bool

wp_loaded()   X-Ref
Register styles/scripts and initialize the preview of each setting

wp_redirect_status( $status )   X-Ref
Prevents Ajax requests from following redirects when previewing a theme
by issuing a 200 response instead of a 30x.

Instead, the JS will sniff out the location header.

param: int $status Status.
return: int

find_changeset_post_id( $uuid )   X-Ref
Find the changeset post ID for a given changeset UUID.

param: string $uuid Changeset UUID.
return: int|null Returns post ID on success and null on failure.

get_changeset_posts( $args = array()   X-Ref
Get changeset posts.

param: array $args {
return: WP_Post[] Auto-draft changesets.

dismiss_user_auto_draft_changesets()   X-Ref
Dismiss all of the current user's auto-drafts (other than the present one).

return: int The number of auto-drafts that were dismissed.

changeset_post_id()   X-Ref
Get the changeset post id for the loaded changeset.

return: int|null Post ID on success or null if there is no post yet saved.

get_changeset_post_data( $post_id )   X-Ref
Get the data stored in a changeset post.

param: int $post_id Changeset post ID.
return: array|WP_Error Changeset data or WP_Error on error.

changeset_data()   X-Ref
Get changeset data.

return: array Changeset data.

import_theme_starter_content( $starter_content = array()   X-Ref
Import theme starter content into the customized state.

param: array $starter_content Starter content. Defaults to `get_theme_starter_content()`.

prepare_starter_content_attachments( $attachments )   X-Ref
Prepare starter content attachments.

Ensure that the attachments are valid and that they have slugs and file name/path.

param: array $attachments Attachments.
return: array Prepared attachments.

_save_starter_content_changeset()   X-Ref
Save starter content changeset.

unsanitized_post_values( $args = array()   X-Ref
Get dirty pre-sanitized setting values in the current customized state.

The returned array consists of a merge of three sources:
1. If the theme is not currently active, then the base array is any stashed
theme mods that were modified previously but never published.
2. The values from the current changeset, if it exists.
3. If the user can customize, the values parsed from the incoming
`$_POST['customized']` JSON data.
4. Any programmatically-set post values via `WP_Customize_Manager::set_post_value()`.

The name "unsanitized_post_values" is a carry-over from when the customized
state was exclusively sourced from `$_POST['customized']`. Nevertheless,
the value returned will come from the current changeset post and from the
incoming post data.

param: array $args {
return: array

post_value( $setting, $default = null )   X-Ref
Returns the sanitized value for a given setting from the current customized state.

The name "post_value" is a carry-over from when the customized state was exclusively
sourced from `$_POST['customized']`. Nevertheless, the value returned will come
from the current changeset post and from the incoming post data.

param: WP_Customize_Setting $setting A WP_Customize_Setting derived object.
param: mixed                $default Value returned $setting has no post value (added in 4.2.0)
return: string|mixed $post_value Sanitized value or the $default provided.

set_post_value( $setting_id, $value )   X-Ref
Override a setting's value in the current customized state.

The name "post_value" is a carry-over from when the customized state was
exclusively sourced from `$_POST['customized']`.

param: string $setting_id ID for the WP_Customize_Setting instance.
param: mixed  $value      Post value.

customize_preview_init()   X-Ref
Print JavaScript settings.

filter_iframe_security_headers( $headers )   X-Ref
Filter the X-Frame-Options and Content-Security-Policy headers to ensure frontend can load in customizer.

param: array $headers Headers.
return: array Headers.

add_state_query_params( $url )   X-Ref
Add customize state query params to a given URL if preview is allowed.

param: string $url URL.
return: string URL.

customize_preview_override_404_status()   X-Ref
Prevent sending a 404 status when returning the response for the customize
preview, since it causes the jQuery Ajax to fail. Send 200 instead.

customize_preview_base()   X-Ref
Print base element for preview frame.

customize_preview_html5()   X-Ref
Print a workaround to handle HTML5 tags in IE < 9.

customize_preview_loading_style()   X-Ref
Print CSS for loading indicators for the Customizer preview.

remove_frameless_preview_messenger_channel()   X-Ref
Remove customize_messenger_channel query parameter from the preview window when it is not in an iframe.

This ensures that the admin bar will be shown. It also ensures that link navigation will
work as expected since the parent frame is not being sent the URL to navigate to.

customize_preview_settings()   X-Ref
Print JavaScript settings for preview frame.

customize_preview_signature()   X-Ref
Prints a signature so we can ensure the Customizer was properly executed.

remove_preview_signature( $return = null )   X-Ref
Removes the signature in case we experience a case where the Customizer was not properly executed.

param: mixed $return Value passed through for {@see 'wp_die_handler'} filter.
return: mixed Value passed through for {@see 'wp_die_handler'} filter.

is_preview()   X-Ref
Is it a theme preview?

return: bool True if it's a preview, false if not.

get_template()   X-Ref
Retrieve the template name of the previewed theme.

return: string Template name.

get_stylesheet()   X-Ref
Retrieve the stylesheet name of the previewed theme.

return: string Stylesheet name.

get_template_root()   X-Ref
Retrieve the template root of the previewed theme.

return: string Theme root.

get_stylesheet_root()   X-Ref
Retrieve the stylesheet root of the previewed theme.

return: string Theme root.

current_theme( $current_theme )   X-Ref
Filters the current theme and return the name of the previewed theme.

param: $current_theme {@internal Parameter is not used}
return: string Theme name.

validate_setting_values( $setting_values, $options = array()   X-Ref
Validates setting values.

Validation is skipped for unregistered settings or for values that are
already null since they will be skipped anyway. Sanitization is applied
to values that pass validation, and values that become null or `WP_Error`
after sanitizing are marked invalid.

param: array $setting_values Mapping of setting IDs to values to validate and sanitize.
param: array $options {
return: array Mapping of setting IDs to return value of validate method calls, either `true` or `WP_Error`.

prepare_setting_validity_for_js( $validity )   X-Ref
Prepares setting validity for exporting to the client (JS).

Converts `WP_Error` instance into array suitable for passing into the
`wp.customize.Notification` JS model.

param: true|WP_Error $validity Setting validity.
return: true|array If `$validity` was a WP_Error, the error codes will be array-mapped

save()   X-Ref
Handle customize_save WP Ajax request to save/update a changeset.

save_changeset_post( $args = array()   X-Ref
Save the post for the loaded changeset.

param: array $args {
return: array|WP_Error Returns array on success and WP_Error with array data on error.

preserve_insert_changeset_post_content( $data, $postarr, $unsanitized_postarr )   X-Ref
Preserve the initial JSON post_content passed to save into the post.

This is needed to prevent KSES and other {@see 'content_save_pre'} filters
from corrupting JSON data.

Note that WP_Customize_Manager::validate_setting_values() have already
run on the setting values being serialized as JSON into the post content
so it is pre-sanitized.

Also, the sanitization logic is re-run through the respective
WP_Customize_Setting::sanitize() method when being read out of the
changeset, via WP_Customize_Manager::post_value(), and this sanitized
value will also be sent into WP_Customize_Setting::update() for
persisting to the DB.

Multiple users can collaborate on a single changeset, where one user may
have the unfiltered_html capability but another may not. A user with
unfiltered_html may add a script tag to some field which needs to be kept
intact even when another user updates the changeset to modify another field
when they do not have unfiltered_html.

param: array $data                An array of slashed and processed post data.
param: array $postarr             An array of sanitized (and slashed) but otherwise unmodified post data.
param: array $unsanitized_postarr An array of slashed yet *unsanitized* and unprocessed post data as originally passed to wp_insert_post().
return: array Filtered post data.

trash_changeset_post( $post )   X-Ref
Trash or delete a changeset post.

The following re-formulates the logic from `wp_trash_post()` as done in
`wp_publish_post()`. The reason for bypassing `wp_trash_post()` is that it
will mutate the the `post_content` and the `post_name` when they should be

param: int|WP_Post $post The changeset post.
return: mixed A WP_Post object for the trashed post or an empty value on failure.

handle_changeset_trash_request()   X-Ref
Handle request to trash a changeset.

grant_edit_post_capability_for_changeset( $caps, $cap, $user_id, $args )   X-Ref
Re-map 'edit_post' meta cap for a customize_changeset post to be the same as 'customize' maps.

There is essentially a "meta meta" cap in play here, where 'edit_post' meta cap maps to
the 'customize' meta cap which then maps to 'edit_theme_options'. This is currently
required in core for `wp_create_post_autosave()` because it will call
`_wp_translate_postdata()` which in turn will check if a user can 'edit_post', but the
the caps for the customize_changeset post type are all mapping to the meta capability.
This should be able to be removed once #40922 is addressed in core.

param: string[] $caps    Array of the user's capabilities.
param: string   $cap     Capability name.
param: int      $user_id The user ID.
param: array    $args    Adds the context to the cap. Typically the object ID.
return: array Capabilities.

set_changeset_lock( $changeset_post_id, $take_over = false )   X-Ref
Marks the changeset post as being currently edited by the current user.

param: int  $changeset_post_id Changeset post id.
param: bool $take_over Take over the changeset, default is false.

refresh_changeset_lock( $changeset_post_id )   X-Ref
Refreshes changeset lock with the current time if current user edited the changeset before.

param: int $changeset_post_id Changeset post id.

add_customize_screen_to_heartbeat_settings( $settings )   X-Ref
Filter heartbeat settings for the Customizer.

param: array $settings Current settings to filter.
return: array Heartbeat settings.

get_lock_user_data( $user_id )   X-Ref
Get lock user data.

param: int $user_id User ID.
return: array|null User data formatted for client.

check_changeset_lock_with_heartbeat( $response, $data, $screen_id )   X-Ref
Check locked changeset with heartbeat API.

param: array  $response  The Heartbeat response.
param: array  $data      The $_POST data sent.
param: string $screen_id The screen id.
return: array The Heartbeat response.

handle_override_changeset_lock_request()   X-Ref
Removes changeset lock when take over request is sent via Ajax.

_filter_revision_post_has_changed( $post_has_changed, $last_revision, $post )   X-Ref
Filters whether a changeset has changed to create a new revision.

Note that this will not be called while a changeset post remains in auto-draft status.

param: bool    $post_has_changed Whether the post has changed.
param: WP_Post $last_revision    The last revision post object.
param: WP_Post $post             The post object.
return: bool Whether a revision should be made.

_publish_changeset_values( $changeset_post_id )   X-Ref
Publish changeset values.

This will the values contained in a changeset, even changesets that do not
correspond to current manager instance. This is called by
`_wp_customize_publish_changeset()` when a customize_changeset post is
transitioned to the `publish` status. As such, this method should not be
called directly and instead `wp_publish_post()` should be used.

Please note that if the settings in the changeset are for a non-activated
theme, the theme must first be switched to (via `switch_theme()`) before
invoking this method.

param: int $changeset_post_id ID for customize_changeset post. Defaults to the changeset for the current manager instance.
return: true|WP_Error True or error info.

update_stashed_theme_mod_settings( $inactive_theme_mod_settings )   X-Ref
Update stashed theme mod settings.

param: array $inactive_theme_mod_settings Mapping of stylesheet to arrays of theme mod settings.
return: array|false Returns array of updated stashed theme mods or false if the update failed or there were no changes.

refresh_nonces()   X-Ref
Refresh nonces for the current preview.

handle_dismiss_autosave_or_lock_request()   X-Ref
Delete a given auto-draft changeset or the autosave revision for a given changeset or delete changeset lock.

add_setting( $id, $args = array()   X-Ref
Add a customize setting.

param: WP_Customize_Setting|string $id   Customize Setting object, or ID.
param: array                       $args Optional. Array of properties for the new Setting object.
return: WP_Customize_Setting The instance of the setting that was added.

add_dynamic_settings( $setting_ids )   X-Ref
Register any dynamically-created settings, such as those from $_POST['customized']
that have no corresponding setting created.

This is a mechanism to "wake up" settings that have been dynamically created
on the front end and have been sent to WordPress in `$_POST['customized']`. When WP
loads, the dynamically-created settings then will get created and previewed
even though they are not directly created statically with code.

param: array $setting_ids The setting IDs to add.
return: array The WP_Customize_Setting objects added.

get_setting( $id )   X-Ref
Retrieve a customize setting.

param: string $id Customize Setting ID.
return: WP_Customize_Setting|void The setting, if set.

remove_setting( $id )   X-Ref
Remove a customize setting.

Note that removing the setting doesn't destroy the WP_Customize_Setting instance or remove its filters.

param: string $id Customize Setting ID.

add_panel( $id, $args = array()   X-Ref
Add a customize panel.

param: WP_Customize_Panel|string $id   Customize Panel object, or ID.
param: array                     $args Optional. Array of properties for the new Panel object.
return: WP_Customize_Panel The instance of the panel that was added.

get_panel( $id )   X-Ref
Retrieve a customize panel.

param: string $id Panel ID to get.
return: WP_Customize_Panel|void Requested panel instance, if set.

remove_panel( $id )   X-Ref
Remove a customize panel.

Note that removing the panel doesn't destroy the WP_Customize_Panel instance or remove its filters.

param: string $id Panel ID to remove.

register_panel_type( $panel )   X-Ref
Register a customize panel type.

Registered types are eligible to be rendered via JS and created dynamically.

param: string $panel Name of a custom panel which is a subclass of WP_Customize_Panel.

render_panel_templates()   X-Ref
Render JS templates for all registered panel types.

add_section( $id, $args = array()   X-Ref
Add a customize section.

param: WP_Customize_Section|string $id   Customize Section object, or ID.
param: array                       $args Optional. Array of properties for the new Section object.
return: WP_Customize_Section The instance of the section that was added.

get_section( $id )   X-Ref
Retrieve a customize section.

param: string $id Section ID.
return: WP_Customize_Section|void The section, if set.

remove_section( $id )   X-Ref
Remove a customize section.

Note that removing the section doesn't destroy the WP_Customize_Section instance or remove its filters.

param: string $id Section ID.

register_section_type( $section )   X-Ref
Register a customize section type.

Registered types are eligible to be rendered via JS and created dynamically.

param: string $section Name of a custom section which is a subclass of WP_Customize_Section.

render_section_templates()   X-Ref
Render JS templates for all registered section types.

add_control( $id, $args = array()   X-Ref
Add a customize control.

param: WP_Customize_Control|string $id   Customize Control object, or ID.
param: array                       $args Optional. Array of properties for the new Control object.
return: WP_Customize_Control The instance of the control that was added.

get_control( $id )   X-Ref
Retrieve a customize control.

param: string $id ID of the control.
return: WP_Customize_Control|void The control object, if set.

remove_control( $id )   X-Ref
Remove a customize control.

Note that removing the control doesn't destroy the WP_Customize_Control instance or remove its filters.

param: string $id ID of the control.

register_control_type( $control )   X-Ref
Register a customize control type.

Registered types are eligible to be rendered via JS and created dynamically.

param: string $control Name of a custom control which is a subclass of

render_control_templates()   X-Ref
Render JS templates for all registered control types.

_cmp_priority( $a, $b )   X-Ref
Helper function to compare two objects by priority, ensuring sort stability via instance_number.

param: WP_Customize_Panel|WP_Customize_Section|WP_Customize_Control $a Object A.
param: WP_Customize_Panel|WP_Customize_Section|WP_Customize_Control $b Object B.
return: int

prepare_controls()   X-Ref
Prepare panels, sections, and controls.

For each, check if required related components exist,
whether the user has the necessary capabilities,
and sort by priority.

enqueue_control_scripts()   X-Ref
Enqueue scripts for customize controls.

is_ios()   X-Ref
Determine whether the user agent is iOS.

return: bool Whether the user agent is iOS.

get_document_title_template()   X-Ref
Get the template string for the Customizer pane document title.

return: string The template string for the document title.

set_preview_url( $preview_url )   X-Ref
Set the initial URL to be previewed.

URL is validated.

param: string $preview_url URL to be previewed.

get_preview_url()   X-Ref
Get the initial URL to be previewed.

return: string URL being previewed.

is_cross_domain()   X-Ref
Determines whether the admin and the frontend are on different domains.

return: bool Whether cross-domain.

get_allowed_urls()   X-Ref
Get URLs allowed to be previewed.

If the front end and the admin are served from the same domain, load the
preview over ssl if the Customizer is being loaded over ssl. This avoids
insecure content warnings. This is not attempted if the admin and front end
are on different domains to avoid the case where the front end doesn't have
ssl certs. Domain mapping plugins can allow other urls in these conditions
using the customize_allowed_urls filter.

return: array Allowed URLs.

get_messenger_channel()   X-Ref
Get messenger channel.

return: string Messenger channel.

set_return_url( $return_url )   X-Ref
Set URL to link the user to when closing the Customizer.

URL is validated.

param: string $return_url URL for return link.

get_return_url()   X-Ref
Get URL to link the user to when closing the Customizer.

return: string URL for link to close Customizer.

set_autofocus( $autofocus )   X-Ref
Set the autofocused constructs.

param: array $autofocus {

get_autofocus()   X-Ref
Get the autofocused constructs.

return: array {

get_nonces()   X-Ref
Get nonces for the Customizer.

return: array Nonces.

customize_pane_settings()   X-Ref
Print JavaScript settings for parent window.

get_previewable_devices()   X-Ref
Returns a list of devices to allow previewing.

return: array List of devices with labels and default setting.

register_controls()   X-Ref
Register some default controls.

has_published_pages()   X-Ref
Return whether there are published pages.

Used as active callback for static front page section and controls.

return: bool Whether there are published (or to be published) pages.

register_dynamic_settings()   X-Ref
Add settings from the POST data that were not added with code, e.g. dynamically-created settings for Widgets

handle_load_themes_request()   X-Ref
Load themes into the theme browsing/installation UI.

_sanitize_header_textcolor( $color )   X-Ref
Callback for validating the header_textcolor value.

Accepts 'blank', and otherwise uses sanitize_hex_color_no_hash().
Returns default text color if hex color is empty.

param: string $color
return: mixed

_sanitize_background_setting( $value, $setting )   X-Ref
Callback for validating a background setting value.

param: string $value Repeat value.
param: WP_Customize_Setting $setting Setting.
return: string|WP_Error Background value or validation error.

export_header_video_settings( $response, $selective_refresh, $partials )   X-Ref
Export header video settings to facilitate selective refresh.

param: array $response Response.
param: WP_Customize_Selective_Refresh $selective_refresh Selective refresh component.
param: array $partials Array of partials.
return: array

_validate_header_video( $validity, $value )   X-Ref
Callback for validating the header_video value.

Ensures that the selected video is less than 8MB and provides an error message.

param: WP_Error $validity
param: mixed $value
return: mixed

_validate_external_header_video( $validity, $value )   X-Ref
Callback for validating the external_header_video value.

Ensures that the provided URL is supported.

param: WP_Error $validity
param: mixed $value
return: mixed

_sanitize_external_header_video( $value )   X-Ref
Callback for sanitizing the external_header_video value.

param: string $value URL.
return: string Sanitized URL.

_render_custom_logo_partial()   X-Ref
Callback for rendering the custom logo, used in the custom_logo partial.

This method exists because the partial object and context data are passed
into a partial's render_callback so we cannot use get_custom_logo() as
the render_callback directly since it expects a blog ID as the first
argument. When WP no longer supports PHP 5.3, this method can be removed
in favor of an anonymous function.

return: string Custom logo.

Generated: Tue May 19 15:51:04 2020 Cross-referenced by PHPXref 0.7.1