In Twenty Ten, documentation and code improvements. see #12695.

git-svn-id: http://svn.automattic.com/wordpress/trunk@14708 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-content/themes/twentyten/404.php

@@ -4,7 +4,7 @@
  *
  * @package WordPress
  * @subpackage Twenty_Ten
- * @since 3.0.0
+ * @since Twenty Ten 1.0
  */
 ?>
 

wp-content/themes/twentyten/archive.php

@@ -9,7 +9,7 @@
  *
  * @package WordPress
  * @subpackage Twenty_Ten
- * @since 3.0.0
+ * @since Twenty Ten 1.0
  */
 ?>
 
@@ -18,7 +18,15 @@
 		<div id="container">
 			<div id="content" role="main">
 
-<?php the_post(); ?>
+<?php
+	/* Queue the first post, that way we know
+	 * what date we're dealing with (if that is the case).
+	 *
+	 * We reset this later so we can run the loop
+	 * properly with a call to rewind_posts().
+	 */
+	the_post();
+?>
 
 			<h1 class="page-title">
 <?php if ( is_day() ) : ?>
@@ -31,8 +39,14 @@
 				<?php _e( 'Blog Archives', 'twentyten' ); ?>
 <?php endif; ?>
 			</h1>
-<?php rewind_posts(); ?>
+
 <?php
+	/* Since we called the_post() above, we need to
+	 * rewind the loop back to the beginning that way
+	 * we can run the loop properly, in full.
+	 */
+	rewind_posts();
+
 	/* Run the loop for the archives page to output the posts.
 	 * If you want to overload this in a child theme then include a file
 	 * called loop-archives.php and that will be used instead.

wp-content/themes/twentyten/attachment.php

@@ -4,7 +4,7 @@
  *
  * @package WordPress
  * @subpackage Twenty_Ten
- * @since 3.0.0
+ * @since Twenty Ten 1.0
  */
 ?>
 
@@ -13,7 +13,7 @@
 		<div id="container">
 			<div id="content" role="main">
 
-<?php the_post(); ?>
+<?php if ( have_posts() ) while ( have_posts() ) : the_post(); ?>
 
 				<p class="page-title"><a href="<?php echo get_permalink( $post->post_parent ); ?>" title="<?php printf( esc_attr__( 'Return to %s', 'twentyten' ), esc_html( get_the_title( $post->post_parent ), 1 ) ); ?>" rel="gallery">&larr; <?php echo get_the_title( $post->post_parent ); ?></a></p>
 
@@ -98,6 +98,8 @@
 
 <?php comments_template(); ?>
 
+<?php endwhile; ?>
+
 			</div><!-- #content -->
 		</div><!-- #container -->
 

wp-content/themes/twentyten/author.php

@@ -4,7 +4,7 @@
  *
  * @package WordPress
  * @subpackage Twenty_Ten
- * @since 3.0.0
+ * @since Twenty Ten 1.0
  */
 ?>
 
@@ -13,11 +13,22 @@
 		<div id="container">
 			<div id="content" role="main">
 
-<?php the_post(); ?>
+<?php
+	/* Queue the first post, that way we know who
+	 * the author is when we try to get their name,
+	 * URL, description, avatar, etc.
+	 *
+	 * We reset this later so we can run the loop
+	 * properly with a call to rewind_posts().
+	 */
+	the_post();
+?>
 
 				<h1 class="page-title author"><?php printf( __( 'Author Archives: %s', 'twentyten' ), "<span class='vcard'><a class='url fn n' href='" . get_author_posts_url( get_the_author_meta( 'ID' ) ) . "' title='" . esc_attr( get_the_author() ) . "' rel='me'>" . get_the_author() . "</a></span>" ); ?></h1>
 
