WordPress 4.2
[autoinstalls/wordpress.git] / wp-includes / theme.php
index 85119eda1eaa3b9480afe51ca4d03ac08981f2e0..1b372da37ab28aecb2942cfd8b3a0f9767afe14d 100644 (file)
@@ -271,7 +271,6 @@ function get_locale_stylesheet_uri() {
  * Retrieve name of the current theme.
  *
  * @since 1.5.0
- * @uses apply_filters() Calls 'template' filter on template option.
  *
  * @return string Template name.
  */
@@ -407,6 +406,7 @@ function search_theme_directories( $force = false ) {
        $found_themes = array();
 
        $wp_theme_directories = (array) $wp_theme_directories;
+       $relative_theme_roots = array();
 
        // Set up maybe-relative, maybe-absolute array of theme directories.
        // We always want to return absolute, but we need to cache relative
@@ -676,7 +676,6 @@ function preview_theme() {
 
        ob_start( 'preview_theme_ob_filter' );
 }
-add_action('setup_theme', 'preview_theme');
 
 /**
  * Private function to modify the current template when previewing a theme
@@ -804,9 +803,9 @@ function switch_theme( $stylesheet ) {
                add_option( "theme_mods_$stylesheet", $default_theme_mods );
        } else {
                /*
-                * Since retrieve_widgets() is called when initializing the customizer theme,
+                * Since retrieve_widgets() is called when initializing a theme in the Customizer,
                 * we need to to remove the theme mods to avoid overwriting changes made via
-                * the widget customizer when accessing wp-admin/widgets.php.
+                * the Customizer when accessing wp-admin/widgets.php.
                 */
                if ( 'wp_ajax_customize_save' === current_action() ) {
                        remove_theme_mod( 'sidebars_widgets' );
@@ -872,7 +871,7 @@ function validate_current_theme() {
  *
  * @since 3.1.0
  *
- * @return array Theme modifications.
+ * @return array|null Theme modifications.
  */
 function get_theme_mods() {
        $theme_slug = get_option( 'stylesheet' );
@@ -910,7 +909,7 @@ function get_theme_mod( $name, $default = false ) {
                /**
                 * Filter the theme modification, or 'theme_mod', value.
                 *
-                * The dynamic portion of the hook name, $name, refers to
+                * The dynamic portion of the hook name, `$name`, refers to
                 * the key name of the modification array. For example,
                 * 'header_textcolor', 'header_image', and so on depending
                 * on the theme options.
@@ -935,7 +934,7 @@ function get_theme_mod( $name, $default = false ) {
  * @since 2.1.0
  *
  * @param string $name Theme modification name.
- * @param string $value theme modification value.
+ * @param mixed  $value theme modification value.
  */
 function set_theme_mod( $name, $value ) {
        $mods = get_theme_mods();
@@ -944,7 +943,7 @@ function set_theme_mod( $name, $value ) {
        /**
         * Filter the theme mod value on save.
         *
-        * The dynamic portion of the hook name, $name, refers to the key name of
+        * The dynamic portion of the hook name, `$name`, refers to the key name of
         * the modification array. For example, 'header_textcolor', 'header_image',
         * and so on depending on the theme options.
         *
@@ -1035,12 +1034,25 @@ function display_header_text() {
        return 'blank' != $text_color;
 }
 
+/**
+ * Check whether a header image is set or not.
+ *
+ * @since 4.2.0
+ *
+ * @see get_header_image()
+ *
+ * @return bool Whether a header image is set or not.
+ */
+function has_header_image() {
+       return (bool) get_header_image();
+}
+
 /**
  * Retrieve header image for custom header.
  *
  * @since 2.1.0
  *
- * @return string
+ * @return string|false
  */
 function get_header_image() {
        $url = get_theme_mod( 'header_image', get_theme_support( 'custom-header', 'default-image' ) );
@@ -1143,7 +1155,10 @@ function is_random_header_image( $type = 'any' ) {
  * @since 2.1.0
  */
 function header_image() {
-       echo esc_url( get_header_image() );
+       $image = get_header_image();
+       if ( $image ) {
+               echo esc_url( $image );
+       }
 }
 
 /**
@@ -1365,7 +1380,7 @@ body.custom-background { <?php echo trim( $style ); ?> }
  *
  * @since 3.0.0
  *
- * @param mixed $stylesheet Optional. Stylesheet name or array thereof, relative to theme root.
+ * @param array|string $stylesheet Optional. Stylesheet name or array thereof, relative to theme root.
  *     Defaults to 'editor-style.css'
  */
 function add_editor_style( $stylesheet = 'editor-style.css' ) {
@@ -1472,8 +1487,12 @@ function add_theme_support( $feature ) {
 
        switch ( $feature ) {
                case 'post-formats' :
-                       if ( is_array( $args[0] ) )
-                               $args[0] = array_intersect( $args[0], array_keys( get_post_format_slugs() ) );
+                       if ( is_array( $args[0] ) ) {
+                               $post_formats = get_post_format_slugs();
+                               unset( $post_formats['standard'] );
+
+                               $args[0] = array_intersect( $args[0], array_keys( $post_formats ) );
+                       }
                        break;
 
                case 'html5' :
@@ -1482,7 +1501,7 @@ function add_theme_support( $feature ) {
                                // Build an array of types for back-compat.
                                $args = array( 0 => array( 'comment-list', 'comment-form', 'search-form' ) );
                        } elseif ( ! is_array( $args[0] ) ) {
-                               _doing_it_wrong( "add_theme_support( 'html5' )", 'You need to pass an array of types.', '3.6.1' );
+                               _doing_it_wrong( "add_theme_support( 'html5' )", __( 'You need to pass an array of types.' ), '3.6.1' );
                                return false;
                        }
 
@@ -1607,6 +1626,17 @@ function add_theme_support( $feature ) {
                                define( 'BACKGROUND_IMAGE', $args[0]['default-image'] );
 
                        break;
+
+               // Ensure that 'title-tag' is accessible in the admin.
+               case 'title-tag' :
+                       // Can be called in functions.php but must happen before wp_loaded, i.e. not in header.php.
+                       if ( did_action( 'wp_loaded' ) ) {
+                               /* translators: 1: Theme support 2: hook name */
+                               _doing_it_wrong( "add_theme_support( 'title-tag' )", sprintf( __( 'Theme support for %1$s should be registered before the %2$s hook.' ),
+                                       '<code>title-tag</code>', '<code>wp_loaded</code>' ), '4.1' );
+
+                               return false;
+                       }
        }
 
        $_wp_theme_features[ $feature ] = $args;
@@ -1648,7 +1678,6 @@ function _custom_header_background_just_in_time() {
                }
        }
 }
-add_action( 'wp_loaded', '_custom_header_background_just_in_time' );
 
 /**
  * Gets the theme support arguments passed when registering that support
@@ -1656,7 +1685,7 @@ add_action( 'wp_loaded', '_custom_header_background_just_in_time' );
  * @since 3.1.0
  *
  * @param string $feature the feature to check
- * @return array The array of extra arguments
+ * @return mixed The array of extra arguments or the value for the registered feature.
  */
 function get_theme_support( $feature ) {
        global $_wp_theme_features;
@@ -1688,7 +1717,7 @@ function get_theme_support( $feature ) {
  * @since 3.0.0
  * @see add_theme_support()
  * @param string $feature the feature being added
- * @return bool Whether feature was removed.
+ * @return null|bool Whether feature was removed.
  */
 function remove_theme_support( $feature ) {
        // Blacklist: for internal registrations not used directly by themes.
@@ -1703,6 +1732,7 @@ function remove_theme_support( $feature ) {
  *
  * @access private
  * @since 3.1.0
+ * @param string $feature
  */
 function _remove_theme_support( $feature ) {
        global $_wp_theme_features;
@@ -1759,6 +1789,14 @@ function current_theme_supports( $feature ) {
        if ( !isset( $_wp_theme_features[$feature] ) )
                return false;
 
+       if ( 'title-tag' == $feature ) {
+               // Don't confirm support unless called internally.
+               $trace = debug_backtrace();
+               if ( ! in_array( $trace[1]['function'], array( '_wp_render_title_tag', 'wp_title' ) ) ) {
+                       return false;
+               }
+       }
+
        // If no args passed then no extra checks need be performed
        if ( func_num_args() <= 1 )
                return true;
@@ -1796,10 +1834,9 @@ function current_theme_supports( $feature ) {
        /**
         * Filter whether the current theme supports a specific feature.
         *
-        * The dynamic portion of the hook name, $feature, refers to
-        * the specific theme feature. Possible values include 'post-formats',
-        * 'post-thumbnails', 'custom-background', 'custom-header', 'menus',
-        * 'automatic-feed-links', and 'html5'.
+        * The dynamic portion of the hook name, `$feature`, refers to the specific theme
+        * feature. Possible values include 'post-formats', 'post-thumbnails', 'custom-background',
+        * 'custom-header', 'menus', 'automatic-feed-links', and 'html5'.
         *
         * @since 3.4.0
         *
@@ -1849,8 +1886,6 @@ function _delete_attachment_theme_mod( $id ) {
                remove_theme_mod( 'background_image' );
 }
 
-add_action( 'delete_attachment', '_delete_attachment_theme_mod' );
-
 /**
  * Checks if a theme has been changed and runs 'after_switch_theme' hook on the next WP load
  *
@@ -1907,7 +1942,6 @@ function _wp_customize_include() {
        // Init Customize class
        $GLOBALS['wp_customize'] = new WP_Customize_Manager;
 }
-add_action( 'plugins_loaded', '_wp_customize_include' );
 
 /**
  * Adds settings for the customize-loader script.
@@ -1931,11 +1965,12 @@ function _wp_customize_loader_settings() {
                'isCrossDomain' => $cross_domain,
                'browser'       => $browser,
                'l10n'          => array(
-                       'saveAlert' => __( 'The changes you made will be lost if you navigate away from this page.' ),
+                       'saveAlert'       => __( 'The changes you made will be lost if you navigate away from this page.' ),
+                       'mainIframeTitle' => __( 'Customizer' ),
                ),
        );
 
-       $script = 'var _wpCustomizeLoaderSettings = ' . json_encode( $settings ) . ';';
+       $script = 'var _wpCustomizeLoaderSettings = ' . wp_json_encode( $settings ) . ';';
 
        $data = $wp_scripts->get_data( 'customize-loader', 'data' );
        if ( $data )
@@ -1943,10 +1978,9 @@ function _wp_customize_loader_settings() {
 
        $wp_scripts->add_data( 'customize-loader', 'data', $script );
 }
-add_action( 'admin_enqueue_scripts', '_wp_customize_loader_settings' );
 
 /**
- * Returns a URL to load the theme customizer.
+ * Returns a URL to load the Customizer.
  *
  * @since 3.4.0
  *
@@ -1961,7 +1995,7 @@ function wp_customize_url( $stylesheet = null ) {
 }
 
 /**
- * Prints a script to check whether or not the customizer is supported,
+ * 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.
  *
@@ -2010,5 +2044,5 @@ function wp_customize_support_script() {
 function is_customize_preview() {
        global $wp_customize;
 
-       return is_a( $wp_customize, 'WP_Customize_Manager' ) && $wp_customize->is_preview();
+       return ( $wp_customize instanceof WP_Customize_Manager ) && $wp_customize->is_preview();
 }