Codex

Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

zh-cn:The Loop in Action

序言

"循环"是一个指明WordPress主要程序过程的术语。你在你的模板template files中应用循环来把你的文章表现给读者。你可以制做不包含循环的模板,但是你就只能展示一篇文章的数据了。

在我们进入'循环'之前,让我们先来了解一点关于WordPress在循环开始前的动作情况的背景知识。它要做的第一件事就是检查它所需要提供的所有文件。然后,它会从数据库收集blog administrator的默认设置。这包括如每一页展示的文章数,评论是否加载,以及其它一些东西。一量这些默认的数据建立好了,WordPress检查用户请求内容。这一信息将被用来决定那些文章会被从数据库抓取出来。

如果用户没有请求特定的文章,分类,页面或数据,WordPress使用提前采集好的默认数据来决定把那些文章提供给用户。例如,如果博客管理员已经在Administration > Settings > Reading设定显示5篇文章在每个页面,那么WordPress将会从数据库抓取最新的五篇文章给用户。如果用户请求了特定的文章,分类,页面或者是数据,那么WordPress将会使用这个信息决定从数据库取出那些数据。

一旦这些过程完成,WP连接到数据库,检索特定的信息,将结果存在一个变量。循环需要调用这个变量来控制你的模板输出。

默认的,如果访客没有选定一些特定的文章,页面,分类,或数据,WP使用index.php来展示所有东西。做为讨论循环的第一个部分,我们将集中讨论index.php,以及按默认值输出你的文章的情况,后面,只要你理解了这工作是怎么完成的,我们将介绍在其它模板文件下的循环技术。

世界上最简单的index页面

下面展示了一个全功能的首页文件(index.php), 他仅展示了每篇文章的内容,使用中视具体情况去调整循环。 这个展示的目的是向你证明一个循环是多么简单。 大多数在index.php 里的循环增加了更多的css,html,php,这些都让这个循环看起来更强大也更漂亮。

<?php
get_header();
if (have_posts()) :
   while (have_posts()) :
      the_post();
      the_content();
   endwhile;
endif;
get_sidebar();
get_footer(); 
?>

现在就让我们做一些东西让循环看起来更漂亮吧!

默认循环

下面我们来一步一步看 默认经典 的循环是怎么实现的,基于标准的WordPress v1.5.

开始循环

index.php文件顶部可以看到循环如何开始.

<?php if (have_posts()) : ?>
<?php while (have_posts()) : the_post(); ?>
  1. 首先, 通过have_posts()方法来检查是否有文章。
  2. 如果有文章, PHP while循环开始. while 循环会一直执行一直到其括号里的条件为真。所以直到have_posts()返回真,while循环就不会停止(have_posts() 方法单纯的检查下一篇文章能否找到。如果找到了,if判断返回真,while循环就再次执行;如果没有下一篇文章,if判断返回假,跳出循环)。

产生文章

the_post()方法 takes the current item in the collection of posts and makes it available for use inside this iteration of The Loop. 没有 the_post(), 大多数 模板标签 都不能用了。

当文章信息可用时,模板文件向访问者展现文章信息。

标题、日期及作者

下面的模板标签 得到了当前文章标题,时间和作者。

<h2 id="post-<?php the_ID(); ?>">
  <a href="<?php the_permalink() ?>" rel="bookmark" title="Permanent Link to <?php the_title(); ?>">
  <?php the_title(); ?><!--文章标题-->
</a>
</h2>
<small>
  <?php the_time('F jS, Y') ?><!--日期--> 
  by <?php the_author() ?><!--作者-->
</small>

文章内容

the_content()是文章内容。它是循环里文章的“肉”。

<div class="entry">
<?php the_content('阅读全文 &raquo;'); ?>
</div>

如果你熟悉CSS,注意到div 被赋予 class="entry".这样你就可以根据这个特定的符号来对其进行设定样式或功能。

更多标签 : 如果文章包含快速标签 叫做 更多, 写做 <!--more-->,所有之前的将在循环中显示,之后的被省略。

单独文章页面 <!--more--> 将被无视。所以使用 <!--more--> 可强迫读者进入单独文章页面。

其它细节

