WordPress.org

Make WordPress Core

Changeset 13886


Ignore:
Timestamp:
03/30/10 00:05:17 (4 years ago)
Author:
nacin
Message:

Second pass on twentyten/functions.php inline documentation. see #12695. Also:

rename twentyten_init() to twentyten_setup(), to reflect the hook it is run on (init would be too late, it must be after_setup_theme). Remove unnecessary twentyten_get_page_number() and transfer functionality to twentyten_the_page_number(). Remove the function_exists() wrappers from functions that are simply tied to a hook, as a better practice would be to remove the hook instead of plugging the function. For architecture changes, see #12748.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/wp-content/themes/twentyten/functions.php

    r13885 r13886  
    33 * TwentyTen functions and definitions 
    44 * 
    5  * Sets up the theme and provides some helper functions used 
    6  * in other parts of the theme.  All functions are pluggable 
     5 * Sets up the theme and provides some helper functions. Some helper functions 
     6 * are used in the theme as custom template tags. Others are attached to action and 
     7 * filter hooks in WordPress to change core functionality. 
     8 * 
     9 * The first function, twentyten_setup(), sets up the theme by registering support 
     10 * for various features in WordPress, such as post thumbnails, navigation menus, and the like. 
     11 * 
     12 * When using a child theme (see http://codex.wordpress.org/Theme_Development), you can 
     13 * override certain functions (those wrapped in a function_exists() call) by defining 
     14 * them first in your child theme's functions.php file. The child theme's functions.php 
     15 * file is included before the parent theme's file, so the child theme functions would 
     16 * be used. 
     17 * 
     18 * Functions that are not pluggable (not wrapped in function_exists()) are instead attached 
     19 * to a filter or action hook. The hook can be removed by using remove_action() or 
     20 * remove_filter() and you can attach your own function to the hook. For example: 
     21 * 
     22 * <code> 
     23 * remove_action( 'after_setup_theme', 'twentyten_setup' ); 
     24 * add_action( 'after_setup_theme', 'my_child_theme_setup' ); 
     25 * function my_child_theme_setup() { 
     26 *  ... 
     27 * } 
     28 * </code> 
     29 * 
     30 * For more information on hooks, see http://codex.wordpress.org/Plugin_API. 
    731 * 
    832 * @package WordPress 
     
    1236 
    1337/** 
    14  * Set the content width based on the Theme CSS.  Can be overriden 
    15  * 
    16  * Used in attachment.php to set the width of images.  Should 
    17  * be equal to the width set for .onecolumn #content in style.css 
     38 * Set the content width based on the theme's design and stylesheet. 
     39 * 
     40 * Used to set the width of images and content. Should be equal to the width the theme 
     41 * is designed for, generally via the style.css stylesheet. 
    1842 */ 
    1943if ( ! isset( $content_width ) ) 
    2044    $content_width = 640; 
    2145 
    22 if ( ! function_exists( 'twentyten_init' ) ) : 
    23 /** 
    24  * Set up defaults for our theme. 
    25  * 
    26  * Sets up theme defaults and tells wordpress that this is a 
    27  * theme that will take advantage of Post Thumbnails, Custom 
    28  * Background, Nav Menus and automatic feed links.  To 
    29  * override any of the settings in a child theme, create your 
    30  * own twentyten_init function 
    31  * 
    32  * @uses add_theme_support() 
    33  */ 
    34 function twentyten_init() { 
    35     // This theme allows users to set a custom background 
    36     add_custom_background(); 
     46/** Tell WordPress to run twentyten_setup() when the 'after_setup_theme' hook is run. */ 
     47add_action( 'after_setup_theme', 'twentyten_setup' ); 
     48 
     49/** 
     50 * Sets up theme defaults and registers support for various WordPress features. 
     51 * 
     52 * Note that this function is hooked into the after_setup_theme hook, which runs 
     53 * before the init hook. The init hook is too late for some features, such as indicating 
     54 * support post thumbnails. 
     55 * 
     56 * To override twentyten_setup() in a child theme, remove the action hook and add your own 
     57 * function tied to the after_setup_theme hook. 
     58 * 
     59 * @uses add_theme_support() To add support for post thumbnails, navigation menus, and automatic feed links. 
     60 * @uses add_custom_background() To add support for a custom background. 
     61 * @uses add_editor_style() To style the visual editor. 
     62 * @uses load_theme_textdomain() For translation/localization support. 
     63 * @uses add_custom_image_header() To add support for a custom header. 
     64 * @uses register_default_headers() To register the default custom header images provided with the theme. 
     65 * @uses set_post_thumbnail_size() To set a custom post thumbnail size. 
     66 * 
     67 * @since 3.0.0 
     68 */ 
     69function twentyten_setup() { 
    3770 
    3871    // This theme styles the visual editor with editor-style.css to match the theme style. 
    3972    add_editor_style(); 
    4073 
    41     // This theme needs post thumbnails 
     74    // This theme uses post thumbnails 
    4275    add_theme_support( 'post-thumbnails' ); 
    4376 
    4477    // This theme uses wp_nav_menu() 
    4578    add_theme_support( 'nav-menus' ); 
    46  
    47     // We'll be using them for custom header images on posts and pages 
    48     // so we want them to be 940 pixels wide by 198 pixels tall (larger images will be auto-cropped to fit) 
    49     set_post_thumbnail_size( HEADER_IMAGE_WIDTH, HEADER_IMAGE_HEIGHT, true ); 
    5079 
    5180    // Add default posts and comments RSS feed links to head 
     
    6190        require_once( $locale_file ); 
    6291 
    63     // Your Changeable header business starts here 
    64     // No CSS, just IMG call 
     92    // This theme allows users to set a custom background 
     93    add_custom_background(); 
     94 
     95    // Your changeable header business starts here 
    6596    define( 'HEADER_TEXTCOLOR', '' ); 
    66     define( 'HEADER_IMAGE', '%s/images/headers/forestfloor.jpg' ); // %s is theme dir uri 
    67  
    68     // Add a filter to twentyten_header_image_width and twentyten_header_image_height to change these values 
     97    // No CSS, just IMG call. The %s is a placeholder for the theme template directory URI. 
     98    define( 'HEADER_IMAGE', '%s/images/headers/forestfloor.jpg' ); 
     99 
     100    // The height and width of your custom header. You can hook into the theme's own filters to change these values. 
     101    // Add a filter to twentyten_header_image_width and twentyten_header_image_height to change these values. 
    69102    define( 'HEADER_IMAGE_WIDTH', apply_filters( 'twentyten_header_image_width',  940 ) ); 
    70103    define( 'HEADER_IMAGE_HEIGHT', apply_filters( 'twentyten_header_image_height',  198 ) ); 
    71104 
     105    // We'll be using post thumbnails for custom header images on posts and pages. 
     106    // We want them to be 940 pixels wide by 198 pixels tall (larger images will be auto-cropped to fit). 
     107    set_post_thumbnail_size( HEADER_IMAGE_WIDTH, HEADER_IMAGE_HEIGHT, true ); 
     108 
     109    // Don't support text inside the header image. 
    72110    define( 'NO_HEADER_TEXT', true ); 
    73111 
     112    // Add a way for the custom header to be styled in the admin panel that controls 
     113    // custom headers. See twentyten_admin_header_style(), below. 
    74114    add_custom_image_header( '', 'twentyten_admin_header_style' ); 
    75     // and thus ends the changeable header business 
    76  
    77     // Default custom headers.  %s is a placeholder for the theme template directory 
    78  
     115 
     116    // ... and thus ends the changeable header business. 
     117 
     118    // Default custom headers packaged with the theme. %s is a placeholder for the theme template directory URI. 
    79119    register_default_headers( array ( 
    80120        'berries' => array ( 
     
    120160    ) ); 
    121161} 
    122 endif; 
    123 add_action( 'after_setup_theme', 'twentyten_init' ); 
    124162 
    125163if ( ! function_exists( 'twentyten_admin_header_style' ) ) : 
    126164/** 
    127  * Callback to style the header image inside the admin 
     165 * Styles the header image displayed on the Appearance > Header admin panel. 
     166 * 
     167 * Referenced via add_custom_image_header() in twentyten_setup(). 
     168 * 
     169 * @since 3.0.0 
    128170 */ 
    129171function twentyten_admin_header_style() { 
     
    142184endif; 
    143185 
    144 if ( ! function_exists( 'twentyten_get_page_number' ) ) : 
    145 /** 
    146  * Returns the page number currently being browsed 
    147  * 
    148  * Returns a vertical bar followed by page and the page 
    149  * number.  Is pluggable 
    150  * 
    151  * @retun string 
    152  */ 
    153 function twentyten_get_page_number() { 
     186if ( ! function_exists( 'twentyten_the_page_number' ) ) : 
     187/** 
     188 * Prints the page number currently being browsed, with a vertical bar before it. 
     189 * 
     190 * Used in Twenty Ten's header.php to add the page number to the <title> HTML tag. 
     191 * 
     192 * @since 3.0.0 
     193 */ 
     194function twentyten_the_page_number() { 
    154195    if ( get_query_var( 'paged' ) ) 
    155         return ' | ' . __( 'Page ' , 'twentyten' ) . get_query_var( 'paged' ); 
    156 } 
    157 endif; 
    158  
    159 if ( ! function_exists( 'twentyten_the_page_number' ) ) : 
    160 /** 
    161  * Echos the page number being browsed 
    162  * 
    163  * @uses twentyten_get_page_number 
    164  * 
    165  */ 
    166 function twentyten_the_page_number() { 
    167     echo twentyten_get_page_number(); 
    168 } 
    169 endif; 
    170  
    171 if ( ! function_exists( 'twentyten_excerpt_length' ) ) : 
    172 /** 
    173  * Sets the excerpt length to 40 charachters.  Is pluggable 
     196        echo ' | ' . __( 'Page ' , 'twentyten' ) . get_query_var( 'paged' ); 
     197} 
     198endif; 
     199 
     200/** 
     201 * Sets the post excerpt length to 40 characters. 
     202 * 
     203 * To override this length in a child theme, remove the filter and add your own 
     204 * function tied to the excerpt_length filter hook. 
    174205 * 
    175206 * @return int 
     
    178209    return 40; 
    179210} 
    180 endif; 
    181211add_filter( 'excerpt_length', 'twentyten_excerpt_length' ); 
    182212 
    183 if ( ! function_exists( 'twentyten_excerpt_more' ) ) : 
    184 /** 
    185  * Sets the read more link for excerpts to something pretty 
    186  * 
    187  * @return string 
    188  * 
     213/** 
     214 * Sets the "read more" link to something pretty. 
     215 * 
     216 * To override this link in a child theme, remove the filter and add your own 
     217 * function tied to the excerpt_more filter hook. 
     218 * 
     219 * @since 3.0.0 
     220 * @return string A pretty 'Continue reading' link. 
    189221 */ 
    190222function twentyten_excerpt_more( $more ) { 
    191223    return '&nbsp;&hellip; <a href="'. get_permalink() . '">' . __('Continue&nbsp;reading&nbsp;<span class="meta-nav">&rarr;</span>', 'twentyten') . '</a>'; 
    192224} 
    193 endif; 
    194225add_filter( 'excerpt_more', 'twentyten_excerpt_more' ); 
    195226 
     227/** 
     228 * Remove inline styles printed when the gallery shortcode is used. 
     229 * 
     230 * Galleries are styled by the theme in Twenty Ten's style.css. 
     231 * 
     232 * @return string The gallery style filter, with the styles themselves removed. 
     233 */ 
     234function twentyten_remove_gallery_css( $css ) { 
     235    return preg_replace( "#<style type='text/css'>(.*?)</style>#s", '', $css ); 
     236} 
     237add_filter( 'gallery_style', 'twentyten_remove_gallery_css' ); 
     238 
    196239if ( ! function_exists( 'twentyten_comment' ) ) : 
    197240/** 
    198  * Template for comments and pingbacks 
    199  * 
    200  * Used as a callback by wp_list_comments for displaying the 
    201  * comments.  Is pluggable 
    202  * 
     241 * Template for comments and pingbacks. 
     242 * 
     243 * To override this walker in a child theme without modifying the comments template 
     244 * simply create your own twentyten_comment(), and that function will be used instead. 
     245 * 
     246 * Used as a callback by wp_list_comments() for displaying the comments. 
     247 * 
     248 * @since 3.0.0 
    203249 */ 
    204250function twentyten_comment( $comment, $args, $depth ) { 
     
    232278endif; 
    233279 
    234 if ( ! function_exists( 'twentyten_remove_gallery_css' ) ) : 
    235 /** 
    236  * Remove inline styles on gallery shortcode 
    237  * 
    238  * @return string 
    239  */ 
    240 function twentyten_remove_gallery_css( $css ) { 
    241     return preg_replace( "#<style type='text/css'>(.*?)</style>#s", '', $css ); 
    242 } 
    243 endif; 
    244 add_filter( 'gallery_style', 'twentyten_remove_gallery_css' ); 
    245  
    246280if ( ! function_exists( 'twentyten_cat_list' ) ) : 
    247281/** 
     
    275309} 
    276310endif; 
     311 
    277312 
    278313if ( ! function_exists( 'twentyten_term_list' ) ) : 
     
    314349endif; 
    315350 
    316 if ( ! function_exists( 'twentyten_widgets_init' ) ) : 
    317 /** 
    318  * Register widgetized areas 
    319  * 
     351/** 
     352 * Register widgetized areas, including two sidebars and four widget-ready columns in the footer. 
     353 * 
     354 * To override twentyten_widgets_init() in a child theme, remove the action hook and add your own 
     355 * function tied to the init hook. 
    320356 * @uses register_sidebar 
    321357 */ 
     
    386422        'after_title' => '</h3>', 
    387423    ) ); 
    388  
    389 } 
    390 endif; 
     424} 
    391425add_action( 'init', 'twentyten_widgets_init' ); 
Note: See TracChangeset for help on using the changeset viewer.