[ Index ]

PHP Cross Reference of WordPress Trunk (Updated Daily)

Search

title

Body

[close]

/wp-includes/ -> theme.php (summary)

Theme, template, and stylesheet functions.

File Size: 4417 lines (134 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 3 files
 wp-includes/class-wp-customize-manager.php
 wp-admin/includes/class-custom-image-header.php
 wp-admin/includes/class-custom-background.php

Defines 88 functions

  wp_get_themes()
  wp_get_theme()
  wp_clean_themes_cache()
  is_child_theme()
  get_stylesheet()
  get_stylesheet_directory()
  get_stylesheet_directory_uri()
  get_stylesheet_uri()
  get_locale_stylesheet_uri()
  get_template()
  get_template_directory()
  get_template_directory_uri()
  get_theme_roots()
  register_theme_directory()
  search_theme_directories()
  get_theme_root()
  get_theme_root_uri()
  get_raw_theme_root()
  locale_stylesheet()
  switch_theme()
  validate_current_theme()
  validate_theme_requirements()
  get_theme_mods()
  get_theme_mod()
  set_theme_mod()
  remove_theme_mod()
  remove_theme_mods()
  get_header_textcolor()
  header_textcolor()
  display_header_text()
  has_header_image()
  get_header_image()
  get_header_image_tag()
  the_header_image_tag()
  _get_random_header_data()
  get_random_header_image()
  is_random_header_image()
  header_image()
  get_uploaded_header_images()
  get_custom_header()
  register_default_headers()
  unregister_default_headers()
  has_header_video()
  get_header_video_url()
  the_header_video_url()
  get_header_video_settings()
  has_custom_header()
  is_header_video_active()
  get_custom_header_markup()
  the_custom_header_markup()
  get_background_image()
  background_image()
  get_background_color()
  background_color()
  _custom_background_cb()
  wp_custom_css_cb()
  wp_get_custom_css_post()
  wp_get_custom_css()
  wp_update_custom_css_post()
  add_editor_style()
  remove_editor_styles()
  get_editor_stylesheets()
  get_theme_starter_content()
  add_theme_support()
  _custom_header_background_just_in_time()
  _custom_logo_header_styles()
  get_theme_support()
  remove_theme_support()
  _remove_theme_support()
  current_theme_supports()
  require_if_theme_supports()
  register_theme_feature()
  get_registered_theme_features()
  get_registered_theme_feature()
  _delete_attachment_theme_mod()
  check_theme_switched()
  _wp_customize_include()
  _wp_customize_publish_changeset()
  _wp_customize_changeset_filter_insert_post_data()
  _wp_customize_loader_settings()
  wp_customize_url()
  wp_customize_support_script()
  is_customize_preview()
  _wp_keep_alive_customize_changeset_dependent_auto_drafts()
  create_initial_theme_features()
  wp_is_block_theme()
  wp_theme_get_element_class_name()
  _add_default_theme_supports()

Functions
Functions that are not part of a class:

wp_get_themes( $args = array()   X-Ref
Returns an array of WP_Theme objects based on the arguments.

Despite advances over get_themes(), this function is quite expensive, and grows
linearly with additional themes. Stick to wp_get_theme() if possible.

param: array $args {
return: WP_Theme[] Array of WP_Theme objects.

wp_get_theme( $stylesheet = '', $theme_root = '' )   X-Ref
Gets a WP_Theme object for a theme.

param: string $stylesheet Optional. Directory name for the theme. Defaults to active theme.
param: string $theme_root Optional. Absolute path of the theme root to look in.
return: WP_Theme Theme object. Be sure to check the object's exists() method

wp_clean_themes_cache( $clear_update_cache = true )   X-Ref
Clears the cache held by get_theme_roots() and WP_Theme.

param: bool $clear_update_cache Whether to clear the theme updates cache.

is_child_theme()   X-Ref
Whether a child theme is in use.

return: bool True if a child theme is in use, false otherwise.

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

The theme name that is currently set as the front end theme.

For all intents and purposes, the template name and the stylesheet name
are going to be the same for most cases.

return: string Stylesheet name.

get_stylesheet_directory()   X-Ref
Retrieves stylesheet directory path for the active theme.

return: string Path to active theme's stylesheet directory.

get_stylesheet_directory_uri()   X-Ref
Retrieves stylesheet directory URI for the active theme.

return: string URI to active theme's stylesheet directory.

get_stylesheet_uri()   X-Ref
Retrieves stylesheet URI for the active theme.

The stylesheet file name is 'style.css' which is appended to the stylesheet directory URI path.
See get_stylesheet_directory_uri().

return: string URI to active theme's stylesheet.

get_locale_stylesheet_uri()   X-Ref
Retrieves the localized stylesheet URI.

The stylesheet directory for the localized stylesheet files are located, by
default, in the base theme directory. The name of the locale file will be the
locale followed by '.css'. If that does not exist, then the text direction
stylesheet will be checked for existence, for example 'ltr.css'.

The theme may change the location of the stylesheet directory by either using
the {@see 'stylesheet_directory_uri'} or {@see 'locale_stylesheet_uri'} filters.

If you want to change the location of the stylesheet files for the entire
WordPress workflow, then change the former. If you just have the locale in a
separate folder, then change the latter.

return: string URI to active theme's localized stylesheet.

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

return: string Template name.

get_template_directory()   X-Ref
Retrieves template directory path for the active theme.

return: string Path to active theme's template directory.

get_template_directory_uri()   X-Ref
Retrieves template directory URI for the active theme.

return: string URI to active theme's template directory.

get_theme_roots()   X-Ref
Retrieves theme roots.

return: array|string An array of theme roots keyed by template/stylesheet

register_theme_directory( $directory )   X-Ref
Registers a directory that contains themes.

param: string $directory Either the full filesystem path to a theme folder
return: bool True if successfully registered a directory that contains themes,

search_theme_directories( $force = false )   X-Ref
Searches all registered theme directories for complete and valid themes.

param: bool $force Optional. Whether to force a new directory scan. Default false.
return: array|false Valid themes found on success, false on failure.

get_theme_root( $stylesheet_or_template = '' )   X-Ref
Retrieves path to themes directory.

Does not have trailing slash.

param: string $stylesheet_or_template Optional. The stylesheet or template name of the theme.
return: string Themes directory path.

get_theme_root_uri( $stylesheet_or_template = '', $theme_root = '' )   X-Ref
Retrieves URI for themes directory.

Does not have trailing slash.

param: string $stylesheet_or_template Optional. The stylesheet or template name of the theme.
param: string $theme_root             Optional. The theme root for which calculations will be based,
return: string Themes directory URI.

get_raw_theme_root( $stylesheet_or_template, $skip_cache = false )   X-Ref
Gets the raw theme root relative to the content directory with no filters applied.

param: string $stylesheet_or_template The stylesheet or template name of the theme.
param: bool   $skip_cache             Optional. Whether to skip the cache.
return: string Theme root.

locale_stylesheet()   X-Ref
Displays localized stylesheet link element.


switch_theme( $stylesheet )   X-Ref
Switches the theme.

Accepts one argument: $stylesheet of the theme. It also accepts an additional function signature
of two arguments: $template then $stylesheet. This is for backward compatibility.

param: string $stylesheet Stylesheet name.

validate_current_theme()   X-Ref
Checks that the active theme has the required files.

Standalone themes need to have a `templates/index.html` or `index.php` template file.
Child themes need to have a `Template` header in the `style.css` stylesheet.

Does not initially check the default theme, which is the fallback and should always exist.
But if it doesn't exist, it'll fall back to the latest core default theme that does exist.
Will switch theme to the fallback theme if active theme does not validate.

You can use the {@see 'validate_current_theme'} filter to return false to disable
this functionality.

return: bool

validate_theme_requirements( $stylesheet )   X-Ref
Validates the theme requirements for WordPress version and PHP version.

Uses the information from `Requires at least` and `Requires PHP` headers
defined in the theme's `style.css` file.

param: string $stylesheet Directory name for the theme.
return: true|WP_Error True if requirements are met, WP_Error on failure.

get_theme_mods()   X-Ref
Retrieves all theme modifications.

return: array Theme modifications.

get_theme_mod( $name, $default_value = false )   X-Ref
Retrieves theme modification value for the active theme.

If the modification name does not exist and `$default_value` is a string, then the
default will be passed through the {@link https://www.php.net/sprintf sprintf()}
PHP function with the template directory URI as the first value and the
stylesheet directory URI as the second value.

param: string $name          Theme modification name.
param: mixed  $default_value Optional. Theme modification default value. Default false.
return: mixed Theme modification value.

set_theme_mod( $name, $value )   X-Ref
Updates theme modification value for the active theme.

param: string $name  Theme modification name.
param: mixed  $value Theme modification value.
return: bool True if the value was updated, false otherwise.

remove_theme_mod( $name )   X-Ref
Removes theme modification name from active theme list.

If removing the name also removes all elements, then the entire option
will be removed.

param: string $name Theme modification name.

remove_theme_mods()   X-Ref
Removes theme modifications option for the active theme.


get_header_textcolor()   X-Ref
Retrieves the custom header text color in 3- or 6-digit hexadecimal form.

return: string Header text color in 3- or 6-digit hexadecimal form (minus the hash symbol).

header_textcolor()   X-Ref
Displays the custom header text color in 3- or 6-digit hexadecimal form (minus the hash symbol).


display_header_text()   X-Ref
Whether to display the header text.

return: bool

has_header_image()   X-Ref
Checks whether a header image is set or not.

return: bool Whether a header image is set or not.

get_header_image()   X-Ref
Retrieves header image for custom header.

return: string|false

get_header_image_tag( $attr = array()   X-Ref
Creates image tag markup for a custom header image.

param: array $attr Optional. Additional attributes for the image tag. Can be used
return: string HTML image element markup or empty string on failure.

the_header_image_tag( $attr = array()   X-Ref
Displays the image markup for a custom header image.

param: array $attr Optional. Attributes for the image markup. Default empty.

_get_random_header_data()   X-Ref
Gets random header image data from registered images in theme.

return: object

get_random_header_image()   X-Ref
Gets random header image URL from registered images in theme.

return: string Path to header image.

is_random_header_image( $type = 'any' )   X-Ref
Checks if random header image is in use.

Always true if user expressly chooses the option in Appearance > Header.
Also true if theme has multiple header images registered, no specific header image
is chosen, and theme turns on random headers with add_theme_support().

param: string $type The random pool to use. Possible values include 'any',
return: bool

header_image()   X-Ref
Displays header image URL.


get_uploaded_header_images()   X-Ref
Gets the header images uploaded for the active theme.

return: array

get_custom_header()   X-Ref
Gets the header image data.

return: object

register_default_headers( $headers )   X-Ref
Registers a selection of default headers to be displayed by the custom header admin UI.

param: array $headers Array of headers keyed by a string ID. The IDs point to arrays

unregister_default_headers( $header )   X-Ref
Unregisters default headers.

This function must be called after register_default_headers() has already added the
header you want to remove.

param: string|array $header The header string id (key of array) to remove, or an array thereof.
return: bool|void A single header returns true on success, false on failure.

has_header_video()   X-Ref
Checks whether a header video is set or not.

return: bool Whether a header video is set or not.

get_header_video_url()   X-Ref
Retrieves header video URL for custom header.

Uses a local video if present, or falls back to an external video.

return: string|false Header video URL or false if there is no video.

the_header_video_url()   X-Ref
Displays header video URL.


get_header_video_settings()   X-Ref
Retrieves header video settings.

return: array

has_custom_header()   X-Ref
Checks whether a custom header is set or not.

return: bool True if a custom header is set. False if not.

is_header_video_active()   X-Ref
Checks whether the custom header video is eligible to show on the current page.

return: bool True if the custom header video should be shown. False if not.

get_custom_header_markup()   X-Ref
Retrieves the markup for a custom header.

The container div will always be returned in the Customizer preview.

return: string The markup for a custom header on success.

the_custom_header_markup()   X-Ref
Prints the markup for a custom header.

A container div will always be printed in the Customizer preview.


get_background_image()   X-Ref
Retrieves background image for custom background.

return: string

background_image()   X-Ref
Displays background image path.


get_background_color()   X-Ref
Retrieves value for custom background color.

return: string

background_color()   X-Ref
Displays background color value.


_custom_background_cb()   X-Ref
Default custom background callback.


wp_custom_css_cb()   X-Ref
Renders the Custom CSS style element.


wp_get_custom_css_post( $stylesheet = '' )   X-Ref
Fetches the `custom_css` post for a given theme.

param: string $stylesheet Optional. A theme object stylesheet name. Defaults to the active theme.
return: WP_Post|null The custom_css post or null if none exists.

wp_get_custom_css( $stylesheet = '' )   X-Ref
Fetches the saved Custom CSS content for rendering.

param: string $stylesheet Optional. A theme object stylesheet name. Defaults to the active theme.
return: string The Custom CSS Post content.

wp_update_custom_css_post( $css, $args = array()   X-Ref
Updates the `custom_css` post for a given theme.

Inserts a `custom_css` post when one doesn't yet exist.

param: string $css CSS, stored in `post_content`.
param: array  $args {
return: WP_Post|WP_Error Post on success, error on failure.

add_editor_style( $stylesheet = 'editor-style.css' )   X-Ref
Adds callback for custom TinyMCE editor stylesheets.

The parameter $stylesheet is the name of the stylesheet, relative to
the theme root. It also accepts an array of stylesheets.
It is optional and defaults to 'editor-style.css'.

This function automatically adds another stylesheet with -rtl prefix, e.g. editor-style-rtl.css.
If that file doesn't exist, it is removed before adding the stylesheet(s) to TinyMCE.
If an array of stylesheets is passed to add_editor_style(),
RTL is only added for the first stylesheet.

Since version 3.4 the TinyMCE body has .rtl CSS class.
It is a better option to use that class and add any RTL styles to the main stylesheet.

param: array|string $stylesheet Optional. Stylesheet name or array thereof, relative to theme root.

remove_editor_styles()   X-Ref
Removes all visual editor stylesheets.

return: bool True on success, false if there were no stylesheets to remove.

get_editor_stylesheets()   X-Ref
Retrieves any registered editor stylesheet URLs.

return: string[] If registered, a list of editor stylesheet URLs.

get_theme_starter_content()   X-Ref
Expands a theme's starter content configuration using core-provided data.

return: array Array of starter content.

add_theme_support( $feature, ...$args )   X-Ref
Registers theme support for a given feature.

Must be called in the theme's functions.php file to work.
If attached to a hook, it must be {@see 'after_setup_theme'}.
The {@see 'init'} hook may be too late for some features.

Example usage:

add_theme_support( 'title-tag' );
add_theme_support( 'custom-logo', array(
'height' => 480,
'width'  => 720,
) );

param: string $feature The feature being added. Likely core values include:
param: mixed  ...$args Optional extra arguments to pass along with certain features.
return: void|false Void on success, false on failure.

_custom_header_background_just_in_time()   X-Ref
Registers the internal custom header and background routines.


_custom_logo_header_styles()   X-Ref
Adds CSS to hide header text for custom logo, based on Customizer setting.


get_theme_support( $feature, ...$args )   X-Ref
Gets the theme support arguments passed when registering that support.

Example usage:

get_theme_support( 'custom-logo' );
get_theme_support( 'custom-header', 'width' );

param: string $feature The feature to check. See add_theme_support() for the list
param: mixed  ...$args Optional extra arguments to be checked against certain features.
return: mixed The array of extra arguments or the value for the registered feature.

remove_theme_support( $feature )   X-Ref
Allows a theme to de-register its support of a certain feature

Should be called in the theme's functions.php file. Generally would
be used for child themes to override support from the parent theme.

param: string $feature The feature being removed. See add_theme_support() for the list
return: bool|void Whether feature was removed.

_remove_theme_support( $feature )   X-Ref
Do not use. Removes theme support internally without knowledge of those not used
by themes directly.

param: string $feature The feature being removed. See add_theme_support() for the list
return: bool True if support was removed, false if the feature was not registered.

current_theme_supports( $feature, ...$args )   X-Ref
Checks a theme's support for a given feature.

Example usage:

current_theme_supports( 'custom-logo' );
current_theme_supports( 'html5', 'comment-form' );

param: string $feature The feature being checked. See add_theme_support() for the list
param: mixed  ...$args Optional extra arguments to be checked against certain features.
return: bool True if the active theme supports the feature, false otherwise.

require_if_theme_supports( $feature, $file )   X-Ref
Checks a theme's support for a given feature before loading the functions which implement it.

param: string $feature The feature being checked. See add_theme_support() for the list
param: string $file    Path to the file.
return: bool True if the active theme supports the supplied feature, false otherwise.

register_theme_feature( $feature, $args = array()   X-Ref
Registers a theme feature for use in add_theme_support().

This does not indicate that the active theme supports the feature, it only describes
the feature's supported options.

param: string $feature The name uniquely identifying the feature. See add_theme_support()
param: array  $args {
return: true|WP_Error True if the theme feature was successfully registered, a WP_Error object if not.

get_registered_theme_features()   X-Ref
Gets the list of registered theme features.

return: array[] List of theme features, keyed by their name.

get_registered_theme_feature( $feature )   X-Ref
Gets the registration config for a theme feature.

param: string $feature The feature name. See add_theme_support() for the list
return: array|null The registration args, or null if the feature was not registered.

_delete_attachment_theme_mod( $id )   X-Ref
Checks an attachment being deleted to see if it's a header or background image.

If true it removes the theme modification which would be pointing at the deleted
attachment.

param: int $id The attachment ID.

check_theme_switched()   X-Ref
Checks if a theme has been changed and runs 'after_switch_theme' hook on the next WP load.

See {@see 'after_switch_theme'}.


_wp_customize_include()   X-Ref
Includes and instantiates the WP_Customize_Manager class.

Loads the Customizer at plugins_loaded when accessing the customize.php admin
page or when any request includes a wp_customize=on param or a customize_changeset
param (a UUID). This param is a signal for whether to bootstrap the Customizer when
WordPress is loading, especially in the Customizer preview
or when making Customizer Ajax requests for widgets or menus.


_wp_customize_publish_changeset( $new_status, $old_status, $changeset_post )   X-Ref
Publishes a snapshot's changes.

param: string  $new_status     New post status.
param: string  $old_status     Old post status.
param: WP_Post $changeset_post Changeset post object.

_wp_customize_changeset_filter_insert_post_data( $post_data, $supplied_post_data )   X-Ref
Filters changeset post data upon insert to ensure post_name is intact.

This is needed to prevent the post_name from being dropped when the post is
transitioned into pending status by a contributor.

param: array $post_data          An array of slashed post data.
param: array $supplied_post_data An array of sanitized, but otherwise unmodified post data.
return: array Filtered data.

_wp_customize_loader_settings()   X-Ref
Adds settings for the customize-loader script.


wp_customize_url( $stylesheet = '' )   X-Ref
Returns a URL to load the Customizer.

param: string $stylesheet Optional. Theme to customize. Defaults to active theme.
return: string

wp_customize_support_script()   X-Ref
Prints a script to check whether or not the Customizer is supported,
and apply either the no-customize-support or customize-support class
to the body.

This function MUST be called inside the body tag.

Ideally, call this function immediately after the body tag is opened.
This prevents a flash of unstyled content.

It is also recommended that you add the "no-customize-support" class
to the body tag by default.


is_customize_preview()   X-Ref
Whether the site is being previewed in the Customizer.

return: bool True if the site is being previewed in the Customizer, false otherwise.

_wp_keep_alive_customize_changeset_dependent_auto_drafts( $new_status, $old_status, $post )   X-Ref
Makes sure that auto-draft posts get their post_date bumped or status changed
to draft to prevent premature garbage-collection.

When a changeset is updated but remains an auto-draft, ensure the post_date
for the auto-draft posts remains the same so that it will be
garbage-collected at the same time by `wp_delete_auto_drafts()`. Otherwise,
if the changeset is updated to be a draft then update the posts
to have a far-future post_date so that they will never be garbage collected
unless the changeset post itself is deleted.

When a changeset is updated to be a persistent draft or to be scheduled for
publishing, then transition any dependent auto-drafts to a draft status so
that they likewise will not be garbage-collected but also so that they can
be edited in the admin before publishing since there is not yet a post/page
editing flow in the Customizer. See #39752.

param: string   $new_status Transition to this post status.
param: string   $old_status Previous post status.
param: \WP_Post $post       Post data.

create_initial_theme_features()   X-Ref
Creates the initial theme features when the 'setup_theme' action is fired.

See {@see 'setup_theme'}.


wp_is_block_theme()   X-Ref
Returns whether the active theme is a block-based theme or not.

return: bool Whether the active theme is a block-based theme or not.

wp_theme_get_element_class_name( $element )   X-Ref
Given an element name, returns a class name.

Alias of WP_Theme_JSON::get_element_class_name.

param: string $element The name of the element.
return: string The name of the class.

_add_default_theme_supports()   X-Ref
Adds default theme supports for block themes when the 'after_setup_theme' action fires.

See {@see 'after_setup_theme'}.




Generated : Tue Dec 24 08:20:01 2024 Cross-referenced by PHPXref