WordPress.org
Get WordPress

Make WordPress Core


Ignore:
Timestamp:
03/19/2012 05:12:44 PM (14 years ago)
Author:
nacin
Message:

Introduce new registration methods for custom headers and custom backgrounds. Backwards compatible, but old methods will be deprecated. see #20249. see #17242.

Custom header: Use add_theme_support('custom-header', $args) instead of add_custom_image_header(). Deprecates all use of constants.

  • HEADER_TEXTCOLOR is now (string) 'default-text-color'.
  • NO_HEADER_TEXT is nowi ! (bool) 'header-text'.
  • HEADER_IMAGE_WIDTH (and _HEIGHT) are now (int) 'width' and 'height'.
  • HEADER_IMAGE is now (string) 'default-image'.
  • The 3.4 arguments 'suggested-width' and 'suggested-height' are now just 'width' and 'height' (they are "suggested" when flex-width and flex-height are set).
  • Callback arguments for add_custom_image_header() can now be passed to add_theme_support().

Custom background: Use add_theme_support('custom-background, $args) instead of add_custom_background(). Deprecates all use of constants.

  • BACKGROUND_COLOR is now (string) 'default-color'.
  • BACKGROUND_IMAGE is now (string) 'default-image'.
  • Callback arguments for add_custom_background() can now be passed to add_theme_support().

Inheritance: add_theme_support() arguments for custom headers and custom backgrounds is a first-one-wins situation. This is not an unusual paradigm for theming as a child theme (which is included first) overrides a parent theme.

  • Once an argument is explicitly set, it cannot be overridden. You must hook in earlier and set it first.
  • Any argument that is not explicitly set before WP is loaded will inherit the default value for that argument.
  • It is therefore possible for a child theme to pass minimal arguments as long as the parent theme specifies others that may be necessary.
  • Allows for a child theme to alter callbacks for <head> and preview (previously, calling add_custom_image_header more than once broke things).
  • The just-in-time bits ensure that arguments fall back to default values, that the values of all constants are considered (such as one defined after an old add_custom_image_header call), and that all constants are defined (so as to be backwards compatible).

get_theme_support(): Introduce new second argument, which headers and backgrounds leverage to return an argument. current_theme_supports() already supported checking the truthiness of the argument.

  • For example, get_theme_support( 'custom-header', 'width' ) will return the width specified during registration.
  • If you had wanted the default image, use get_theme_support( 'custom-header', 'default-image' ) instead of HEADER_IMAGE.

Deprecate remove_custom_image_header(), remove_custom_background(). Use remove_theme_support('custom-header'), 'custom-background'.

Deprecate short-lived custom-header-uploads internal support; this is now (bool) 'uploads' for add_theme_support().

New 3.4 functions renamed or removed: Rename get_current_header_data() to get_custom_header(). Remove get_header_image_width() and _height() in favor of get_custom_header()->width and height.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/wp-includes/theme.php

    r20193 r20212  
    902902 *
    903903 * @since 2.1.0
    904  * @uses HEADER_TEXTCOLOR
    905904 *
    906905 * @return string
    907906 */
    908907function get_header_textcolor() {
    909         $default = defined('HEADER_TEXTCOLOR') ? HEADER_TEXTCOLOR : '';
    910 
    911         return get_theme_mod('header_textcolor', $default);
     908        return get_theme_mod('header_textcolor', get_theme_support( 'custom-header', 'default-text-color' ) );
    912909}
    913910
    … …  
    925922 *
    926923 * @since 2.1.0
    927  * @uses HEADER_IMAGE
    928924 *
    929925 * @return string
    930926 */
    931927function get_header_image() {
    932         $default = defined( 'HEADER_IMAGE' ) ? HEADER_IMAGE : '';
    933         $url = get_theme_mod( 'header_image', $default );
     928        $url = get_theme_mod( 'header_image', get_theme_support( 'custom-header', 'default-image' ) );
    934929
    935930        if ( 'remove-header' == $url )
    … …  
    971966                                $headers = $_wp_default_headers;
    972967                        } else {
    973                                 $is_random = get_theme_support( 'custom-header' );
    974                                 if ( isset( $is_random[ 0 ] ) && !empty( $is_random[ 0 ][ 'random-default' ] ) )
     968                                if ( current_theme_supports( 'custom-header', 'random-default' ) )
    975969                                        $headers = $_wp_default_headers;
    976970                        }
    … …  
    10111005 *
    10121006 * @since 3.2.0
    1013  * @uses HEADER_IMAGE
    10141007 *
    10151008 * @param string $type The random pool to use. any|default|uploaded
    … …  
    10171010 */
    10181011function is_random_header_image( $type = 'any' ) {
    1019         $default = defined( 'HEADER_IMAGE' ) ? HEADER_IMAGE : '';
    1020         $header_image_mod = get_theme_mod( 'header_image', $default );
     1012        $header_image_mod = get_theme_mod( 'header_image', get_theme_support( 'custom-header', 'default-image' ) );
    10211013
    10221014        if ( 'any' == $type ) {
    … …  
    10801072 * @return object
    10811073 */
    1082 function get_current_header_data() {
     1074function get_custom_header() {
    10831075        $data = is_random_header_image()? _get_random_header_data() : get_theme_mod( 'header_image_data' );
    10841076        $default = array(
    10851077                'url'           => '',
    10861078                'thumbnail_url' => '',
    1087                 'width'         => '',
    1088                 'height'        => '',
     1079                'width'         => get_theme_suppport( 'custom-header', 'width' ),
     1080                'height'        => get_theme_suppport( 'custom-header', 'height' ),
    10891081        );
    10901082        return (object) wp_parse_args( $data, $default );
    … …  
    10921084
    10931085/**
    1094  * Get the header image width.
    1095  *
    1096  * @since 3.4.0
    1097  *
    1098  * @return int
    1099  */
    1100 function get_header_image_width() {
    1101         return empty( get_current_header_data()->width )? HEADER_IMAGE_WIDTH : get_current_header_data()->width;
    1102 }
    1103 
    1104 /**
    1105  * Get the header image height.
    1106  *
    1107  * @since 3.4.0
    1108  *
    1109  * @return int
    1110  */
    1111 function get_header_image_height() {
    1112         return empty( get_current_header_data()->height )? HEADER_IMAGE_HEIGHT : get_current_header_data()->height;
    1113 }
    1114 
    1115 /**
    11161086 * Add callbacks for image header display.
    11171087 *
    1118  * The parameter $header_callback callback will be required to display the
    1119  * content for the 'wp_head' action. The parameter $admin_header_callback
    1120  * callback will be added to Custom_Image_Header class and that will be added
    1121  * to the 'admin_menu' action.
    1122  *
    11231088 * @since 2.1.0
    1124  * @uses Custom_Image_Header Sets up for $admin_header_callback for administration panel display.
     1089 * @deprecated 3.4.0
     1090 * @deprecated Use add_theme_support('custom-header', $args)
     1091 * @see add_theme_support()
    11251092 *
    11261093 * @param callback $header_callback Call on 'wp_head' action.
    … …  
    11291096 */
    11301097function add_custom_image_header( $header_callback, $admin_header_callback, $admin_image_div_callback = '' ) {
    1131         if ( ! empty( $header_callback ) )
    1132                 add_action('wp_head', $header_callback);
    1133 
    1134         $support = array( 'callback' => $header_callback );
    1135         $theme_support = get_theme_support( 'custom-header' );
    1136         if ( ! empty( $theme_support ) && is_array( $theme_support[ 0 ] ) )
    1137                 $support = array_merge( $theme_support[ 0 ], $support );
    1138         add_theme_support( 'custom-header',  $support );
    1139         add_theme_support( 'custom-header-uploads' );
    1140 
    1141         if ( ! is_admin() )
    1142                 return;
    1143 
    1144         global $custom_image_header;
    1145 
    1146         require_once( ABSPATH . 'wp-admin/custom-header.php' );
    1147         $custom_image_header = new Custom_Image_Header( $admin_header_callback, $admin_image_div_callback );
    1148         add_action( 'admin_menu', array( &$custom_image_header, 'init' ) );
     1098        # _deprecated_function( __FUNCTION__, '3.4', 'add_theme_support(\'custom-header\', $args)' );
     1099        return add_theme_support( 'custom-header', array(
     1100                'callback' => $header_callback,
     1101                'admin-header-callback' => $admin_header_callback,
     1102                'admin-image-div-callback' => $admin_image_div_callback,
     1103        ) );
    11491104}
    11501105
    … …  
    11531108 *
    11541109 * @since 3.1.0
    1155  * @see add_custom_image_header()
     1110 * @deprecated 3.4.0
     1111 * @deprecated Use remove_theme_support('custom-header')
     1112 * @see remove_theme_support()
    11561113 *
    11571114 * @return bool Whether support was removed.
    11581115 */
    11591116function remove_custom_image_header() {
    1160         if ( ! current_theme_supports( 'custom-header' ) )
    1161                 return false;
    1162 
    1163         $callback = get_theme_support( 'custom-header' );
    1164         remove_action( 'wp_head', $callback[0]['callback'] );
    1165         _remove_theme_support( 'custom-header' );
    1166         remove_theme_support( 'custom-header-uploads' );
    1167 
    1168         if ( is_admin() ) {
    1169                 remove_action( 'admin_menu', array( &$GLOBALS['custom_image_header'], 'init' ) );
    1170                 unset( $GLOBALS['custom_image_header'] );
    1171         }
    1172 
    1173         return true;
     1117        # _deprecated_function( __FUNCTION__, '3.4', 'remove_theme_support(\'custom-header\')' );
     1118        return remove_theme_support( 'custom-header' );
    11741119}
    11751120
    … …  
    12191164 */
    12201165function get_background_image() {
    1221         $default = defined('BACKGROUND_IMAGE') ? BACKGROUND_IMAGE : '';
    1222 
    1223         return get_theme_mod('background_image', $default);
     1166        return get_theme_mod('background_image', get_theme_support( 'custom-background', 'default-image' ) );
    12241167}
    12251168
    … …  
    12371180 *
    12381181 * @since 3.0.0
    1239  * @uses BACKGROUND_COLOR
    12401182 *
    12411183 * @return string
    12421184 */
    12431185function get_background_color() {
    1244         $default = defined('BACKGROUND_COLOR') ? BACKGROUND_COLOR : '';
    1245 
    1246         return get_theme_mod('background_color', $default);
     1186        return get_theme_mod('background_color', get_theme_support( 'custom-background', 'default-color' ) );
    12471187}
    12481188
    … …  
    12721212 */
    12731213function add_custom_background( $header_callback = '', $admin_header_callback = '', $admin_image_div_callback = '' ) {
    1274         if ( isset( $GLOBALS['custom_background'] ) )
    1275                 return;
    1276 
    1277         if ( empty( $header_callback ) )
    1278                 $header_callback = '_custom_background_cb';
    1279 
    1280         add_action( 'wp_head', $header_callback );
    1281 
    1282         add_theme_support( 'custom-background', array( 'callback' => $header_callback ) );
    1283 
    1284         if ( ! is_admin() )
    1285                 return;
    1286         require_once( ABSPATH . 'wp-admin/custom-background.php' );
    1287         $GLOBALS['custom_background'] = new Custom_Background( $admin_header_callback, $admin_image_div_callback );
    1288         add_action( 'admin_menu', array( &$GLOBALS['custom_background'], 'init' ) );
     1214        # _deprecated_function( __FUNCTION__, '3.4', 'add_theme_support(\'custom-background\', $args)' );
     1215        return add_theme_support( 'custom-background', array(
     1216                'callback' => $header_callback,
     1217                'admin-header-callback' => $admin_header_callback,
     1218                'admin-image-div-callback' => $admin_image_div_callback,
     1219        ) );
    12891220}
    12901221
    … …  
    12981229 */
    12991230function remove_custom_background() {
    1300         if ( ! current_theme_supports( 'custom-background' ) )
    1301                 return false;
    1302 
    1303         $callback = get_theme_support( 'custom-background' );
    1304         remove_action( 'wp_head', $callback[0]['callback'] );
    1305         _remove_theme_support( 'custom-background' );
    1306 
    1307         if ( is_admin() ) {
    1308                 remove_action( 'admin_menu', array( &$GLOBALS['custom_background'], 'init' ) );
    1309                 unset( $GLOBALS['custom_background'] );
    1310         }
    1311 
    1312         return true;
     1231        # _deprecated_function( __FUNCTION__, '3.4', 'remove_theme_support(\'custom-background\')' );
     1232        return remove_theme_support( 'custom-background' );
    13131233}
    13141234
    … …  
    13171237 *
    13181238 * @since 3.0.0
    1319  * @see add_custom_background()
    13201239 * @access protected
    13211240 */
    … …  
    14231342
    14241343        if ( func_num_args() == 1 )
    1425                 $_wp_theme_features[$feature] = true;
     1344                $args = true;
    14261345        else
    1427                 $_wp_theme_features[$feature] = array_slice( func_get_args(), 1 );
    1428 
    1429         if ( $feature == 'post-formats' && is_array( $_wp_theme_features[$feature][0] ) )
    1430                 $_wp_theme_features[$feature][0] = array_intersect( $_wp_theme_features[$feature][0], array_keys( get_post_format_slugs() ) );
    1431 }
     1346                $args = array_slice( func_get_args(), 1 );
     1347
     1348        switch ( $feature ) {
     1349                case 'post-formats' :
     1350                        if ( is_array( $args[0] ) )
     1351                                $args[0] = array_intersect( $args[0], array_keys( get_post_format_slugs() ) );
     1352                        break;
     1353
     1354                case 'custom-header-uploads' :
     1355                        return add_theme_support( 'custom-header', array( 'uploads' => true ) );
     1356                        break;
     1357
     1358                case 'custom-header' :
     1359                        $defaults = array(
     1360                                'default-image' => '',
     1361                                'random-default' => false,
     1362                                'width' => 0,
     1363                                'height' => 0,
     1364                                'flex-height' => false,
     1365                                'flex-width' => false,
     1366                                'default-text-color' => '',
     1367                                'header-text' => true,
     1368                                'uploads' => true,
     1369                                'callback' => '',
     1370                                'admin-header-callback' => '',
     1371                                'admin-image-div-callback' => '',
     1372                        );
     1373
     1374                        $jit = isset( $args[0]['__jit'] );
     1375                        unset( $args[0]['__jit'] );
     1376
     1377                        // Merge in data from previous add_theme_support() calls.
     1378                        // The first value registered wins. (A child theme is set up first.)
     1379                        if ( isset( $_wp_theme_features['custom-header'] ) )
     1380                                $args[0] = wp_parse_args( $_wp_theme_features['custom-header'][0], $args[0] );
     1381
     1382                        // Load in the defaults at the end, as we need to insure first one wins.
     1383                        // This will cause all constants to be defined, as each arg will then be set to the default.
     1384                        if ( $jit )
     1385                                $args[0] = wp_parse_args( $args[0], $defaults );
     1386
     1387                        // If a constant was defined, use that value. Otherwise, define the constant to ensure
     1388                        // the constant is always accurate (and is not defined later,  overriding our value).
     1389                        // As stated above, the first value wins.
     1390                        // Once we get to wp_loaded (just-in-time), define any constants we haven't already.
     1391                        // Constants are lame. Don't reference them. This is just for backwards compatibility.
     1392
     1393                        if ( defined( 'NO_HEADER_TEXT' ) )
     1394                                $args[0]['header-text'] = ! NO_HEADER_TEXT;
     1395                        elseif ( isset( $args[0]['header-text'] ) )
     1396                                define( 'NO_HEADER_TEXT', empty( $args[0]['header-text'] ) );
     1397
     1398                        if ( defined( 'HEADER_IMAGE_WIDTH' ) )
     1399                                $args[0]['width'] = (int) HEADER_IMAGE_WIDTH;
     1400                        elseif ( isset( $args[0]['width'] ) )
     1401                                define( 'HEADER_IMAGE_WIDTH', (int) $args[0]['width'] );
     1402
     1403                        if ( defined( 'HEADER_IMAGE_HEIGHT' ) )
     1404                                $args[0]['height'] = (int) HEADER_IMAGE_HEIGHT;
     1405                        elseif ( ! isset( $args[0]['height'] ) )
     1406                                define( 'HEADER_IMAGE_HEIGHT', (int) $args[0]['height'] );
     1407
     1408                        if ( defined( 'HEADER_TEXTCOLOR' ) )
     1409                                $args[0]['default-text-color'] = HEADER_TEXTCOLOR;
     1410                        elseif ( isset( $args[0]['default-text-color'] ) )
     1411                                define( 'HEADER_TEXTCOLOR', $args[0]['default-text-color'] );
     1412
     1413                        if ( defined( 'HEADER_IMAGE' ) )
     1414                                $args[0]['default-image'] = HEADER_IMAGE;
     1415
     1416                        if ( $jit && ! empty( $args[0]['default-image'] ) )
     1417                                $args[0]['random-default'] = false;
     1418
     1419                        if ( ! defined( 'HEADER_IMAGE' ) && ( isset( $args[0]['default-image'] ) || isset( $args[0]['random-default'] ) ) )
     1420                                define( 'HEADER_IMAGE', $args[0]['default-image'] );
     1421
     1422                        // If headers are supported, and we still don't have a defined width or height,
     1423                        // we have implicit flex sizes.
     1424                        if ( $jit ) {
     1425                                if ( empty( $args[0]['width'] ) && empty( $args[0]['flex-width'] ) )
     1426                                        $args[0]['flex-width'] = true;
     1427                                if ( empty( $args[0]['height'] ) && empty( $args[0]['flex-height'] ) )
     1428                                        $args[0]['flex-height'] = true;
     1429                        }
     1430
     1431                        break;
     1432
     1433                case 'custom-background' :
     1434                        $defaults = array(
     1435                                'default-image' => '',
     1436                                'default-color' => '',
     1437                                'callback' => '',
     1438                                'admin-header-callback' => '',
     1439                                'admin-image-div-callback' => '',
     1440                        );
     1441
     1442                        $jit = isset( $args[0]['__jit'] );
     1443                        unset( $args[0]['__jit'] );
     1444
     1445                        // Merge in data from previous add_theme_support() calls. The first value registered wins.
     1446                        if ( isset( $_wp_theme_features['custom-background'] ) )
     1447                                $args[0] = wp_parse_args( $_wp_theme_features['custom-background'][0], $args[0] );
     1448
     1449                        if ( $jit )
     1450                                $args[0] = wp_parse_args( $args[0], $defaults );
     1451
     1452                        if ( defined( 'BACKGROUND_COLOR' ) )
     1453                                $args[0]['default-color'] = BACKGROUND_COLOR;
     1454                        elseif ( isset( $args[0]['default-color'] ) || $jit )
     1455                                define( 'BACKGROUND_COLOR', $args[0]['default-color'] );
     1456
     1457                        if ( defined( 'BACKGROUND_IMAGE' ) )
     1458                                $args[0]['default-image'] = BACKGROUND_IMAGE;
     1459                        elseif ( isset( $args[0]['default-image'] ) || $jit )
     1460                                define( 'BACKGROUND_IMAGE', $args[0]['default-image'] );
     1461
     1462                        if ( empty( $args[0]['callback'] ) )
     1463                                $args[0]['callback'] = '_custom_background_cb';
     1464
     1465                        break;
     1466        }
     1467
     1468        $_wp_theme_features[ $feature ] = $args;
     1469}
     1470
     1471/**
     1472 * Registers the internal custom header and background routines.
     1473 *
     1474 * @since 3.4.0
     1475 * @access private
     1476 */
     1477function _custom_header_background_just_in_time() {
     1478        global $custom_image_header, $custom_background;
     1479
     1480        if ( current_theme_supports( 'custom-header' ) ) {
     1481                // In case any constants were defined after an add_custom_image_header() call, re-run.
     1482                add_theme_support( 'custom-header', array( '__jit' => true ) );
     1483
     1484                $args = get_theme_support( 'custom-header' );
     1485                if ( $args[0]['callback'] )
     1486                        add_action( 'wp_head', $args[0]['callback'] );
     1487
     1488                if ( is_admin() ) {
     1489                        require_once( ABSPATH . 'wp-admin/custom-header.php' );
     1490                        $custom_image_header = new Custom_Image_Header( $args[0]['admin-header-callback'], $args[0]['admin-image-div-callback'] );
     1491                }
     1492        }
     1493
     1494        if ( current_theme_supports( 'custom-background' ) ) {
     1495                // In case any constants were defined after an add_custom_background() call, re-run.
     1496                add_theme_support( 'custom-background', array( '__jit' => true ) );
     1497
     1498                $args = get_theme_support( 'custom-background' );
     1499                add_action( 'wp_head', $args[0]['callback'] );
     1500
     1501                if ( is_admin() ) {
     1502                        require_once( ABSPATH . 'wp-admin/custom-background.php' );
     1503                        $custom_background = new Custom_Background( $args[0]['admin-header-callback'], $args[0]['admin-image-div-callback'] );
     1504                }
     1505        }               
     1506}
     1507add_action( 'wp_loaded', '_custom_header_background_just_in_time' );
    14321508
    14331509/**
    … …  
    14401516function get_theme_support( $feature ) {
    14411517        global $_wp_theme_features;
    1442         if ( !isset( $_wp_theme_features[$feature] ) )
     1518        if ( ! isset( $_wp_theme_features[ $feature ] ) )
    14431519                return false;
    1444         else
    1445                 return $_wp_theme_features[$feature];
     1520
     1521        if ( func_num_args() <= 1 )
     1522                return $_wp_theme_features[ $feature ];
     1523
     1524        $args = array_slice( func_get_args(), 1 );
     1525        switch ( $feature ) {
     1526                case 'custom-header' :
     1527                case 'custom-background' :
     1528                        if ( isset( $_wp_theme_features[ $feature ][0][ $args[0] ] ) )
     1529                                return $_wp_theme_features[ $feature ][0][ $args[0] ];
     1530                        return false;
     1531                        break;
     1532                default :
     1533                        return $_wp_theme_features[ $feature ];
     1534                        break;
     1535        }
    14461536}
    14471537
    … …  
    14591549function remove_theme_support( $feature ) {
    14601550        // Blacklist: for internal registrations not used directly by themes.
    1461         if ( in_array( $feature, array( 'custom-background', 'custom-header', 'editor-style', 'widgets', 'menus' ) ) )
     1551        if ( in_array( $feature, array( 'editor-style', 'widgets', 'menus' ) ) )
    14621552                return false;
     1553
    14631554        return _remove_theme_support( $feature );
    14641555}
    … …  
    14731564        global $_wp_theme_features;
    14741565
    1475         if ( ! isset( $_wp_theme_features[$feature] ) )
     1566        switch ( $feature ) {
     1567                case 'custom-header-uploads' :
     1568                        if ( ! isset( $_wp_theme_features['custom-header'] ) )
     1569                                return false;
     1570                        add_theme_support( 'custom-header', array( 'uploads' => false ) );
     1571                        return; // Do not continue - custom-header-uploads no longer exists.
     1572        }
     1573
     1574        if ( ! isset( $_wp_theme_features[ $feature ] ) )
    14761575                return false;
    1477         unset( $_wp_theme_features[$feature] );
     1576
     1577        switch ( $feature ) {
     1578                case 'custom-header' :
     1579                        $support = get_theme_support( 'custom-header' );
     1580                        if ( $support[0]['callback'] )
     1581                                remove_action( 'wp_head', $support[0]['callback'] );
     1582                        remove_action( 'admin_menu', array( $GLOBALS['custom_image_header'], 'init' ) );
     1583                        unset( $GLOBALS['custom_image_header'] );
     1584                        break;
     1585
     1586                case 'custom-header' :
     1587                        $support = get_theme_support( 'custom-background' );
     1588                        remove_action( 'wp_head', $support[0]['callback'] );
     1589                        remove_action( 'admin_menu', array( $GLOBALS['custom_background'], 'init' ) );
     1590                        unset( $GLOBALS['custom_background'] );
     1591                        break;
     1592        }
     1593
     1594        unset( $_wp_theme_features[ $feature ] );
    14781595        return true;
    14791596}
    … …  
    14881605function current_theme_supports( $feature ) {
    14891606        global $_wp_theme_features;
     1607
     1608        if ( 'custom-header-uploads' == $feature )
     1609                return current_theme_supports( 'custom-header', 'uploads' );
    14901610
    14911611        if ( !isset( $_wp_theme_features[$feature] ) )
Note: See TracChangeset for help on using the changeset viewer.