From fab0607ee4a0b322d1589816e66a81c4110ba9ed Mon Sep 17 00:00:00 2001 From: nacin Date: Tue, 30 Mar 2010 00:05:17 +0000 Subject: [PATCH] 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. git-svn-id: http://svn.automattic.com/wordpress/trunk@13886 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-content/themes/twentyten/functions.php | 186 +++++++++++++--------- 1 file changed, 110 insertions(+), 76 deletions(-) diff --git a/wp-content/themes/twentyten/functions.php b/wp-content/themes/twentyten/functions.php index b14bc26033..db08b0b215 100644 --- a/wp-content/themes/twentyten/functions.php +++ b/wp-content/themes/twentyten/functions.php @@ -2,8 +2,32 @@ /** * TwentyTen functions and definitions * - * Sets up the theme and provides some helper functions used - * in other parts of the theme. All functions are pluggable + * Sets up the theme and provides some helper functions. Some helper functions + * are used in the theme as custom template tags. Others are attached to action and + * filter hooks in WordPress to change core functionality. + * + * The first function, twentyten_setup(), sets up the theme by registering support + * for various features in WordPress, such as post thumbnails, navigation menus, and the like. + * + * When using a child theme (see http://codex.wordpress.org/Theme_Development), you can + * override certain functions (those wrapped in a function_exists() call) by defining + * them first in your child theme's functions.php file. The child theme's functions.php + * file is included before the parent theme's file, so the child theme functions would + * be used. + * + * Functions that are not pluggable (not wrapped in function_exists()) are instead attached + * to a filter or action hook. The hook can be removed by using remove_action() or + * remove_filter() and you can attach your own function to the hook. For example: + * + * + * remove_action( 'after_setup_theme', 'twentyten_setup' ); + * add_action( 'after_setup_theme', 'my_child_theme_setup' ); + * function my_child_theme_setup() { + * ... + * } + * + * + * For more information on hooks, see http://codex.wordpress.org/Plugin_API. * * @package WordPress * @subpackage Twenty Ten @@ -11,43 +35,48 @@ */ /** - * Set the content width based on the Theme CSS. Can be overriden + * Set the content width based on the theme's design and stylesheet. * - * Used in attachment.php to set the width of images. Should - * be equal to the width set for .onecolumn #content in style.css + * Used to set the width of images and content. Should be equal to the width the theme + * is designed for, generally via the style.css stylesheet. */ if ( ! isset( $content_width ) ) $content_width = 640; -if ( ! function_exists( 'twentyten_init' ) ) : +/** Tell WordPress to run twentyten_setup() when the 'after_setup_theme' hook is run. */ +add_action( 'after_setup_theme', 'twentyten_setup' ); + /** - * Set up defaults for our theme. + * Sets up theme defaults and registers support for various WordPress features. * - * Sets up theme defaults and tells wordpress that this is a - * theme that will take advantage of Post Thumbnails, Custom - * Background, Nav Menus and automatic feed links. To - * override any of the settings in a child theme, create your - * own twentyten_init function + * Note that this function is hooked into the after_setup_theme hook, which runs + * before the init hook. The init hook is too late for some features, such as indicating + * support post thumbnails. * - * @uses add_theme_support() + * To override twentyten_setup() in a child theme, remove the action hook and add your own + * function tied to the after_setup_theme hook. + * + * @uses add_theme_support() To add support for post thumbnails, navigation menus, and automatic feed links. + * @uses add_custom_background() To add support for a custom background. + * @uses add_editor_style() To style the visual editor. + * @uses load_theme_textdomain() For translation/localization support. + * @uses add_custom_image_header() To add support for a custom header. + * @uses register_default_headers() To register the default custom header images provided with the theme. + * @uses set_post_thumbnail_size() To set a custom post thumbnail size. + * + * @since 3.0.0 */ -function twentyten_init() { - // This theme allows users to set a custom background - add_custom_background(); +function twentyten_setup() { // This theme styles the visual editor with editor-style.css to match the theme style. add_editor_style(); - // This theme needs post thumbnails + // This theme uses post thumbnails add_theme_support( 'post-thumbnails' ); // This theme uses wp_nav_menu() add_theme_support( 'nav-menus' ); - // We'll be using them for custom header images on posts and pages - // so we want them to be 940 pixels wide by 198 pixels tall (larger images will be auto-cropped to fit) - set_post_thumbnail_size( HEADER_IMAGE_WIDTH, HEADER_IMAGE_HEIGHT, true ); - // Add default posts and comments RSS feed links to head add_theme_support( 'automatic-feed-links' ); @@ -60,22 +89,33 @@ function twentyten_init() { if ( is_readable( $locale_file ) ) require_once( $locale_file ); - // Your Changeable header business starts here - // No CSS, just IMG call - define( 'HEADER_TEXTCOLOR', '' ); - define( 'HEADER_IMAGE', '%s/images/headers/forestfloor.jpg' ); // %s is theme dir uri + // This theme allows users to set a custom background + add_custom_background(); - // Add a filter to twentyten_header_image_width and twentyten_header_image_height to change these values + // Your changeable header business starts here + define( 'HEADER_TEXTCOLOR', '' ); + // No CSS, just IMG call. The %s is a placeholder for the theme template directory URI. + define( 'HEADER_IMAGE', '%s/images/headers/forestfloor.jpg' ); + + // The height and width of your custom header. You can hook into the theme's own filters to change these values. + // Add a filter to twentyten_header_image_width and twentyten_header_image_height to change these values. define( 'HEADER_IMAGE_WIDTH', apply_filters( 'twentyten_header_image_width', 940 ) ); define( 'HEADER_IMAGE_HEIGHT', apply_filters( 'twentyten_header_image_height', 198 ) ); + // We'll be using post thumbnails for custom header images on posts and pages. + // We want them to be 940 pixels wide by 198 pixels tall (larger images will be auto-cropped to fit). + set_post_thumbnail_size( HEADER_IMAGE_WIDTH, HEADER_IMAGE_HEIGHT, true ); + + // Don't support text inside the header image. define( 'NO_HEADER_TEXT', true ); + // Add a way for the custom header to be styled in the admin panel that controls + // custom headers. See twentyten_admin_header_style(), below. add_custom_image_header( '', 'twentyten_admin_header_style' ); - // and thus ends the changeable header business - // Default custom headers. %s is a placeholder for the theme template directory + // ... and thus ends the changeable header business. + // Default custom headers packaged with the theme. %s is a placeholder for the theme template directory URI. register_default_headers( array ( 'berries' => array ( 'url' => '%s/images/headers/berries.jpg', @@ -119,12 +159,14 @@ function twentyten_init() { ) ) ); } -endif; -add_action( 'after_setup_theme', 'twentyten_init' ); if ( ! function_exists( 'twentyten_admin_header_style' ) ) : /** - * Callback to style the header image inside the admin + * Styles the header image displayed on the Appearance > Header admin panel. + * + * Referenced via add_custom_image_header() in twentyten_setup(). + * + * @since 3.0.0 */ function twentyten_admin_header_style() { ?> @@ -141,65 +183,69 @@ function twentyten_admin_header_style() { } endif; -if ( ! function_exists( 'twentyten_get_page_number' ) ) : -/** - * Returns the page number currently being browsed - * - * Returns a vertical bar followed by page and the page - * number. Is pluggable - * - * @retun string - */ -function twentyten_get_page_number() { - if ( get_query_var( 'paged' ) ) - return ' | ' . __( 'Page ' , 'twentyten' ) . get_query_var( 'paged' ); -} -endif; - if ( ! function_exists( 'twentyten_the_page_number' ) ) : /** - * Echos the page number being browsed + * Prints the page number currently being browsed, with a vertical bar before it. * - * @uses twentyten_get_page_number + * Used in Twenty Ten's header.php to add the page number to the HTML tag. * + * @since 3.0.0 */ function twentyten_the_page_number() { - echo twentyten_get_page_number(); + if ( get_query_var( 'paged' ) ) + echo ' | ' . __( 'Page ' , 'twentyten' ) . get_query_var( 'paged' ); } endif; -if ( ! function_exists( 'twentyten_excerpt_length' ) ) : /** - * Sets the excerpt length to 40 charachters. Is pluggable + * Sets the post excerpt length to 40 characters. + * + * To override this length in a child theme, remove the filter and add your own + * function tied to the excerpt_length filter hook. * * @return int */ function twentyten_excerpt_length( $length ) { return 40; } -endif; add_filter( 'excerpt_length', 'twentyten_excerpt_length' ); -if ( ! function_exists( 'twentyten_excerpt_more' ) ) : /** - * Sets the read more link for excerpts to something pretty + * Sets the "read more" link to something pretty. * - * @return string + * To override this link in a child theme, remove the filter and add your own + * function tied to the excerpt_more filter hook. * + * @since 3.0.0 + * @return string A pretty 'Continue reading' link. */ function twentyten_excerpt_more( $more ) { return ' … <a href="'. get_permalink() . '">' . __('Continue reading <span class="meta-nav">→</span>', 'twentyten') . '</a>'; } -endif; add_filter( 'excerpt_more', 'twentyten_excerpt_more' ); +/** + * Remove inline styles printed when the gallery shortcode is used. + * + * Galleries are styled by the theme in Twenty Ten's style.css. + * + * @return string The gallery style filter, with the styles themselves removed. + */ +function twentyten_remove_gallery_css( $css ) { + return preg_replace( "#<style type='text/css'>(.*?)</style>#s", '', $css ); +} +add_filter( 'gallery_style', 'twentyten_remove_gallery_css' ); + if ( ! function_exists( 'twentyten_comment' ) ) : /** - * Template for comments and pingbacks + * Template for comments and pingbacks. * - * Used as a callback by wp_list_comments for displaying the - * comments. Is pluggable + * To override this walker in a child theme without modifying the comments template + * simply create your own twentyten_comment(), and that function will be used instead. * + * Used as a callback by wp_list_comments() for displaying the comments. + * + * @since 3.0.0 */ function twentyten_comment( $comment, $args, $depth ) { $GLOBALS ['comment'] = $comment; ?> @@ -231,18 +277,6 @@ function twentyten_comment( $comment, $args, $depth ) { } endif; -if ( ! function_exists( 'twentyten_remove_gallery_css' ) ) : -/** - * Remove inline styles on gallery shortcode - * - * @return string - */ -function twentyten_remove_gallery_css( $css ) { - return preg_replace( "#<style type='text/css'>(.*?)</style>#s", '', $css ); -} -endif; -add_filter( 'gallery_style', 'twentyten_remove_gallery_css' ); - if ( ! function_exists( 'twentyten_cat_list' ) ) : /** * Returns the list of categories @@ -275,6 +309,7 @@ function twentyten_tag_list() { } endif; + if ( ! function_exists( 'twentyten_term_list' ) ) : /** * Returns the list of taxonomy items in multiple ways @@ -313,10 +348,11 @@ function twentyten_term_list( $taxonomy, $glue = ', ', $text = '', $also_text = } endif; -if ( ! function_exists( 'twentyten_widgets_init' ) ) : /** - * Register widgetized areas + * Register widgetized areas, including two sidebars and four widget-ready columns in the footer. * + * To override twentyten_widgets_init() in a child theme, remove the action hook and add your own + * function tied to the init hook. * @uses register_sidebar */ function twentyten_widgets_init() { @@ -385,7 +421,5 @@ function twentyten_widgets_init() { 'before_title' => '<h3 class="widget-title">', 'after_title' => '</h3>', ) ); - } -endif; -add_action( 'init', 'twentyten_widgets_init' ); +add_action( 'init', 'twentyten_widgets_init' ); \ No newline at end of file