Changeset 13886 for trunk/wp-content/themes/twentyten/functions.php

Timestamp:

03/30/2010 12:05:17 AM (15 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:

• trunk/wp-content/themes/twentyten/functions.php (modified) (10 diffs)

trunk/wp-content/themes/twentyten/functions.php

@@ -3 +3 @@
  * 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:
+ *
+ * <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.
  *
  * @package WordPress
@@ -12 +36 @@
 
 /**
- * Set the content width based on the Theme CSS.  Can be overriden
- *
- * Used in attachment.php to set the width of images.  Should
- * be equal to the width set for .onecolumn #content in style.css
+ * Set the content width based on the theme's design and stylesheet.
+ *
+ * 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' ) ) :
-/**
- * Set up defaults for our theme.
- *
- * 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
- *
- * @uses add_theme_support()
- */
-function twentyten_init() {
-    // This theme allows users to set a custom background
-    add_custom_background();
+/** Tell WordPress to run twentyten_setup() when the 'after_setup_theme' hook is run. */
+add_action( 'after_setup_theme', 'twentyten_setup' );
+
+/**
+ * Sets up theme defaults and registers support for various WordPress features.
+ *
+ * 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.
+ *
+ * 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_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
@@ -61 +90 @@
         require_once( $locale_file );
 
-    // Your Changeable header business starts here
-    // No CSS, just IMG call
+    // This theme allows users to set a custom background
+    add_custom_background();
+
+    // Your changeable header business starts here
     define( 'HEADER_TEXTCOLOR', '' );
-    define( 'HEADER_IMAGE', '%s/images/headers/forestfloor.jpg' ); // %s is theme dir uri
-
-    // Add a filter to twentyten_header_image_width and twentyten_header_image_height to change these values
+    // 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 (
@@ -120 +160 @@
     ) );
 }
-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() {
@@ -142 +184 @@
 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 ( ! function_exists( 'twentyten_the_page_number' ) ) :
+/**
+ * Prints the page number currently being browsed, with a vertical bar before it.
+ *
+ * Used in Twenty Ten's header.php to add the page number to the <title> HTML tag.
+ *
+ * @since 3.0.0
+ */
+function twentyten_the_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
- *
- * @uses twentyten_get_page_number
- *
- */
-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
+        echo ' | ' . __( 'Page ' , 'twentyten' ) . get_query_var( 'paged' );
+}
+endif;
+
+/**
+ * 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
@@ -178 +209 @@
     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
- *
- * @return string
- *
+/**
+ * Sets the "read more" link to something pretty.
+ *
+ * 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 '&nbsp;&hellip; <a href="'. get_permalink() . '">' . __('Continue&nbsp;reading&nbsp;<span class="meta-nav">&rarr;</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
- *
- * Used as a callback by wp_list_comments for displaying the
- * comments.  Is pluggable
- *
+ * Template for comments and pingbacks.
+ *
+ * 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 ) {
@@ -232 +278 @@
 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' ) ) :
 /**
@@ -275 +309 @@
 }
 endif;
+
 
 if ( ! function_exists( 'twentyten_term_list' ) ) :
@@ -314 +349 @@
 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
  */
@@ -386 +422 @@
         'after_title' => '</h3>',
     ) );
-
-}
-endif;
+}
 add_action( 'init', 'twentyten_widgets_init' );