-<?php if ( get_the_author_meta( 'description' ) ) : // If a user has filled out their description, show a bio on their entries  ?>
+<?php
+// If a user has filled out their description, show a bio on their entries.
+if ( get_the_author_meta( 'description' ) ) : ?>
 					<div id="entry-author-info">
 						<div id="author-avatar">
 							<?php echo get_avatar( get_the_author_meta( 'user_email' ), apply_filters( 'twentyten_author_bio_avatar_size', 60 ) ); ?>
@@ -29,9 +40,13 @@
 					</div><!-- .entry-author-info -->
 <?php endif; ?>
 
-<?php rewind_posts(); ?>
-
 <?php
+	/* Since we called the_post() above, we need to
+	 * rewind the loop back to the beginning that way
+	 * we can run the loop properly, in full.
+	 */
+	rewind_posts();
+
 	/* Run the loop for the author archive page to output the authors posts
 	 * If you want to overload this in a child theme then include a file
 	 * called loop-author.php and that will be used instead.

wp-content/themes/twentyten/category.php

@@ -4,7 +4,7 @@
  *
  * @package WordPress
  * @subpackage Twenty_Ten
- * @since 3.0.0
+ * @since Twenty Ten 1.0
  */
 ?>
 
@@ -20,9 +20,7 @@
 					$category_description = category_description();
 					if ( ! empty( $category_description ) )
 						echo '<div class="archive-meta">' . $categorydesc . '</div>';
-				?>
 
-				<?php
 				/* Run the loop for the category page to output the posts.
 				 * If you want to overload this in a child theme then include a file
 				 * called loop-category.php and that will be used instead.

wp-content/themes/twentyten/comments.php

@@ -9,7 +9,7 @@
  *
  * @package WordPress
  * @subpackage Twenty_Ten
- * @since 3.0.0
+ * @since Twenty Ten 1.0
  */
 ?>
 
@@ -18,6 +18,10 @@
 				<div class="nopassword"><?php _e( 'This post is password protected. Enter the password to view any comments.', 'twentyten' ); ?></div>
 			</div><!-- .comments -->
 <?php
+		/* Stop the rest of comments.php from being processed,
+		 * but don't kill the script entirely -- we still have
+		 * to fully load the template.
+		 */
 		return;
 	endif;
 ?>
@@ -27,14 +31,12 @@
 ?>
 
 <?php if ( have_comments() ) : ?>
-			<h3 id="comments-title">
+			<h3 id="comments-title"><?php
-<?php
 			printf( _n( 'One Response to %2$s', '%1$s Responses to %2$s', get_comments_number(), 'twentyten' ),
 			number_format_i18n( get_comments_number() ), '<em>' . get_the_title() . '</em>' );
-?>
+			?></h3>
-			</h3>
 
-<?php if ( get_comment_pages_count() > 1 ) : // are there comments to navigate through ?>
+<?php if ( get_comment_pages_count() > 1 ) : // Are there comments to navigate through? ?>
 			<div class="navigation">
 				<div class="nav-previous"><?php previous_comments_link( __( '&larr; Older Comments', 'twentyten' ) ); ?></div>
 				<div class="nav-next"><?php next_comments_link( __( 'Newer Comments &rarr;', 'twentyten' ) ); ?></div>
@@ -42,26 +44,35 @@
 <?php endif; // check for comment navigation ?>
 
 			<ol class="commentlist">
-				<?php wp_list_comments( array( 'callback' => 'twentyten_comment' ) ); ?>
+				<?php
+					/* Loop through and list the comments. Tell wp_list_comments()
+					 * to use twentyten_comment() to format the comments.
+					 * If you want to overload this in a child theme then you can
+					 * define twentyten_comment() and that will be used instead.
+					 * See twentyten_comment() in twentyten/functions.php for more.
+					 */
+					wp_list_comments( array( 'callback' => 'twentyten_comment' ) );
+				?>
 			</ol>
 
