add_theme_support

Registers theme support for a given feature.

Description

(void|bool) add_theme_support( (string) $feature ); 

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

Returns (void|bool)

False on failure, void otherwise.

Parameters (1)

0. $feature (string)
The feature being added. Likely core values include post-formats,, post-thumbnails, html5, custom-logo, custom-header-uploads, custom-header, custom-background, title-tag, etc.

Usage

  1. if ( !function_exists( 'add_theme_support' ) ) { 
  2. require_once ABSPATH . WPINC . '/theme.php'; 
  3. $feature = ''; 
  4.  
  5. // NOTICE! Understand what this does before running. 
  6. $result = add_theme_support($feature); 
  7.  

Defined (1)

The function is defined in the following location(s).

/wp-includes/theme.php  
  1. function add_theme_support( $feature ) { 
  2. global $_wp_theme_features; 
  3.  
  4. if ( func_num_args() == 1 ) 
  5. $args = true; 
  6. else 
  7. $args = array_slice( func_get_args(), 1 ); 
  8.  
  9. switch ( $feature ) { 
  10. case 'post-thumbnails': 
  11. // All post types are already supported. 
  12. if ( true === get_theme_support( 'post-thumbnails' ) ) { 
  13. return; 
  14.  
  15. /** 
  16. * Merge post types with any that already declared their support 
  17. * for post thumbnails. 
  18. */ 
  19. if ( is_array( $args[0] ) && isset( $_wp_theme_features['post-thumbnails'] ) ) { 
  20. $args[0] = array_unique( array_merge( $_wp_theme_features['post-thumbnails'][0], $args[0] ) ); 
  21.  
  22. break; 
  23.  
  24. case 'post-formats' : 
  25. if ( is_array( $args[0] ) ) { 
  26. $post_formats = get_post_format_slugs(); 
  27. unset( $post_formats['standard'] ); 
  28.  
  29. $args[0] = array_intersect( $args[0], array_keys( $post_formats ) ); 
  30. break; 
  31.  
  32. case 'html5' : 
  33. // You can't just pass 'html5', you need to pass an array of types. 
  34. if ( empty( $args[0] ) ) { 
  35. // Build an array of types for back-compat. 
  36. $args = array( 0 => array( 'comment-list', 'comment-form', 'search-form' ) ); 
  37. } elseif ( ! is_array( $args[0] ) ) { 
  38. _doing_it_wrong( "add_theme_support( 'html5' )", __( 'You need to pass an array of types.' ), '3.6.1' ); 
  39. return false; 
  40.  
  41. // Calling 'html5' again merges, rather than overwrites. 
  42. if ( isset( $_wp_theme_features['html5'] ) ) 
  43. $args[0] = array_merge( $_wp_theme_features['html5'][0], $args[0] ); 
  44. break; 
  45.  
  46. case 'custom-logo': 
  47. if ( ! is_array( $args ) ) { 
  48. $args = array( 0 => array() ); 
  49. $defaults = array( 
  50. 'width' => null,  
  51. 'height' => null,  
  52. 'flex-width' => false,  
  53. 'flex-height' => false,  
  54. 'header-text' => '',  
  55. ); 
  56. $args[0] = wp_parse_args( array_intersect_key( $args[0], $defaults ), $defaults ); 
  57.  
  58. // Allow full flexibility if no size is specified. 
  59. if ( is_null( $args[0]['width'] ) && is_null( $args[0]['height'] ) ) { 
  60. $args[0]['flex-width'] = true; 
  61. $args[0]['flex-height'] = true; 
  62. break; 
  63.  
  64. case 'custom-header-uploads' : 
  65. return add_theme_support( 'custom-header', array( 'uploads' => true ) ); 
  66.  
  67. case 'custom-header' : 
  68. if ( ! is_array( $args ) ) 
  69. $args = array( 0 => array() ); 
  70.  
  71. $defaults = array( 
  72. 'default-image' => '',  
  73. 'random-default' => false,  
  74. 'width' => 0,  
  75. 'height' => 0,  
  76. 'flex-height' => false,  
  77. 'flex-width' => false,  
  78. 'default-text-color' => '',  
  79. 'header-text' => true,  
  80. 'uploads' => true,  
  81. 'wp-head-callback' => '',  
  82. 'admin-head-callback' => '',  
  83. 'admin-preview-callback' => '',  
  84. ); 
  85.  
  86. $jit = isset( $args[0]['__jit'] ); 
  87. unset( $args[0]['__jit'] ); 
  88.  
  89. // Merge in data from previous add_theme_support() calls. 
  90. // The first value registered wins. (A child theme is set up first.) 
  91. if ( isset( $_wp_theme_features['custom-header'] ) ) 
  92. $args[0] = wp_parse_args( $_wp_theme_features['custom-header'][0], $args[0] ); 
  93.  
  94. // Load in the defaults at the end, as we need to insure first one wins. 
  95. // This will cause all constants to be defined, as each arg will then be set to the default. 
  96. if ( $jit ) 
  97. $args[0] = wp_parse_args( $args[0], $defaults ); 
  98.  
  99. // If a constant was defined, use that value. Otherwise, define the constant to ensure 
  100. // the constant is always accurate (and is not defined later, overriding our value). 
  101. // As stated above, the first value wins. 
  102. // Once we get to wp_loaded (just-in-time), define any constants we haven't already. 
  103. // Constants are lame. Don't reference them. This is just for backward compatibility. 
  104.  
  105. if ( defined( 'NO_HEADER_TEXT' ) ) 
  106. $args[0]['header-text'] = ! NO_HEADER_TEXT
  107. elseif ( isset( $args[0]['header-text'] ) ) 
  108. define( 'NO_HEADER_TEXT', empty( $args[0]['header-text'] ) ); 
  109.  
  110. if ( defined( 'HEADER_IMAGE_WIDTH' ) ) 
  111. $args[0]['width'] = (int) HEADER_IMAGE_WIDTH
  112. elseif ( isset( $args[0]['width'] ) ) 
  113. define( 'HEADER_IMAGE_WIDTH', (int) $args[0]['width'] ); 
  114.  
  115. if ( defined( 'HEADER_IMAGE_HEIGHT' ) ) 
  116. $args[0]['height'] = (int) HEADER_IMAGE_HEIGHT
  117. elseif ( isset( $args[0]['height'] ) ) 
  118. define( 'HEADER_IMAGE_HEIGHT', (int) $args[0]['height'] ); 
  119.  
  120. if ( defined( 'HEADER_TEXTCOLOR' ) ) 
  121. $args[0]['default-text-color'] = HEADER_TEXTCOLOR
  122. elseif ( isset( $args[0]['default-text-color'] ) ) 
  123. define( 'HEADER_TEXTCOLOR', $args[0]['default-text-color'] ); 
  124.  
  125. if ( defined( 'HEADER_IMAGE' ) ) 
  126. $args[0]['default-image'] = HEADER_IMAGE
  127. elseif ( isset( $args[0]['default-image'] ) ) 
  128. define( 'HEADER_IMAGE', $args[0]['default-image'] ); 
  129.  
  130. if ( $jit && ! empty( $args[0]['default-image'] ) ) 
  131. $args[0]['random-default'] = false; 
  132.  
  133. // If headers are supported, and we still don't have a defined width or height,  
  134. // we have implicit flex sizes. 
  135. if ( $jit ) { 
  136. if ( empty( $args[0]['width'] ) && empty( $args[0]['flex-width'] ) ) 
  137. $args[0]['flex-width'] = true; 
  138. if ( empty( $args[0]['height'] ) && empty( $args[0]['flex-height'] ) ) 
  139. $args[0]['flex-height'] = true; 
  140.  
  141. break; 
  142.  
  143. case 'custom-background' : 
  144. if ( ! is_array( $args ) ) 
  145. $args = array( 0 => array() ); 
  146.  
  147. $defaults = array( 
  148. 'default-image' => '',  
  149. 'default-repeat' => 'repeat',  
  150. 'default-position-x' => 'left',  
  151. 'default-attachment' => 'scroll',  
  152. 'default-color' => '',  
  153. 'wp-head-callback' => '_custom_background_cb',  
  154. 'admin-head-callback' => '',  
  155. 'admin-preview-callback' => '',  
  156. ); 
  157.  
  158. $jit = isset( $args[0]['__jit'] ); 
  159. unset( $args[0]['__jit'] ); 
  160.  
  161. // Merge in data from previous add_theme_support() calls. The first value registered wins. 
  162. if ( isset( $_wp_theme_features['custom-background'] ) ) 
  163. $args[0] = wp_parse_args( $_wp_theme_features['custom-background'][0], $args[0] ); 
  164.  
  165. if ( $jit ) 
  166. $args[0] = wp_parse_args( $args[0], $defaults ); 
  167.  
  168. if ( defined( 'BACKGROUND_COLOR' ) ) 
  169. $args[0]['default-color'] = BACKGROUND_COLOR
  170. elseif ( isset( $args[0]['default-color'] ) || $jit ) 
  171. define( 'BACKGROUND_COLOR', $args[0]['default-color'] ); 
  172.  
  173. if ( defined( 'BACKGROUND_IMAGE' ) ) 
  174. $args[0]['default-image'] = BACKGROUND_IMAGE
  175. elseif ( isset( $args[0]['default-image'] ) || $jit ) 
  176. define( 'BACKGROUND_IMAGE', $args[0]['default-image'] ); 
  177.  
  178. break; 
  179.  
  180. // Ensure that 'title-tag' is accessible in the admin. 
  181. case 'title-tag' : 
  182. // Can be called in functions.php but must happen before wp_loaded, i.e. not in header.php. 
  183. if ( did_action( 'wp_loaded' ) ) { 
  184. /** translators: 1: Theme support 2: hook name */ 
  185. _doing_it_wrong( "add_theme_support( 'title-tag' )", sprintf( __( 'Theme support for %1$s should be registered before the %2$s hook.' ),  
  186. '<code>title-tag</code>', '<code>wp_loaded</code>' ), '4.1.0' ); 
  187.  
  188. return false; 
  189.  
  190. $_wp_theme_features[ $feature ] = $args;