Page d'accueil du Codex en français - Télécharger WordPress en français
Les utilisateurs francophones se retrouvent sur le site WordPress-Francophone, notamment sur son forum d'entraide.
"The Loop" ou "La Boucle" est un terme qui se réfère au processus principal de WordPress. Vous utilisez la boucle dans vos fichiers de modèle (template) pour afficher vos articles (posts) aux visiteurs. Vous pouriez créer des modèles sans boucle, mais vous ne pourriez alors n'afficher les données que d'un seul article.
La première chose que WordPress fait est de vérifier que tous les fichiers dont il a besoin sont présents.
Ensuite, il collecte les paramètres par défaut définis par les administrateurs du blog, depuis la base de données. lesquels incluent certaines données telles que: le nombre d'articles à afficher par pages, si les commentaires sont autorisés ou non, et d'autres, et qui détermineront la façon dont les articles seront affichés.
Une fois que ces paramètres sont définis, WordPress vérifie ce que le visiteur recherche, afin de déterminer quels articles extraire de la base de données.
Si le visiteur n'a pas demandé un article, une catégorie, une page, ou une date spécifique, WordPress utilise les paramètres par défaut précédemment collectées pour déterminer quels articles préparer pour le visiteur.
Par exemple: si l'administrateur du blog a choisi d'afficher 5 articles par page dans Administration > Réglages > Lecture, alors WordPress extrait les 5 derniers articles publiés de la base de donnée.
Si le visiteur a fait la demande d'un article, une catégorie, une page, ou une date spécifique, alors WordPress utilise ces informations pour savoir quel(s) article(s) extraire.
Une fois cela fait, WordPress se connecte à la base de données, récupère les informations spécifiées, et range les valeurs dans une variable. C'est La Boucle qui accède à cette variable, et utilise les valeurs à afficher dans votre modèle.
Par défaut, si le visiteur n'a pas fait de recherche sur un article, une catégorie, une page, ou une date spécifique, WordPress utilise index.php pour tout afficher.
Dans la première partie de cette discussion sur La Boucle, nous allons nous attarder sur index.php, et l'affichage par défaut de votre blog.
Plus loin, une fois que vous aurez compris comment tout cela fonctionne, nous examinerons quelques astuces avec La Boucle dans d'autres modèles.
Le code suivant est un index totalement fonctionnel qui affichera le contenu (et seulement le contenu) de chaque article, en accord avec les conditions dictées pour la préparation de La Boucle.
Le but ici est de démontrer que très peu de code est nécessaire au fonctionnement de La Boucle. Le plus gros de votre index.php réside dans les déclarations CSS, HTML et PHP qui habillent La Boucle.
<?php
get_header();
if (have_posts()) :
while (have_posts()) :
the_post();
the_content();
endwhile;
endif;
get_sidebar();
get_footer();
?>
Maintenant, jetons un œil à tout ce qui va habiller votre Boucle.
Le détail suivant regarde l'utilisation par défaut de La Boucle dans les thèmes Default et Classic de l'installation par défaut de WordPress.
Le code d'initialisation de La Boucle est situé au début du fichier de modèle (template) index.php par défaut.
<?php if (have_posts()) : ?><br /> <?php while (have_posts()) : the_post(); ?>
La fonction the_post() prends l'item courant dans la collection d'articles et rends celui-ci utilisable dans l'itération de La Boucle. Sans la fonction the_post() certains des marqueurs de modèle (template tags) utilisé dans votre thène ne fonctionnerait pas.
Une fois que les données de l'article sont accessibles, le modèle (template) peut commencer l'affichage de ces données au visiteur.
Les template tags ou marqueurs de modèle suivants récupèrent le titre de l'article courant, ainsi que sa date de publication et l'auteur de celui-ci.
<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>
Le marqueur de modèle the_content() affiche le contenu de l'article. C'est l'essentiel de chaque passage dans la boucle:
<div class="entry">
<?php the_content('Read the rest of this entry »'); ?>
</div>
Si vous incluez le bouton du marqueur rapide (Quicktag) nommé more (ou "Lire la suite" ou "En savoir plus" ou autre en fonction de la traduction de votre modèle), dont la syntaxe est <!--more-->, après une ligne dans le corps d'un article, seule la portion au dessus de cette ligne sera affichée au visiteur.
Donc, si vous voulez par exemple que votre page d'accueil n'affiche que la première ligne de chaque article que vous écrivez, insérez simplement <!--more--> après la première ligne de texte de chacun.
Lorsqu'un article est affiché seul, il l'est en entier et le délimiteur <!-- more --> est omis.
Ce qui implique qu'insérer le délimiteur <!-- more --> dans chacun de vos articles forcera le lecteur à cliquer sur chaque entrée d'article pour pouvoir en lire l'intégralité.
La Boucle sert également à afficher des informations complémentaires aux articles, comme les catégories, la date, ou encore les commentaires. Ces informations sont appelées les méta-données de l'article et la zone où elles sont affichées : Zone de méta-données de l'article (post meta data section en anglais). Si vous êtes un utilisateur connecté avec des droits suffisants ou l'auteur de l'article en question, vous pouvez également voir affiché un lien "Modifier" grâce au marqueur de modèle edit_post_link().
<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>
Si les commentaires sont ouverts, ou si l'article a déjà été commenté, le marqueur de modèle comments_popup_link() affichera un lien vers les commentaires. Si vous utilisez le marqueur de modèle comments popup window, le lien généré affichera les commentaires dans une fenêtre popup, sinon le navigateur sautera directement à l'emplacement des commentaires sur la page de l'article.
Si le visiteur consulte une liste d'articles (une page d'archive par exemple), le lien généré par le marqueur de modèle comments_popup_link() l'amènera sur la page individuelle de l'article.
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".
<?php endwhile; ?>
Ce code termine la Boucle. Après cela, tous les marqueurs de modèles relatifs aux articles ne fonctionneront plus comme vu plus haut (ou si ils fonctionnent, ils utiliseront les données du dernier article passé dans la Boucle). Ceci signifie que si vous avez besoin d'utiliser un marqueur de modèle qui fonction within The Loop (dans la Boucle) il faudra le placer avant ce point du code.
Immédiatement après la fin de la Boucle vous trouvez la section qui affiche les contrôles de navigation permettant d'accéder aux pages des articles plus récents (next) ou plus anciens (previous).
<div class="navigation">
<div class="alignleft"><?php posts_nav_link('','','« Previous Entries') ?></div>
<div class="alignright"><?php posts_nav_link('','Next Entries »','') ?></div>
</div>
Si WordPress est configuré pour afficher 10 articles par page (via le menu Réglages/Lecture du panneau d'administration) et que la Boucle doit en afficher 25, alors il y aura 3 pages à parcourir : 2 pages de 10 articles et une page de 5. Les liens de navigation permettront au visiteur de naviguer facilement dans cet ensemble de pages.
Les contrôles de navigation sont placés en dehors de la Boucle, mais au sein de la condition if testant la présence d'article à afficher. Ainsi ces contrôles ne s'afficheront pas si aucun article n'est à afficher.
<?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>
La clause else : précises ce qui doit être affiché si have_posts() est faux (aucun article à afficher). Par exemple un message signifiant au visiteur qu'aucun contenu ne correspond aux critères de sa recherche.
<?php endif; ?>
Ceci termine le test conditionnel "Si il y a des articles à afficher fait ceci, sinon fait cela". Viennent ensuite l'inclusion de la barre latérale (sidebar) et enfin du pied de page (footer).
WordPress can use different template files for displaying your blog in different ways. In the default WordPress theme, there are template files for the index view, category view, and archive view, as well as a template for viewing individual posts. Each of these uses The Loop, but does so with slightly different formatting, as well as different uses of the 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('','','« Previous Entries') ?>
</div>
<div class="alignright">
<?php posts_nav_link('','Next Entries »','') ?>
</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('','','« Previous Entries') ?>
</div>
<div class="alignright">
<?php posts_nav_link('','Next Entries »','') ?>
</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:
<?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.
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.
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.
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 120 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.
<?php include(TEMPLATEPATH . '/sideleft.php'); ?>
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.
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.