-<?php if ( get_comment_pages_count() > 1 ) : // are there comments to navigate through ?>
+<?php if ( get_comment_pages_count() > 1 ) : // Are there comments to navigate through? ?>
 			<div class="navigation">
 				<div class="nav-previous"><?php previous_comments_link( __( '&larr; Older Comments', 'twentyten' ) ); ?></div>
 				<div class="nav-next"><?php next_comments_link( __( 'Newer Comments &rarr;', 'twentyten' ) ); ?></div>
 			</div>
 <?php endif; // check for comment navigation ?>
 
-<?php else : // this is displayed if there are no comments so far ?>
+<?php else : // or, if we don't have comments:
-
-<?php if ( comments_open() ) : // If comments are open, but there are no comments ?>
-
-<?php else : // if comments are closed ?>
 
+	/* If there are no comments and comments are closed,
+	 * let's leave a little note, shall we?
+	 */
+	if ( ! comments_open() ) :
+?>
 	<p class="nocomments"><?php _e( 'Comments are closed.', 'twentyten' ); ?></p>
+<?php endif; // end ! comments_opened() ?>
 
-<?php endif; ?>
+<?php endif; // end have_comments() ?>
-<?php endif; ?>
 
 <?php comment_form(); ?>
 

wp-content/themes/twentyten/footer.php

@@ -7,7 +7,7 @@
  *
  * @package WordPress
  * @subpackage Twenty_Ten
- * @since 3.0.0
+ * @since Twenty Ten 1.0
  */
 ?>
 	</div><!-- #main -->
@@ -15,7 +15,12 @@
 	<div id="footer" role="contentinfo">
 		<div id="colophon">
 
-<?php get_sidebar( 'footer' ); ?>
+<?php
+	/* A sidebar in the footer? Yep. You can can customize
+	 * your footer with four columns of widgets.
+	 */
+	get_sidebar( 'footer' );
+?>
 
 			<div id="site-info">
 				<a href="<?php echo home_url( '/' ) ?>" title="<?php echo esc_attr( get_bloginfo( 'name', 'display' ) ); ?>" rel="home">

wp-content/themes/twentyten/header.php

@@ -6,11 +6,9 @@
  *
  * @package WordPress
  * @subpackage Twenty_Ten
- * @since 3.0.0
+ * @since Twenty Ten 1.0
  */
-?>
+?><!DOCTYPE html>
-
-<!DOCTYPE html>
 <html <?php language_attributes(); ?>>
 <head>
 	<meta charset="<?php bloginfo( 'charset' ); ?>" />

wp-content/themes/twentyten/index.php

@@ -10,7 +10,7 @@
  *
  * @package WordPress
  * @subpackage Twenty_Ten
- * @since 3.0.0
+ * @since Twenty Ten 1.0
  */
 ?>
  

wp-content/themes/twentyten/loop.php

@@ -9,7 +9,7 @@
  *
  * @package WordPress
  * @subpackage Twenty_Ten
- * @since 3.0.0
+ * @since Twenty Ten 1.0
  */
 ?>
 
@@ -26,16 +26,31 @@
 	<div id="post-0" class="post error404 not-found">
 		<h1 class="entry-title"><?php _e( 'Not Found', 'twentyten' ); ?></h1>
 		<div class="entry-content">
-			<p><?php _e( 'Apologies, but no results were found for the requested Archive. Perhaps searching will help find a related post.', 'twentyten' ); ?></p>
+			<p><?php _e( 'Apologies, but no results were found for the requested archive. Perhaps searching will help find a related post.', 'twentyten' ); ?></p>
 			<?php get_search_form(); ?>
 		</div><!-- .entry-content -->
 	</div><!-- #post-0 -->
 <?php endif; ?>
 