Beneath each post's content in the index.php template file is a place to display more information about the post, such as the categories, date, and comment information. Known as the post meta data section, if you're a logged in user of sufficient privilege (or the post's author), you will also see an "Edit This" link, thanks to the edit_post_link() template tag function.

<p class="postmetadata">
Posted in <?php the_category(', ') ?> 
<strong>|</strong>
<?php edit_post_link('Edit','','<strong>|</strong>'); ?>  
<?php comments_popup_link('No Comments »', '1 Comment »', '% Comments »'); ?></p>

If commenting is enabled, or if the post has comments, the comments_popup_link() template tag will display a link to the comments. If you're using the comments popup window, this link will open the comments window; otherwise it will jump right to this post's comments.

If the visitor is viewing an index of posts (i.e.: more than one post in The Loop), the comments_popup_link() link will take the reader to this post's individual page.

自动发现Trackback

The trackback_rdf template tag's function is to output machine-readable code used for trackback auto-discovery.

<!--
<?php trackback_rdf(); ?>
-->

Note: The trackback_rdf() tag is supposed to be used with comments around it. It is not "turned off".

结束循环

The following ends The Loop. After this, the various post-related template tags will not work as expected (or if they do, they will use the last post from The Loop). This means, that if you need to use a template tag that works within The Loop, you need to put it in before this point.

<?php endwhile; ?>

This section, immediately after the end of The Loop, displays navigation controls to move forward and backward by each web page. More information is available in function reference for posts_nav_link().

 <div class="navigation">
 <div class="alignleft"><?php previous_posts_link('&laquo; Previous Entries') ?></div>
 <div class="alignright"><?php next_posts_link('Next Entries &raquo;','') ?></div>
 </div>

If the blog is set to display 10 posts per page, and the conditions used by The Loop collect 25 posts, there will be three pages to navigate: two pages of 10 posts each, and one page of 5 posts. The navigation links will allow the visitor to move forward and backward through the collection of posts.

The navigation controls are included outside The Loop, but inside the if condition, so that they only show up if there are any posts. The navigation functions themselves also check whether or not there is anything to which they will link, based on the current Loop, and only display links if there's something to link.

<?php else : ?>
 <h2 class="center">Not Found</h2>
 <p class="center">
<?php _e("Sorry, but you are looking for something that isn't here."); ?></p>

The else : clause determines what to do if have_posts() (from way up at the top) is false. That is to say, the stuff after the else will only be executed/displayed if The Loop had zero posts. No posts show up if, for example, the visitor requested a specific day for which no posts were made or a search was performed that produced no results.

  <?php endif; ?>

This ends the conditional test of "if there are posts do this, else if there are no posts, do that". Once the conditional test is finished, the default index.php template next includes the sidebar, and finally the footer.

其它模板中的循环

WordPress会用不同的模版文件使得博客的显示方式多彩多样。在默认的WordPress主题中,利用 template files 的 主页视图,分类视图,以及存档视图来作为显示单独文章的模版。 每个使用 The Loop的模版,但采用了稍微不同的样式, 则参考 template tags的不同用法.

For any view which does not have a separate template file, WordPress will use index.php by default. If a visitor requests a single post, WordPress will first look for a file named single.php. If that file exists, it will be used to present the post to the visitor. If that file does not exist, WordPress will use index.php to present the post to the visitor. This is called the Template Hierarchy.

If you are making your own Theme, it's often helpful to look at the template files from the default Theme as a point of reference. It's also helpful to use your theme's index.php as a template for your other template files. Doing so may give you a known and working page from which to begin making changes as you create more template files.

不同的存档格式

An archive is a collection of historical posts. In the default usage, the posts displayed on your main index are recent chronological postings. When a visitor clicks on one of your archive links, or if they manually request a specific date (http://www.example.com/blog/index.php?m=200504 or http://www.example.com/blog/2005/04 to select all posts from April, 2005), WordPress will display an archive view. By default, the archive will use index.php, and thus look the same as your front page, just displaying the posts from April 2005.

When WordPress prepares an archive view for a visitor, it specifically looks for a file named archive.php in your current theme's directory. If you'd like to visually disambiguate archives from your front page, simply copy index.php to archive.php, and edit archive.php as necessary!

For example, if you want to show only post titles, and no post content, for your list of archives, you could use something like this:

<?php get_header(); ?>
 <div id="content" class="narrowcolumn">

  <?php if (have_posts()) : ?>
   <?php while (have_posts()) : the_post(); ?>
     <div class="post">
     <h2 id="post-<?php the_ID(); ?>">
<a href="<?php the_permalink() ?>" rel="bookmark" title="Permanent Link to <?php the_title(); ?>"><?php the_title(); ?></a></h2>
     <small><?php the_time('F jS, Y') ?> <!-- by <?php the_author() ?> --></small>
      </div>
    <?php endwhile; ?>
<div class="navigation">
<div class="alignleft">
<?php posts_nav_link('','','&laquo; Previous Entries') ?>
</div>
<div class="alignright">
<?php posts_nav_link('','Next Entries &raquo;','') ?>
</div>
  </div>
<?php else : ?>
  <h2 class="center">Not Found</h2>
 <p class="center"><?php _e("Sorry, but you are looking for something that isn't here."); ?></p>
  <?php endif; ?>
</div>
<?php get_sidebar(); ?>
<?php get_footer(); ?>

不同的分类格式

Like the archive views, WordPress looks for a separate template file for category views. If a visitor clicks on a link for a category in your blog, they will be taken to the category view. WordPress will prepare The Loop with posts from that category only, limiting the number of posts per the blog's default settings.

To make your category view different from your index view, copy index.php and rename it category.php. For a category view, it's probably not necessary to list the categories to which a post is assigned, so let's remove that portion. Instead, let's announce the category at the top of the page:

<?php get_header(); ?>
 <div id="content" class="narrowcolumn">
 <p>
 <strong>
  <?php single_cat_title('Currently browsing '); ?>
  </strong><br />
 <?php echo category_description(); ?>
 </p>
 <?php if (have_posts()) : ?>
   <?php while (have_posts()) : the_post(); ?>
     <div class="post">
      <h2 id="post-<?php the_ID(); ?>">
<a href="<?php the_permalink() ?>" rel="bookmark" title="Permanent Link to <?php the_title(); ?>">
<?php the_title(); ?></a></h2>
   <small>
     <?php the_time('F jS, Y') ?> 
        <!-- by <?php the_author() ?> -->
   </small>
 </div>
<?php endwhile; ?>
 <div class="navigation">
   <div class="alignleft">
    <?php posts_nav_link('','','&laquo; Previous Entries') ?>
   </div>
   <div class="alignright">
    <?php posts_nav_link('','Next Entries &raquo;','') ?>
   </div>
 </div>
<?php else : ?>
  <h2 class="center">Not Found</h2>
<p class="center"><?php _e("Sorry, but you are looking for something that isn't here."); ?></p>
 <?php endif; ?>
</div>
<?php get_sidebar(); ?>
<?php get_footer(); ?>

不同分类不同格式

As explained in the Template Hierarchy, it is possible to create separate template files for each category. Simply name the file category-X.php, where X is the numerical ID of the category. Consider carefully whether you need a whole new template for a specific category.

Let's look at two categories, "Plants" and "Flowers", with category IDs 3 and 4, respectively. Next to each post title in the output you want to have picture of either a plant, or a flower, depending on which category is being displayed. You could:

  • Use two separate files, category-3.php and category-4.php, each with a different img tag for each post title.
  • Use a conditional test inside your default category.php file to check whether the current category is "Plants" or "Flowers" (or neither), and display the appropriate image:
<?php if (is_category('3') ):
 // we're in the Plants category, so show a plant ?>
 <img src='/images/plant.png' alt='a plant' />
<?php } elseif (is_category('4') ):
 // we're in the Flowers category, so show a flower ?>
 <img src='/images/flower.png' alt='a pretty flower' />
<?php endif; // end the if, no images for other other categories ?>

If you added another category, "Cars", which you wanted to display in a significantly different way, then a separate category-X.php would be more appropriate.

不同分类不同的CSS样式

Many users want to create separate CSS files for a specific category. This, too, can be easily accomplished. It is important to remember that stylesheets are defined and loaded in the <head> section of the HTML document. WordPress uses the header.php file for this. In the default header.php, find this line:

<link rel="stylesheet" href="<?php bloginfo('stylesheet_url'); ?>" type="text/css" media="screen" />

And change it to something like this:

<?php if ( is_category('5') ) { // Load special CSS for "Cars" category ?>
  <link rel="stylesheet" href="<?php bloginfo('template_url'); ?>/category-5.css" type="text/css" media="screen" />;
<?php } else { ?>
   <link rel="stylesheet" href="<?php bloginfo('stylesheet_url'); ?>" type="text/css" media="screen" />
<?php } ?>

Note: The Cars template uses the category-5.css file to override the default layout. In this example the CSS file is named after the category template file to which it will be applied, rather than the actual name of the category. Thus, you know that category-5.css goes with category-5.php.

不同的单文章格式

When viewing any single post (or permalink), WordPress will use single.php, if present.

This portion, from the WordPress default single.php, provides the post meta data information about the current post:

<p class="postmetadata alt">
<small>
This entry was posted on <?php the_time('l, F jS, Y') ?> at <?php the_time() ?> 
and is filed under <?php the_category(', ') ?>.
You can follow any responses to this entry through 
the <?php comments_rss_link('RSS 2.0'); ?> feed.
<?php
if (('open' == $post->comment_status) && ('open' == $post->ping_status)) {
// Both Comments and Pings are open
?>
  You can <a href="#respond">leave a response</a>, or 
  <a href="<?php trackback_url(display); ?>">trackback</a> 
from your own site.
<?php 
} elseif (!('open' == $post->comment_status) && ('open' == $post->ping_status)) {
// Only Pings are Open 
?>
  Responses are currently closed, but you can 
  <a href="<?php trackback_url(display); ?> ">trackback</a> 
from your own site.
<?php
} elseif (('open' == $post->comment_status) && !('open' == $post->ping_status)) { 
// Comments are open, Pings are not 
?>
  You can skip to the end and leave a response. Pinging is currently not allowed.
<?php
} elseif (!('open' == $post->comment_status) && !('open' == $post->ping_status)) { 
// Neither Comments, nor Pings are open 
?>
  Both comments and pings are currently closed.
<?php 
} 
edit_post_link('Edit this entry.','',''); ?>
</small>
</p>

This sort of information -- whether comments are open or closed -- is largely inappropriate on an index, archive, or category view; which is why it's only included in the single.php template file.

其它循环技巧

Now that you have a good introduction to the basic uses for the WordPress Loop, let's introduce you to some more Loop effects and tricks.

静态首页

如何做到使某些特殊的内容显示在首页?没错,仅显示在首页,而不是你网站上任何其他的页面。非常简单!这我们称之为静态首页。 你网站的首页或第一页并非是真正静态的,而是通过循环使之看起来那样。

为了做到这点,我们使用条件模板标签is_home()

index.php, 使用 if() 判断来选择性的输出额外的内容:

<?php get_header(); ?>
<?php if (is_home()) {
 // we're on the home page, so let's show a picture of our new kitten!
 echo "<img src='/images/new_kitty.jpg' alt='Our new cat, Rufus!' />";
 // and now back to our regularly scheduled home page
} ?> 

当访问者请求的不是某一个文章、页面、分类或日期时,函数 is_home() 才会返回true。于是乎以上内容将仅显示在首页。

要了解更多,请查看 创建静态首页.

只显示摘要

The easiest way to display excerpts, instead of the full content, of posts, replace all instances of the_content() with the_excerpt(). If you have not created explicit excerpts for your posts, this function will automatically display the first 55 words of the post.

<div class="entry">
<?php the_excerpt(); ?>
</div>

依靠文章编号显示摘要或全文

In some circumstances, for example on archive pages, you may want to show the full post if there is only one post or excerpts if there are multiple posts. You can customize the loop to do this.

<?php if (have_posts()) : ?>

  <?php if (($wp_query->post_count) > 1) : ?>
     <?php while (have_posts()) : the_post(); ?>
       <!-- Do your post header stuff here for excerpts-->
          <?php the_excerpt() ?>
       <!-- Do your post footer stuff here for excerpts-->
     <?php endwhile; ?>

  <?php else : ?>

     <?php while (have_posts()) : the_post(); ?>
       <!-- Do your post header stuff here for single post-->
          <?php the_content() ?>
       <!-- Do your post footer stuff here for single post-->
     <?php endwhile; ?>

  <?php endif; ?>

<?php else : ?>
     <!-- Stuff to do if there are no posts-->

<?php endif; ?>

不同的顶栏边栏底栏

WordPress offers the get_header(), get_sidebar(), and get_footer() Include Tags for use in your template files. These functions make it easy to define a standard header/sidebar/footer which is easily editable. Any changes made to these files will immediately be made visible to viewers, without any work on your part.

But sometimes you might not want a sidebar. If you don't want a sidebar, simply exclude the call to the get_sidebar() function from your template. For example, the single.php template in the WordPress default theme does not include a sidebar.

To create your own different sidebar, you have two choices:

  1. Include the sidebar contents directly into the template file on which you're working. If you want category-3 to have a different sidebar, edit category-3.php and include the necessary HTML and PHP to generate your distinctive sidebar.
  2. Use the PHP include function, to include another file. The WordPress get_sidebar() function only loads sidebar.php. If you make a file named sideleft.php, you would include it like this:
<?php include(TEMPLATEPATH . '/sideleft.php'); ?>

In Wordpress Version 2.5 and above you can also call a sidebar like this:

<?php get_sidebar('right'); ?>

This causes the template TEMPLATEPATH . 'sidebar-right.php' to be included.

Using the WordPress default Template Hierarchy, if you want to use the same elements on multiple or different templates, it's probably best to put them in separate template files and use the PHP include() function. If the element you're adding is specifically for one template file, it's probably best to include it directly in that template file.

综述

我们刚刚大致了解了如何处理循环。提醒一下,下面是能帮助你自定义你自己WordPress Loop的资源。