Codex

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

Цикл в действии

Эта страница помечена как незавершённая. Вы можете помочь проекту, дополнив её.
(Add your language)

Введение

"Цикл WordPress" (дале-Цикл) является основным процессом WordPress. Вы используете его локально в своих файлах шаблонов[[1]], чтобы показать сообщения для посетителей. Вы можете сделать шаблоны без Цикла, но тогда вы сможете отображать данные только из одной записи.

Перед началом действия Цикла, WordPress проверяет, все ли файлы, необходимые для работы Цикла, присутствуют. После этого он получает настройки по умолчаню, как определено администратором блога, из базы данных.Это включает в себя количество записей(постов),которые будут отображаться на странице, включены ли комментарии, и многое другое.После того, как эти значения устанавлены, WordPress проверяет, что пользователь запросил. Эта информация используется для определения, какие записи необходимо доставить из базы данных на страницу блога.

Если пользователь не запросил конкретной записи(поста), категории, страницы или даты, WordPress использует ранее собранные значения по умолчанию,чтобы определить, какие записи приготовить пользователю.Например, если администратор блога выбрал для отображения 5 сообщений на странице в Administration > Settings > Reading,то WordPress будет получать пять последних записей из базы данных. Если пользователь запросил информацию по конкретной записи, категории, странице, или дате, то WordPress будет использовать эту информацию, чтобы указать, какую(ие) запись(и) выбрать из базы данных.

Когда всё это будет сделано, WordPress подключается к базе данных, извлекает указанную информацию и сохраняет результаты в переменной. Цикл использует значение этой переменной для отображения в шаблонах.

По умолчанию, если посетитель не выбрал определенный пост, страницы, категории, или дату, WordPress использует index.php для отображения всего. Для первой части этого рассказа о Цикле мы сосредоточимся только на index.php, и исполнению по умолчанию вашего блога. Позже, как только вы поймёе, как работают вещи, мы будем исследовать трюки с Циклом в других файлах шаблона.

Простейшая Главная Страница Сайта

Ниже приводится функциональный index file (index.php), который отображает содержимое (и только содержимое) каждого сообщения, в соответствии с условиями, использованными для подготовки Цикла. Этот пример демонстрирует, как мало на самом деле необходимо для функционирования Цикла.

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

Цикл WordPress по умолчанию

Ниже представлен пошаговый обзор использования Цикла по умолчанию,который поставляется с темами "default" и "classic" в стандартной сборке WordPress v1.5.


Начало Цикла

Сначала в верху шаблона по умолчанию, index.php, имеется стартовый код, которым начинается Цикл WordPress