-<?php /* Start the Loop */ ?>
+<?php
+	/* Start the Loop.
+	 *
+	 * In Twenty Ten we use the same loop in multiple contexts.
+	 * It is broken into three main parts: when we're displaying
+	 * posts that are in the gallery category, when we're displaying
+	 * posts in the asides category, and finally all other posts.
+	 *
+	 * Additionally, we sometimes check for whether we are on an
+	 * archive page, a search page, etc., allowing for small differences
+	 * in the loop on each template without actually duplicating
+	 * the rest of the loop that is shared.
+	 *
+	 * Without further ado, the loop:
+	 */ ?>
 <?php while ( have_posts() ) : the_post(); ?>
 
-<?php /* How to Display posts in the Gallery Category */ ?>
+<?php /* How to display posts in the Gallery category. */ ?>
+
 	<?php if ( in_category( _x('gallery', 'gallery category slug', 'twentyten') ) ) : ?>
 		<div id="post-<?php the_ID(); ?>" <?php post_class(); ?>>
 			<h2 class="entry-title"><a href="<?php the_permalink(); ?>" title="<?php printf( esc_attr__( 'Permalink to %s', 'twentyten' ), the_title_attribute( 'echo=0' ) ); ?>" rel="bookmark"><?php the_title(); ?></a></h2>
@@ -71,11 +86,13 @@
 		</div>
 
 <?php /* How to display posts in the asides category */ ?>
+
 	<?php elseif ( in_category( _x('asides', 'asides category slug', 'twentyten') ) ) : ?>
 		<div id="post-<?php the_ID(); ?>" <?php post_class(); ?>>
-	<?php if ( is_archive() || is_search() ) : // Only display Excerpts for archives & search ?>
+
+		<?php if ( is_archive() || is_search() ) : // Display excerpts for archives and search. ?>
 			<div class="entry-summary">
-				<?php the_excerpt( __( 'Continue reading <span class="meta-nav">&rarr;</span>', 'twentyten' ) ); ?>
+				<?php the_excerpt(); ?>
 			</div><!-- .entry-summary -->
 		<?php else : ?>
 			<div class="entry-content">
@@ -89,9 +106,10 @@
 				<span class="comments-link"><?php comments_popup_link( __( 'Leave a comment', 'twentyten' ), __( '1 Comment', 'twentyten' ), __( '% Comments', 'twentyten' ) ); ?></span>
 				<?php edit_post_link( __( 'Edit', 'twentyten' ), '<span class="meta-sep">|</span> <span class="edit-link">', '</span>' ); ?>
 			</div><!-- #entry-utility -->
-		</div><!-- #post-<?php the_ID(); ?> -->
+		</div><!-- #post-(id) -->
+
+<?php /* How to display all other posts. */ ?>
 
-<?php /* How to display all other posts */ ?>
 	<?php else : ?>
 		<div id="post-<?php the_ID(); ?>" <?php post_class(); ?>>
 			<h2 class="entry-title"><a href="<?php the_permalink(); ?>" title="<?php printf( esc_attr__( 'Permalink to %s', 'twentyten' ), the_title_attribute( 'echo=0' ) ); ?>" rel="bookmark"><?php the_title(); ?></a></h2>
@@ -100,7 +118,7 @@
 				<?php twentyten_posted_on(); ?>
 			</div><!-- .entry-meta -->
 
-	<?php if ( is_archive() || is_search() ) : // Only display Excerpts for archives & search ?>
+	<?php if ( is_archive() || is_search() ) : // Only display excerpts for archives and search. ?>
 			<div class="entry-summary">
 				<?php the_excerpt( __( 'Continue reading <span class="meta-nav">&rarr;</span>', 'twentyten' ) ); ?>
 			</div><!-- .entry-summary -->
@@ -134,8 +152,9 @@
 
 		<?php comments_template( '', true ); ?>
 
-	<?php endif; // if different categories queried ?>
+	<?php endif; // This was the if statement that broke the loop into three parts based on categories. ?>
-<?php endwhile; ?>
+
+<?php endwhile; // End the loop. Whew. ?>
 
 <?php /* Display navigation to next/previous pages when applicable */ ?>
 <?php if (  $wp_query->max_num_pages > 1 ) : ?>

