WordPress.org
Get WordPress

Make WordPress Core


Ignore:
Timestamp:
03/19/2012 05:12:44 PM (13 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.