<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><meta http-equiv="content-type" content="text/html; charset=utf-8" /><style type="text/css"><!--
#msg dl { border: 1px #006 solid; background: #369; padding: 6px; color: #fff; }
#msg dt { float: left; width: 6em; font-weight: bold; }
#msg dt:after { content:':';}
#msg dl, #msg dt, #msg ul, #msg li, #header, #footer { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; }
#msg dl a { font-weight: bold}
#msg dl a:link { color:#fc3; }
#msg dl a:active { color:#ff0; }
#msg dl a:visited { color:#cc6; }
h3 { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; font-weight: bold; }
#msg pre { overflow: auto; background: #ffc; border: 1px #fc0 solid; padding: 6px; }
#msg ul, pre { overflow: auto; }
#header, #footer { color: #fff; background: #636; border: 1px #300 solid; padding: 6px; }
#patch { width: 100%; }
#patch h4 {font-family: verdana,arial,helvetica,sans-serif;font-size:10pt;padding:8px;background:#369;color:#fff;margin:0;}
#patch .propset h4, #patch .binary h4 {margin:0;}
#patch pre {padding:0;line-height:1.2em;margin:0;}
#patch .diff {width:100%;background:#eee;padding: 0 0 10px 0;overflow:auto;}
#patch .propset .diff, #patch .binary .diff {padding:10px 0;}
#patch span {display:block;padding:0 10px;}
#patch .modfile, #patch .addfile, #patch .delfile, #patch .propset, #patch .binary, #patch .copfile {border:1px solid #ccc;margin:10px 0;}
#patch ins {background:#dfd;text-decoration:none;display:block;padding:0 10px;}
#patch del {background:#fdd;text-decoration:none;display:block;padding:0 10px;}
#patch .lines, .info {color:#888;background:#fff;}
--></style>
<title>[13886] trunk/wp-content/themes/twentyten/functions.php:
Second pass on twentyten/functions.php inline documentation.</title>
</head>
<body>
<div id="msg">
<dl>
<dt>Revision</dt> <dd><a href="http://trac.wordpress.org/changeset/13886">13886</a></dd>
<dt>Author</dt> <dd>nacin</dd>
<dt>Date</dt> <dd>2010-03-30 00:05:17 +0000 (Tue, 30 Mar 2010)</dd>
</dl>
<h3>Log Message</h3>
<pre>Second pass on twentyten/functions.php inline documentation. see <a href="http://trac.wordpress.org/ticket/12695">#12695</a>. 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 <a href="http://trac.wordpress.org/ticket/12748">#12748</a>.</pre>
<h3>Modified Paths</h3>
<ul>
<li><a href="#trunkwpcontentthemestwentytenfunctionsphp">trunk/wp-content/themes/twentyten/functions.php</a></li>
</ul>
</div>
<div id="patch">
<h3>Diff</h3>
<a id="trunkwpcontentthemestwentytenfunctionsphp"></a>
<div class="modfile"><h4>Modified: trunk/wp-content/themes/twentyten/functions.php (13885 => 13886)</h4>
<pre class="diff"><span>
<span class="info">--- trunk/wp-content/themes/twentyten/functions.php 2010-03-29 22:03:15 UTC (rev 13885)
+++ trunk/wp-content/themes/twentyten/functions.php 2010-03-30 00:05:17 UTC (rev 13886)
</span><span class="lines">@@ -2,52 +2,81 @@
</span><span class="cx"> /**
</span><span class="cx"> * TwentyTen functions and definitions
</span><span class="cx"> *
</span><del>- * Sets up the theme and provides some helper functions used
- * in other parts of the theme. All functions are pluggable
</del><ins>+ * 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.
</ins><span class="cx"> *
</span><ins>+ * 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:
+ *
+ * <code>
+ * remove_action( 'after_setup_theme', 'twentyten_setup' );
+ * add_action( 'after_setup_theme', 'my_child_theme_setup' );
+ * function my_child_theme_setup() {
+ * ...
+ * }
+ * </code>
+ *
+ * For more information on hooks, see http://codex.wordpress.org/Plugin_API.
+ *
</ins><span class="cx"> * @package WordPress
</span><span class="cx"> * @subpackage Twenty Ten
</span><span class="cx"> * @since 3.0.0
</span><span class="cx"> */
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Set the content width based on the Theme CSS. Can be overriden
</del><ins>+ * Set the content width based on the theme's design and stylesheet.
</ins><span class="cx"> *
</span><del>- * Used in attachment.php to set the width of images. Should
- * be equal to the width set for .onecolumn #content in style.css
</del><ins>+ * 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.
</ins><span class="cx"> */
</span><span class="cx"> if ( ! isset( $content_width ) )
</span><span class="cx"> $content_width = 640;
</span><span class="cx">
</span><del>-if ( ! function_exists( 'twentyten_init' ) ) :
</del><ins>+/** Tell WordPress to run twentyten_setup() when the 'after_setup_theme' hook is run. */
+add_action( 'after_setup_theme', 'twentyten_setup' );
+
</ins><span class="cx"> /**
</span><del>- * Set up defaults for our theme.
</del><ins>+ * Sets up theme defaults and registers support for various WordPress features.
</ins><span class="cx"> *
</span><del>- * 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
</del><ins>+ * 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.
</ins><span class="cx"> *
</span><del>- * @uses add_theme_support()
</del><ins>+ * 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
</ins><span class="cx"> */
</span><del>-function twentyten_init() {
- // This theme allows users to set a custom background
- add_custom_background();
</del><ins>+function twentyten_setup() {
</ins><span class="cx">
</span><span class="cx"> // This theme styles the visual editor with editor-style.css to match the theme style.
</span><span class="cx"> add_editor_style();
</span><span class="cx">
</span><del>- // This theme needs post thumbnails
</del><ins>+ // This theme uses post thumbnails
</ins><span class="cx"> add_theme_support( 'post-thumbnails' );
</span><span class="cx">
</span><span class="cx"> // This theme uses wp_nav_menu()
</span><span class="cx"> add_theme_support( 'nav-menus' );
</span><span class="cx">
</span><del>- // 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 );
-
</del><span class="cx"> // Add default posts and comments RSS feed links to head
</span><span class="cx"> add_theme_support( 'automatic-feed-links' );
</span><span class="cx">
</span><span class="lines">@@ -60,22 +89,33 @@
</span><span class="cx"> if ( is_readable( $locale_file ) )
</span><span class="cx"> require_once( $locale_file );
</span><span class="cx">
</span><del>- // Your Changeable header business starts here
- // No CSS, just IMG call
</del><ins>+ // This theme allows users to set a custom background
+ add_custom_background();
+
+ // Your changeable header business starts here
</ins><span class="cx"> define( 'HEADER_TEXTCOLOR', '' );
</span><del>- define( 'HEADER_IMAGE', '%s/images/headers/forestfloor.jpg' ); // %s is theme dir uri
</del><ins>+ // No CSS, just IMG call. The %s is a placeholder for the theme template directory URI.
+ define( 'HEADER_IMAGE', '%s/images/headers/forestfloor.jpg' );
</ins><span class="cx">
</span><del>- // Add a filter to twentyten_header_image_width and twentyten_header_image_height to change these values
</del><ins>+ // 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.
</ins><span class="cx"> define( 'HEADER_IMAGE_WIDTH', apply_filters( 'twentyten_header_image_width', 940 ) );
</span><span class="cx"> define( 'HEADER_IMAGE_HEIGHT', apply_filters( 'twentyten_header_image_height', 198 ) );
</span><span class="cx">
</span><ins>+ // 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.
</ins><span class="cx"> define( 'NO_HEADER_TEXT', true );
</span><span class="cx">
</span><ins>+ // Add a way for the custom header to be styled in the admin panel that controls
+ // custom headers. See twentyten_admin_header_style(), below.
</ins><span class="cx"> add_custom_image_header( '', 'twentyten_admin_header_style' );
</span><del>- // and thus ends the changeable header business
</del><span class="cx">
</span><del>- // Default custom headers. %s is a placeholder for the theme template directory
</del><ins>+ // ... and thus ends the changeable header business.
</ins><span class="cx">
</span><ins>+ // Default custom headers packaged with the theme. %s is a placeholder for the theme template directory URI.
</ins><span class="cx"> register_default_headers( array (
</span><span class="cx"> 'berries' => array (
</span><span class="cx"> 'url' => '%s/images/headers/berries.jpg',
</span><span class="lines">@@ -119,12 +159,14 @@
</span><span class="cx"> )
</span><span class="cx"> ) );
</span><span class="cx"> }
</span><del>-endif;
-add_action( 'after_setup_theme', 'twentyten_init' );
</del><span class="cx">
</span><span class="cx"> if ( ! function_exists( 'twentyten_admin_header_style' ) ) :
</span><span class="cx"> /**
</span><del>- * Callback to style the header image inside the admin
</del><ins>+ * Styles the header image displayed on the Appearance > Header admin panel.
+ *
+ * Referenced via add_custom_image_header() in twentyten_setup().
+ *
+ * @since 3.0.0
</ins><span class="cx"> */
</span><span class="cx"> function twentyten_admin_header_style() {
</span><span class="cx"> ?>
</span><span class="lines">@@ -141,65 +183,69 @@
</span><span class="cx"> }
</span><span class="cx"> endif;
</span><span class="cx">
</span><del>-if ( ! function_exists( 'twentyten_get_page_number' ) ) :
</del><ins>+if ( ! function_exists( 'twentyten_the_page_number' ) ) :
</ins><span class="cx"> /**
</span><del>- * Returns the page number currently being browsed
</del><ins>+ * Prints the page number currently being browsed, with a vertical bar before it.
</ins><span class="cx"> *
</span><del>- * Returns a vertical bar followed by page and the page
- * number. Is pluggable
</del><ins>+ * Used in Twenty Ten's header.php to add the page number to the <title> HTML tag.
</ins><span class="cx"> *
</span><del>- * @retun string
</del><ins>+ * @since 3.0.0
</ins><span class="cx"> */
</span><del>-function twentyten_get_page_number() {
</del><ins>+function twentyten_the_page_number() {
</ins><span class="cx"> if ( get_query_var( 'paged' ) )
</span><del>- return ' | ' . __( 'Page ' , 'twentyten' ) . get_query_var( 'paged' );
</del><ins>+ echo ' | ' . __( 'Page ' , 'twentyten' ) . get_query_var( 'paged' );
</ins><span class="cx"> }
</span><span class="cx"> endif;
</span><span class="cx">
</span><del>-if ( ! function_exists( 'twentyten_the_page_number' ) ) :
</del><span class="cx"> /**
</span><del>- * Echos the page number being browsed
</del><ins>+ * Sets the post excerpt length to 40 characters.
</ins><span class="cx"> *
</span><del>- * @uses twentyten_get_page_number
</del><ins>+ * To override this length in a child theme, remove the filter and add your own
+ * function tied to the excerpt_length filter hook.
</ins><span class="cx"> *
</span><del>- */
-function twentyten_the_page_number() {
- echo twentyten_get_page_number();
-}
-endif;
-
-if ( ! function_exists( 'twentyten_excerpt_length' ) ) :
-/**
- * Sets the excerpt length to 40 charachters. Is pluggable
- *
</del><span class="cx"> * @return int
</span><span class="cx"> */
</span><span class="cx"> function twentyten_excerpt_length( $length ) {
</span><span class="cx"> return 40;
</span><span class="cx"> }
</span><del>-endif;
</del><span class="cx"> add_filter( 'excerpt_length', 'twentyten_excerpt_length' );
</span><span class="cx">
</span><del>-if ( ! function_exists( 'twentyten_excerpt_more' ) ) :
</del><span class="cx"> /**
</span><del>- * Sets the read more link for excerpts to something pretty
</del><ins>+ * Sets the "read more" link to something pretty.
</ins><span class="cx"> *
</span><del>- * @return string
</del><ins>+ * To override this link in a child theme, remove the filter and add your own
+ * function tied to the excerpt_more filter hook.
</ins><span class="cx"> *
</span><ins>+ * @since 3.0.0
+ * @return string A pretty 'Continue reading' link.
</ins><span class="cx"> */
</span><span class="cx"> function twentyten_excerpt_more( $more ) {
</span><span class="cx"> return '&nbsp;&hellip; <a href="'. get_permalink() . '">' . __('Continue&nbsp;reading&nbsp;<span class="meta-nav">&rarr;</span>', 'twentyten') . '</a>';
</span><span class="cx"> }
</span><del>-endif;
</del><span class="cx"> add_filter( 'excerpt_more', 'twentyten_excerpt_more' );
</span><span class="cx">
</span><ins>+/**
+ * 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' );
+
</ins><span class="cx"> if ( ! function_exists( 'twentyten_comment' ) ) :
</span><span class="cx"> /**
</span><del>- * Template for comments and pingbacks
</del><ins>+ * Template for comments and pingbacks.
</ins><span class="cx"> *
</span><del>- * Used as a callback by wp_list_comments for displaying the
- * comments. Is pluggable
</del><ins>+ * 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.
</ins><span class="cx"> *
</span><ins>+ * Used as a callback by wp_list_comments() for displaying the comments.
+ *
+ * @since 3.0.0
</ins><span class="cx"> */
</span><span class="cx"> function twentyten_comment( $comment, $args, $depth ) {
</span><span class="cx"> $GLOBALS ['comment'] = $comment; ?>
</span><span class="lines">@@ -231,18 +277,6 @@
</span><span class="cx"> }
</span><span class="cx"> endif;
</span><span class="cx">
</span><del>-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' );
-
</del><span class="cx"> if ( ! function_exists( 'twentyten_cat_list' ) ) :
</span><span class="cx"> /**
</span><span class="cx"> * Returns the list of categories
</span><span class="lines">@@ -275,6 +309,7 @@
</span><span class="cx"> }
</span><span class="cx"> endif;
</span><span class="cx">
</span><ins>+
</ins><span class="cx"> if ( ! function_exists( 'twentyten_term_list' ) ) :
</span><span class="cx"> /**
</span><span class="cx"> * Returns the list of taxonomy items in multiple ways
</span><span class="lines">@@ -313,10 +348,11 @@
</span><span class="cx"> }
</span><span class="cx"> endif;
</span><span class="cx">
</span><del>-if ( ! function_exists( 'twentyten_widgets_init' ) ) :
</del><span class="cx"> /**
</span><del>- * Register widgetized areas
</del><ins>+ * Register widgetized areas, including two sidebars and four widget-ready columns in the footer.
</ins><span class="cx"> *
</span><ins>+ * To override twentyten_widgets_init() in a child theme, remove the action hook and add your own
+ * function tied to the init hook.
</ins><span class="cx"> * @uses register_sidebar
</span><span class="cx"> */
</span><span class="cx"> function twentyten_widgets_init() {
</span><span class="lines">@@ -385,7 +421,5 @@
</span><span class="cx"> 'before_title' => '<h3 class="widget-title">',
</span><span class="cx"> 'after_title' => '</h3>',
</span><span class="cx"> ) );
</span><del>-
</del><span class="cx"> }
</span><del>-endif;
-add_action( 'init', 'twentyten_widgets_init' );
</del><ins>+add_action( 'init', 'twentyten_widgets_init' );
</ins><span class="cx">\ No newline at end of file
</span></span></pre>
</div>
</div>
</body>
</html>