wp-content/themes/twentyten/onecolumn-page.php

@@ -3,20 +3,22 @@
  * Template Name: One column, no sidebar
  *
  * A custom page template without sidebar.
- * Selectable from a dropdown menu on the edit page screen.
+ *
+ * The "Template Name:" bit above allows this to be selectable
+ * from a dropdown menu on the edit page screen.
  *
  * @package WordPress
  * @subpackage Twenty_Ten
- * @since 3.0.0
+ * @since Twenty Ten 1.0
  */
 ?>
 
 <?php get_header(); ?>
 
-		<div id="container" class="onecolumn">
+		<div id="container" class="one-column">
 			<div id="content" role="main">
 
-<?php the_post(); ?>
+<?php if ( have_posts() ) while ( have_posts() ) : the_post(); ?>
 
 				<div id="post-<?php the_ID(); ?>" <?php post_class(); ?>>
 					<h1 class="entry-title"><?php the_title(); ?></h1>
@@ -29,6 +31,8 @@
 
 				<?php comments_template( '', true ); ?>
 
+<?php endwhile; ?>
+
 			</div><!-- #content -->
 		</div><!-- #container -->
 

wp-content/themes/twentyten/page.php

@@ -9,7 +9,7 @@
  *
  * @package WordPress
  * @subpackage Twenty_Ten
- * @since 3.0.0
+ * @since Twenty Ten 1.0
  */
 ?>
 
@@ -18,7 +18,7 @@
 		<div id="container">
 			<div id="content" role="main">
 
