[ Index ]

PHP Cross Reference of WordPress Trunk (Updated Daily)





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

WordPress Customize Manager classes

File Size: 6122 lines (202 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
Returns true if it's an Ajax request.

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

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
Returns the Ajax wp_die() handler if it's a customized request.

return: callable Die handler.

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

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

establish_loaded_changeset()   X-Ref
Establishes 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
Stops previewing the selected theme.

Removes filters to change the active 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
Gets the changeset UUID.

return: string UUID.

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

return: WP_Theme

settings()   X-Ref
Gets the registered settings.

return: array

controls()   X-Ref
Gets the registered controls.

return: array

containers()   X-Ref
Gets the registered containers.

return: array

sections()   X-Ref
Gets the registered sections.

return: array

panels()   X-Ref
Gets the registered panels.

return: array Panels.

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

return: bool

wp_loaded()   X-Ref
Registers 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.

return: int
param: int $status Status.

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

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

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

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

dismiss_user_auto_draft_changesets()   X-Ref
Dismisses 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
Gets 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
Gets the data stored in a changeset post.

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

changeset_data()   X-Ref
Gets changeset data.

return: array Changeset data.

import_theme_starter_content( $starter_content = array()   X-Ref
Imports 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
Prepares starter content attachments.

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

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

_save_starter_content_changeset()   X-Ref
Saves starter content changeset.

unsanitized_post_values( $args = array()   X-Ref
Gets 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.

return: array
param: array $args {

post_value( $setting, $default_value = 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.

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

set_post_value( $setting_id, $value )   X-Ref
Overrides 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
Prints JavaScript settings.

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

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

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

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

customize_preview_override_404_status()   X-Ref
Prevents 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
Prints base element for preview frame.

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

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

remove_frameless_preview_messenger_channel()   X-Ref
Removes 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
Prints 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( $callback = null )   X-Ref
Removes the signature in case we experience a case where the Customizer was not properly executed.

return: callable|null Value passed through for {@see 'wp_die_handler'} filter.
param: callable|null $callback Optional. Value passed through for {@see 'wp_die_handler'} filter.

is_preview()   X-Ref
Determines whether it is a theme preview or not.

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

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

return: string Template name.

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

return: string Stylesheet name.

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

return: string Theme root.

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

return: string Theme root.

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

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

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.

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

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.

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

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

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

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

preserve_insert_changeset_post_content( $data, $postarr, $unsanitized_postarr )   X-Ref
Preserves 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.

return: array Filtered post data.
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().

trash_changeset_post( $post )   X-Ref
Trashes or deletes 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

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

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

grant_edit_post_capability_for_changeset( $caps, $cap, $user_id, $args )   X-Ref
Re-maps '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.

return: array Capabilities.
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.

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 Whether to take over the changeset. Default 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
Filters heartbeat settings for the Customizer.

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

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

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

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

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

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, $latest_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.

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

_publish_changeset_values( $changeset_post_id )   X-Ref
Publishes the values of a changeset.

This will publish 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.

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

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

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

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

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

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

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

add_dynamic_settings( $setting_ids )   X-Ref
Registers 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.

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

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

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

remove_setting( $id )   X-Ref
Removes 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
Adds a customize panel.

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

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

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

remove_panel( $id )   X-Ref
Removes 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
Registers 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
Renders JS templates for all registered panel types.

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

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

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

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

remove_section( $id )   X-Ref
Removes 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
Registers 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
Renders JS templates for all registered section types.

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

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

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

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

remove_control( $id )   X-Ref
Removes 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
Registers 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
Renders 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.

return: int
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.

prepare_controls()   X-Ref
Prepares 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
Enqueues scripts for customize controls.

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

return: bool Whether the user agent is iOS.

get_document_title_template()   X-Ref
Gets 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
Sets the initial URL to be previewed.

URL is validated.

param: string $preview_url URL to be previewed.

get_preview_url()   X-Ref
Gets 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
Gets 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
Gets messenger channel.

return: string Messenger channel.

set_return_url( $return_url )   X-Ref
Sets 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
Gets URL to link the user to when closing the Customizer.

return: string URL for link to close Customizer.

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

param: array $autofocus {

get_autofocus()   X-Ref
Gets the autofocused constructs.

return: string[] {

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

return: array Nonces.

customize_pane_settings()   X-Ref
Prints 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
Registers some default controls.

has_published_pages()   X-Ref
Returns 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
Adds settings from the POST data that were not added with code, e.g. dynamically-created settings for Widgets

handle_load_themes_request()   X-Ref
Loads 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.

return: mixed
param: string $color

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

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

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

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

_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.

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

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

Ensures that the provided URL is supported.

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

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

return: string Sanitized URL.
param: string $value 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 : Fri Sep 30 08:20:01 2022 Cross-referenced by PHPXref