<?php if (have_posts()) : ?>
<?php while (have_posts()) : the_post(); ?>
  1. Во-первых, он проверяет, были ли обнаружены какие-либо записи -- с помощью функции have_posts().
  2. Если были какие-либо сообщения, запускается PHP цикл while . Цикл while будет продолжать выполняться до тех пор, пока условие в скобках логически верно. Так, до тех пор, как функция have_posts () возвращает истинное значение, цикл whileбудет продолжать цикл (повторения). (Функция have_posts() просто проверяет наличие следующего элемента в очереди записей(постов). Если есть следующий элемент, оператор if вновь возвращает ответ 'true' (верно) и оператор while используется вновь. Если нет больше элементов, оператор if возвращает значение 'false' (ложно) и Цикл переходит к те или иным инструкциям после операторов if и while

Формирование записи

Функция the_post() принимает текущий элемент из набора записей и делает его доступным для использования внутри текущего шага Цикла. Без the_post(), много из Template Tags, использующихся в вашей теме, не будут работать.

После того как данная запись становится доступной, шаблон может начать показывать данные записи посетителю.

Название, Дата и Автор

Следующие template tags получают название, время написания и автора текущей записи.

<h2 id="post-<?php the_ID(); ?>">
<a href="<?php the_permalink() ?>" rel="bookmark" title="Permanent Link to <?php the_title_attribute(); ?>">
<?php the_title(); ?></a></h2>
<small><?php the_time('F jS, Y') ?> <!-- by <?php the_author() ?> --></small>

Содержание(контент) записи (поста)

Тег шаблона the_content() выбирает содержание записи,фильтрует (filters) его, и потом выводит на экран. Это мясо и картошка каждого прохода Цикла WordPress:

<div class="entry">
<?php the_content('Read the rest of this entry &raquo;'); ?>
</div>

Как говорится в документации тега the_content(), короткий тег (quicktag) <!--more--> используется для указания фрагментов для тега the_content() для вывода на страницы с несколькими записями. Строка, передаваемая в the_content() используется для ссылки "Читать далее/Read More" после выдержки из записи. Более подробную информацию о выдержках, коротких тегах <!--more--> , и ссылках "Read More/Читать далее" смотрите Template Tags/the_content и Customizing the Read More.

Дополнительно

Секция post meta data section находится под каждой записью в файле шаблона index.php , и используется для вывода дополнительной информации о записи (посте), такой как категория, дата, комментарий. Если размещена функция тегов шаблонов edit_post_link() , то авторизованные пользователи с достаточными (необходимыми) правами ( или автор записи) увидят ссылку " Править здесь/Edit This".

<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>

Если комментирий включен, или если сообщение имеет комментарий, тег шаблона comments_popup_link() выведет ссылку на комментарий. Если вы используете comments popup window, эта ссылка откроет окно комментария; в противном случае ссылка выведет прямо на комментарий этого поста.

Если посетитель просматривает индекс(указатель) записей (т.е.: более одной записи в Цикле), ссылка comments_popup_link() ведёт читателя к отдельной странице этого поста(записи) .

Автоматическое обнаружение 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 intentionally used within an HTML comment; it is not being "turned off". The reason for this is that, otherwise, RDF breaks validation in non-XML documents, and in XHTML documents it is parsed incorrectly by most browsers.

Окончание Цикла

После завершения Цикла WordPress различные связанные с постом теги шаблонов работать не будут (или если будут , они будут использовать последний пост из Цикла). Это значит, что, если вам нужно использовать тег шаблона, который работает 'внутри Цикла', необходимо положить его в Цикл до этого момента:

<?php endwhile; ?>

В этом разделе, сразу после окончания Цикла, выводится панель навигации, чтобы двигаться вперед и назад по веб-странице. Более подробная информация доступна в вызове функции 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>

Если блог настроен на отображение 10 сообщений на странице, а условия, используемые Циклом собрали всего 25 сообщений, то будет три страницы для навигации: две страницы по 10 постов на каждой, а одна страница с 5 постами. Навигационные ссылки позволят посетителю двигаться вперед и назад по собранным постам.


Элементы навигации включены вне Цикла, но внутри условия if(если) , так что они показываются только, если есть какие-либо посты (записи). Навигационные функции сами также проверяют, есть что-то, что можно связать между собой, на основе текущего Цикла, и показывают ссылки , только если есть что связывать.

 <?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>
 

Пункт else : ("иначе") определяет,что делать, если have_posts() (из предыдущей части Цикла) принимает значение false.Код после else будет выполняться/выводиться,только если Цикл имеет "нулевые" посты (нет постов). Нет постов для вывода если,например,посетитель запросил определённую дату, когда посты не создавались, или поиск был выполнен но не дал результатов.

  <?php endif; ?>

На этом заканчивается проверка условия " если есть посты делать это, иначе если нет постов, делать то". После того, как проверка условий заканчивается,в коде шаблона по умолчанию index.php включены sidebar (боковая панель) и в конце footer (подвал).

Цикл WordPress в других шаблонах

WordPress может использовать различные файлы шаблонов для отображения вашего блога различными способами. В предустановленной теме (теме по умолчанию) WordPress , это Шаблоны для вида индекса, вида категории, и вида архива, а также как шаблон для просмотра отдельных постов. Все они используют Цикл WordPress, но делают это с несколько разным форматированием, также по-разному используя Теги_шаблонов.

Для любого вида, который не имеет отдельного файла шаблона, WordPress будет использовать index.php по умолчанию. Если посетитель запросит одно сообщение, WordPress сначала будет искать файл с именем single.php. Если этот файл существует, он будет использоваться, чтобы представить запись для посетителя. Если этот файл не существует, WordPress будет использовать index.php для представления записи посетителю. Это называетсяИерархия_шаблонов.

Если вы делаете свою ​​собственную тему, то вам полезно взглянуть на файлы шаблонов из Темы по умолчанию как на точку отсчёта. 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.

Different Archive Format

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_attribute(); ?>"><?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(); ?>

Different Category Format

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_attribute(); ?>">
<?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(); ?>

Different Formats for Different Categories

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.

Different CSS For Different Categories

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.

Different Single Post Format

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 ( comments_open() && pings_open() ) {
// 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 ( !comments_open() && pings_open() ) {
// 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 ( comments_open() && !pings_open() ) { 
// Comments are open, Pings are not 
?>
  You can skip to the end and leave a response. Pinging is currently not allowed.
<?php
} else { 
// 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.

Other Loop Tricks

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.

Static Front Page

How can you display something special only on the front page of your blog? That's right, only on the front page or home page, and have it not be seen anywhere else on your site. Easy! We call this the static front page. The front or first page of your site isn't really static. It's just using the Loop to make it look that way.

To make this Loop trick work, use the is_home() conditional template tag function.

In your index.php, use an if () test to conditionally output additional content:

<?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
} ?> 

The function is_home() will only produce a true value if the visitor is not requesting a specific post, page, category, or date, so it only shows up on the "home" page.

For more information, see Creating a Static Front Page.

Excerpts Only

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>

Showing Excerpts or Full Post Depending Upon Number of Posts

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 предоставляет get_header(), get_sidebar() и get_footer() подключающие теги для использования в ваших файлах шаблонов. Эти функции облегчают процесс подключения стандартных заголовка/боковой панели/футера, которые можно легко отредактировать. Любые изменения, внесенные в эти файлы, будут сразу же видны при просмотре страницы без какой-либо дополнительной работы с вашей стороны.

Но иногда вы не хотите видеть боковую панель. Если вы не хотите боковую панель, тогда просто не добавляйте вызов функции get_sidebar() в своем шаблоне. Например, single.php шаблон в WordPress теме по умолчанию не включает боковую панель.

Для создания своей собственной уникальной боковой панели у вас есть две возможности:

  1. Включите содержимое боковой панели непосредственно в файл шаблона над которым вы работаете. Если вы хотите, чтобы category-3 отображала другую боковую панель, отредактируйте файл category-3.php и добавьте в этот файл необходимый HTML и PHP для создания этой панели.
  2. Используйте PHP include функцию, чтобы подключить другой файл. WordPress get_sidebar() функция подключает только sidebar.php. Если вы создали файл sideleft.php, то можете подключить его следующим образом:
<?php include(TEMPLATEPATH . '/sideleft.php'); ?>

В WordPress Version 2.5 и выше вы можете вызвать функцию как в этом примере:

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

Этот вызов подключает файл TEMPLATEPATH . 'sidebar-right.php'.

Использование WordPress Иерархия шаблонов, если вы хотите использовать один элемент в нескольких разных шаблонах, тогда, скорее всего, наилучшим решением будет поместить его в другой файл и использовать PHP include() функцию для подключения. Если элемент, который вы добавляете, уникальный и используется только в одном файле, тогда, скорее всего, наилучшим решением станет включение элемента непосредственно в этот шаблон.

Summary

We've just scratched the surface of what can be done with the Loop. As a reminder, the following are resources that will help you customize your own WordPress Loop.