-<?php the_post(); ?>
+<?php if ( have_posts() ) while ( have_posts() ) : the_post(); ?>
 
 				<div id="post-<?php the_ID(); ?>" <?php post_class(); ?>>
 					<?php if ( is_front_page() ) { ?>
@@ -36,6 +36,8 @@
 
 				<?php comments_template( '', true ); ?>
 
+<?php endwhile; ?>
+
 			</div><!-- #content -->
 		</div><!-- #container -->
 

wp-content/themes/twentyten/search.php

@@ -4,7 +4,7 @@
  *
  * @package WordPress
  * @subpackage Twenty_Ten
- * @since 3.0.0
+ * @since Twenty Ten 1.0
  */
 ?>
 

wp-content/themes/twentyten/sidebar-footer.php

@@ -4,19 +4,27 @@
  *
  * @package WordPress
  * @subpackage Twenty_Ten
- * @since 3.0.0
+ * @since Twenty Ten 1.0
  */
 ?>
 
 <?php
-	if (
+	/* The footer widget area is triggered if any of the areas
-		is_active_sidebar( 'first-footer-widget-area' )  ||
+	 * have widgets. So let's check that first.
-		is_active_sidebar( 'second-footer-widget-area' ) ||
+	 *
-		is_active_sidebar( 'third-footer-widget-area' )  ||
+	 * If none of the sidebars have widgets, then let's bail early.
-		is_active_sidebar( 'fourth-footer-widget-area' )
+	 */
-	) :
+	if (   ! is_active_sidebar( 'first-footer-widget-area'  )
+		&& ! is_active_sidebar( 'second-footer-widget-area' )
+		&& ! is_active_sidebar( 'third-footer-widget-area'  )
+		&& ! is_active_sidebar( 'fourth-footer-widget-area' )
+	)
+		return;
+	// If we get this far, we have widgets. Let do this.
 ?>
+
 			<div id="footer-widget-area" role="complementary">
+
 <?php if ( is_active_sidebar( 'first-footer-widget-area' ) ) : ?>
 				<div id="first" class="widget-area">
 					<ul class="xoxo">
@@ -50,4 +58,3 @@
 <?php endif; ?>
 
 			</div><!-- #footer-widget-area -->
-<?php endif; ?>

wp-content/themes/twentyten/sidebar.php

@@ -4,13 +4,21 @@
  *
  * @package WordPress
  * @subpackage Twenty_Ten
- * @since 3.0.0
+ * @since Twenty Ten 1.0
  */
 ?>
 
 		<div id="primary" class="widget-area" role="complementary">
 			<ul class="xoxo">
-<?php if ( ! dynamic_sidebar( 'primary-widget-area' ) ) : // begin primary widget area ?>
+
+<?php
+	/* When we call the dynamic_sidebar() function, it'll spit out
+	 * the widgets for that widget area. If it instead returns false,
+	 * then the sidebar simply doesn't exist, so we'll hard-code in
+	 * some default sidebar stuff just in case.
+	 */
+	if ( ! dynamic_sidebar( 'primary-widget-area' ) ) : ?>
+	
 			<li id="search" class="widget-container widget_search">
 				<?php get_search_form(); ?>
 			</li>
@@ -30,14 +38,19 @@
 					<?php wp_meta(); ?>
 				</ul>
 			</li>
+
 		<?php endif; // end primary widget area ?>
 			</ul>
 		</div><!-- #primary .widget-area -->
 
-<?php if ( is_active_sidebar( 'secondary-widget-area' ) ) : // Nothing here by default and design ?>
+<?php
+	// A second sidebar for widgets, just because.
+	if ( is_active_sidebar( 'secondary-widget-area' ) ) : ?>
+
 		<div id="secondary" class="widget-area" role="complementary">
 			<ul class="xoxo">
 				<?php dynamic_sidebar( 'secondary-widget-area' ); ?>
 			</ul>
 		</div><!-- #secondary .widget-area -->
+
 <?php endif; ?>

wp-content/themes/twentyten/single.php

@@ -4,7 +4,7 @@
  *
  * @package WordPress
  * @subpackage Twenty_Ten
- * @since 3.0.0
+ * @since Twenty Ten 1.0
  */
 ?>
 
@@ -53,7 +53,7 @@
 						<?php twentyten_posted_in(); ?>
 						<?php edit_post_link( __( 'Edit', 'twentyten' ), '<span class="edit-link">', '</span>' ); ?>
 					</div><!-- .entry-utility -->
-				</div><!-- #post-<?php the_ID(); ?> -->
+				</div><!-- #post-(id) -->
 
 				<div id="nav-below" class="navigation">
 					<div class="nav-previous"><?php previous_post_link( '%link', '<span class="meta-nav">' . _x( '&larr;', 'Previous post link', 'twentyten' ) . '</span> %title' ); ?></div>

wp-content/themes/twentyten/style.css

@@ -87,7 +87,7 @@ LAYOUT: One column, no sidebar
 DESCRIPTION: One centered column with no sidebar
 */
 
-.onecolumn #content {
+.one-column #content {
 	margin: 0 auto;
 	width: 640px;
 }
@@ -1303,7 +1303,7 @@ code {
 		margin: 0;
 	}
 	#content,
-	.onecolumn #content {
+	.one-column #content {
 		width: 100%;
 		margin: 24pt 0 0;
 	}

wp-content/themes/twentyten/tag.php

@@ -4,7 +4,7 @@
  *
  * @package WordPress
  * @subpackage Twenty_Ten
- * @since 3.0.0
+ * @since Twenty Ten 1.0
  */
 ?>
 
@@ -13,13 +13,9 @@
 		<div id="container">
 			<div id="content" role="main">
 
-<?php the_post(); ?>
+				<h1 class="page-title"><?php
-
+					printf( __( 'Tag Archives: %s', 'twentyten' ), '<span>' . single_tag_title( '', false ) . '</span>' );
-				<h1 class="page-title">
+				?></h1>
-					<?php printf( __( 'Tag Archives: %s', 'twentyten' ), '<span>' . single_tag_title( '', false ) . '</span>' ); ?>
-				</h1>
-
-<?php rewind_posts(); ?>
 
 <?php
 /* Run the loop for the tag archive to output the posts