Codex

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

es:The Loop in Action

El Bucle (The Loop) en acción


Introducción

"El Bucle (The Loop)" es un término que se refiere al proceso principal de WordPress. Ud. hace uso de "El Bucle" en sus Archivos de Plantilla para mostrar los artículos a los visitantes. Puede crear Plantillas sin El Bucle, pero podrá mostrar datos solamente de un artículo.

La primera cosa que hace WordPress es comprobar que todos los archivos que necesita estén presentes. Luego, colecta desde la Base de Datos los valores predeterminados definidos por el administrador del blog. Esto incluye cosas como el número de artículos a mostrar por página, si los comentarios están activados y cosas similares. Una vez que estos valores quedan establecidos, WordPress comprueba para ver que es lo que ha solicitado el usuario. Esta información es usada para determinar cuales artículos recuperar de la Base de Datos.

Si el usuario no solicitó un artículo, categoría, página o fecha específica, WordPress utiliza los valores predeterminados recolectados previamente para determinar cuales artículos preparar para el usuario. Por ejemplo, si el administrador del blog ha elegido mostrar 5 artículos por página, entonces WordPress recuperará los cinco artículos más recientes de la Base de Datos. Si el usuario solicitó un artículo, categoría, página o fecha específica, entonces WordPress usará esa información para especificar cual(es) artículo(s) recuperar de la Base de Datos.

Una vez realizado todo esto, WordPress se conecta a la Base de Datos, recupera la información especificada y almacena los resultados en una variable. Es el Bucle quien accesa esta variable y utiliza los valores para mostrarlos en sus plantillas.

De manera predeterminada, si el visitante no seleccionó ningún artículo, categoría, página o fecha específica, WordPress usa la plantilla index.php para mostrar todo. Para la primera parte de esta discusión acerca del Bucle nos enfocaremos solamente en index.php y la apariencia predeterminada del blog. Más adelante, una vez comprenda como funcionan las cosas, investigaremos algunos trucos con El Bucle en otros Archivos de Plantilla.

La Página Index más Sencilla del Mundo

La siguiente es una página index totalmente funcional que mostrará el contenido (y solamente el contenido) de cada artículo, de acuerdo a las condiciones usadas para preparar El Bucle (The Loop). El único propósito de mostrárselo es demostrarle lo poco realmente necesario para el funcionamiento del Bucle. La mayoría de los elementos en su index.php son declaraciones CSS, HTML, y PHP para hacer que El Bucle luzca atractivo.

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

Ahora, echemos un vistazo al grueso de los elementos que hacen que El Bucle se vea atractivo.

El Bucle Predeterminado

La siguiente es una mirada paso-a-paso al uso predeterminado del Bucle que viene con los temas predeterminado y clásico en la instalación estándar de WordPress v1.5.

Inicio del Bucle

En la parte superior del archivo de plantilla predeterminado index.php se encuentra el código de inicio de El Bucle.

<?php if (have_posts()) : ?><br />
<?php while (have_posts()) : the_post(); ?>
  1. Primero comprueba si se recolectó algún artículo con la función have_posts().
  2. Si hay algún artículo, un bucle while de PHP es iniciado. El bucle while continuará ejecutándose mientras la condición en el paréntesis sea true. Por lo que mientras la función have_posts() retorne un valor true, El Bucle seguirá ejecutándose.
  3. La función have_posts() simplemente comprueba el siguiente item en la colección de artículos: si hay algún otro item, retorna true; si no hay un item a continuación, retorna false.

Generando el Artículo

La función the_post() toma el elemento actual en la colección de artículos y lo hace disponible para el uso dentro de esta iteración del Bucle. Sin the_post(), muchas de las Etiquetas de Plantilla usadas en su tema no funcionarían.

Una vez que los datos del artículo se hacen disponibles, la plantilla puede comenzar a mostrar los datos del artículo al visitante.

Título, Fecha y Autor

Las siguientes etiquetas de plantilla obtienen el título del artículo actual, así como la fecha y hora en que fue publicado y quien lo publicó.

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

Contenido del Artículo

La etiqueta de plantilla the_content() muestra el contenido del artículo. Esta es la carne en cada pasada a través del Bucle:

<div class="entry">
<?php the_content('Leer el resto de este artículo &raquo;'); ?>
</div>

Si incluye el botón Quicktag llamado más, mostrado como <!--más-->, en el cuerpo de su artículo, sólo la porción sobre esa línea será mostrada a los lectores. Por lo tanto, si quiere que su página de inicio muestre sólo las primeras dos oraciones de cada artículo, inserte simplemente <!--más--> luego de la segunda línea en cada artículo que cree.

Cuando ve el artículo individual, el delimitador <!-- más --> es obviado. Por consiguiente, colocar el delimitador <!-- más--> en todos sus artículos fuerza a los lectores a hacer click en cada artículo individual si desean leer el artículo completo.

Detalles adicionales

Debajo del contenido de cada artículo en el archivo de plantilla index.php hay un lugar para mostrar más información acerca del artículo, como las información de categorías, fecha y comentarios. Conocida como la sección de meta datos del artículo, si ha ingresado como usuario con suficientes privilegios (o como autor del artículo), también verá un enlace "Editar", gracias a la función de etiqueta de plantilla edit_post_link().

<p class="postmetadata">
Publicado en <?php the_category(', ') ?> 
<strong>|</strong>
<?php edit_post_link('Edit','','<strong>|</strong>'); ?>  
<?php comments_popup_link('Sin Comentarios »', '1 Comentario »', '% Comentarios »'); ?></p>

Si los comentarios se encuentran activados o si el artículo tiene comentarios, la etiqueta de plantilla comments_popup_link() mostrará un enlace a los comentarios. Si está usando la ventana emergente de comentarios, este enlace abrirá la ventana de comentarios; de otra manera irá directo a los comentario de este artículo.

Si el visitante está viendo un índice de artículos (ej.: más de un artículo en el Bucle), el enlace comments_popup_link() llevará al lector a la página individual de este artículo.

Autodetección de Trackback

La función de la etiqueta de plantilla trackback_rdf es retornar código legible para la máquina usado para la auto-detección de trackback.

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

Nota: Es de esperar que la etiqueta trackback_rdf() se utilice con comentarios alrededor. Esto no significa que está "desactivada".

Finalizando El Bucle

La siguiente instrucción finaliza el Bucle. Después de esto, las distintas etiquetas de plantilla relacionadas con el artículo no funcionarán como se espera (o si lo hacen, utilizarán el último artículo del Bucle). Esto significa, que si necesita usar una etiqueta de plantilla que funciona Dentro de El Bucle, necesita colocarla antes de este punto.

<?php endwhile; ?>

Esta sección, inmediatamente posterior al final del Bucle, muestra controles de navegación para desplazarse hacia adelante y hacia atrás por cada página web.

<div class="navigation">
<div class="alignleft"><?php posts_nav_link('','','&laquo; Artículos Anteriores')?></div>
<div class="alignright"><?php posts_nav_link('','Artículos Siguientes &raquo;','')?></div></div>

Si se configura el blog para que muestre 10 artículos por página y las condiciones usadas por el Bucle recuperan 25 artículos, habrá tres páginas para navegar: dos páginas de 10 artículos cada una y una página de 5 artículos. Los enlaces de navegación le permitirán al visitante desplazarse hacia adelante y hacia atrás a través de la colección de artículos.

Los controles de navegacón son incluidos fuera del Bucle, pero dentro de la condición if, de manera que sólo se muestran si hay algún artículo. Las funciones de navegación comprueban por sí mismas si hay o no algo a lo que deben enlazar basándose en el Bucle actual y sólo muestran enlaces si hay algo a que enlazar.

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

La cláusula else : determina que hacer si have_posts() es false. Esto quiere decir, que los elementos que se encuentren luego del else sólamente serán ejecutados/mostrados si El Bucle no tiene ningún artículo. Ningún artículo se mostrará si, por ejemplo, el visitante solicitó un día específico en el cual no se creó ningún artículo o una búsqueda realizada no arrojó resultados.

  <?php endif; ?>

Esta instrucción finaliza la prueba condicional de "Si hay artículos haz esto, si por el contrario, no hay artículos, haz esto". Una vez la prueba condicional es finalizada, la plantilla predeterminada index.php incluye a continuación la barra lateral y finalmente el pie de página.

El Bucle en otras Plantillas

WordPress puede utilizar diferentes archivos de plantilla para mostrar su blog de diferentes maneras. En el tema predeterminado de WordPress hay archivos de plantilla para la vista principal, vista de categoría y vista de archivo, así como una plantilla para ver los artículos individualmente. Cada una de ellas utiliza El Bucle, pero lo hace con un formato ligeramente diferente, así como también con diferentes usos de las etiquetas de plantilla.

Para cualquiera de las vistas que no tenga un archivo de plantilla separado, WordPress usará index.php de manera predeterminada. Si un visitante solicita un artículo individual, WordPress primero buscará un archivo llamado single.php. Si ese archivo existe, será utilizado para presentar el artículo al visitante. Si ese archivo no existe, WordPress utilizará index.php para presentar el artículo al visitante. Esto es llamado Jerarquía de Plantillas.

Si está creando su propio Tema, con frecuencia es muy útil revisar los archivos de plantilla del Tema predeterminado como punto de referencia. También es útil usar el archivo index.php de su tema como plantilla para sus otros archivos de plantilla. Hacer esto puede proporcionarle una página conocida y funcional desde la cual comenzar a realizar cambios para crear más archivos de plantilla.

Formato de Archivo Diferente

Un archivo es una colección histórica de artículos. De manera predeterminada, los artículos mostrados en su página de inicio son los artículos cronológicamente más recientes. Cuando un visitante hace click en uno de los enlaces de su archivo, o si solicita manualmente una fecha específica (http://www.example.com/blog/index.php?m=200504 o http://www.example.com/blog/2005/04 para seleccionar todos los artículos de Abril de 2005), WordPress mostrará una vista de archivo. De manera predeterminada, el archivo utilizará index.php y por lo tanto lucirá igual a su página de inicio, pero mostrará sólamente los artículos de Abril de 2005.

Cuando WordPress prepara una vista de archivo para un visitante, busca específicamente un archivo llamado archive.php en el directorio de su tema actual. Si desea eliminar ambiguedades visuales entre el archivo y su página de inicio, simplemente copie index.php y renómbrelo a archive.php y edite archive.php como sea necesario.

Por ejemplo, si desea mostrar solamente los títulos y no el contenido de los artículos para su lista de archivos, podría utilizar algo parecido a lo siguiente:

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

Formato de Categorías Diferente

Como con la vista de archivo, WordPress busca un archivo de plantilla separado para la vista de categoría. Si un visitante hace click en un enlace de una categoría en su blog, será llevado a la vista categoría. WordPress preparará El Bucle sólamente con los artículos de esa categoría, limitando el número de artículos indicados en la configuración establecida para el blog.

Para hacer su vista de categorías diferente de su vista principal, copie index.php y renómbrelo como category.php. Para una vista de categoría probablemente no es necesario listar las categorías a las cuales está asignado un artículo, por lo que vamos a remover esa sección. En su lugar, anunciaremos la categoría en la parte superior de la página:

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

Diferentes Formatos para Diferentes Categorías

Como se explica en la Jerarquía de Plantillas, es posible crear archivos de plantilla separados para cada categoría. Simplemente nombre el archivo category-X.php, donde X es el ID numérico de la categoría.

Considere cuidadosamente si necesita una plantilla totalmente nueva para una categoría específica. Veamos dos categorías, "Plantas" y "Flores", con los IDs 3 y 4, respectivamente. Junto al título de cada articulo Ud. quiere tener una imagen de una planta o una flor, dependiendo de que categoría está siendo mostrada. Ud. podría:

  • Usar dos archivos separados, category-3.php y category-4.php, cada uno con una etiqueta img diferente para cada título del artículo.
  • Usar un condicional dentro de su archivo category.php para comprobar si la categoría actual es "Plantas" o "Flores" (o ninguna) y mostrar la imagen adecuada:
<?php if (in_category('3') ):
 // we're in the Plants category, so show a plant ?>
 <img src='/images/plant.png' alt='a plant' />
<?php } elseif (in_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 ?>

Si añadió otra categoría "Carros" que quería mostrar de una manera significativamente diferente, sería más adecuado un archivo category-X.php separado.

Diferentes Hojas de Estilo CSS Para Diferentes Categorìas

Muchos usuarios quieren crear archivos CSS separados para una categoría específica. Esto, también puede lograrse fácilmente. Es importante recordar que las hojas de estilo son definidas y cargadas en la sección <head> del documento HTML. WordPress usa el archivo header.php para esto. En el archivo header.php predeterminado, busque esta línea:

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

Y cámbiela a algo así:

<?php if ( in_category('5') ) { // Carga una Hoja de Estilos CSS especial para la categoría "Carros"  ?>
  <link rel="stylesheet" href="<?php get_template_directory(); ?>/category-5.css" type="text/css" media="screen" />
<?php } else { ?>
   <link rel="stylesheet" href="<?php bloginfo('stylesheet_url'); ?>" type="text/css" media="screen" />
<?php } ?>

Nota: La plantilla Carros usa el archivo category-5.php para cambiar el diseño predeterminado. En este ejemplo se le da nombre al archivo CSS dependiendo del archivo de plantilla de categoría al cual será aplicado, en lugar de el nombre real de la categoría. Por lo tanto, Ud. sabe que category-5.css pertenece a category-5.php.

Formato de Artículo Individual Diferente

Cuando visualiza un artículo individual (o permalink), WordPress utilizará single.php, si está presente. Esta porción, del archivo predeterminado de WordPress single.php, proporciona la información de meta datos del artículo del artículo actual:

<p class="postmetadata alt">
<small>
Este artículo fue publicado el <?php the_time('l, F jS, Y') ?> a la(s) <?php the_time() ?> 
y se encuentra archivado en las categorías <?php the_category(', ') ?>.
Puede hacer seguimiento a los comentarios de este artículo mediante el canal <?php comments_rss_link('RSS 2.0'); ?>.
<?php
if (('open' == $post->comment_status) && ('open' == $post->ping_status)) {
// Tanto los Comrentarios como los Pings están activados
?>
  Puede <a href="#respond">dejar un comentario</a>, o 
  <a href="<?php trackback_url(display); ?>">trackback</a> 
desde su propio sitio.
<?php 
} elseif (!('open' == $post->comment_status) && ('open' == $post->ping_status)) {
// Sólo los Pings están activados 
?>
  Los comentarios se encuentran actualmente desactivados, pero puede 
  <a href="<?php trackback_url(display); ?> ">trackback</a> 
desde su propio sitio.
<?php
} elseif (('open' == $post->comment_status) && !('open' == $post->ping_status)) { 
// Los comentarios están activados, pero los Pings están desactivados 
?>
  Puede ir al final del artículo y dejar un comentario. Los Pings están actualmente desactivados.
<?php
} elseif (!('open' == $post->comment_status) && !('open' == $post->ping_status)) { 
// Ni los Comentarios ni los Pings están activados 
?>
  Tanto los Comentarios como los Pings están desactivados actualmente.
<?php 
} 
edit_post_link('Edit this entry.','',''); ?>
</small>
</p>

Este tipo de información -- tanto si los comentarios están activados o desactivados -- es inadecuado en una página de vista principal, de archivo o de categoría; lo que explica por qué sólamente se incluyó en el archivo de plantilla single.php.

Otros Trucos del Bucle

Ahora que ha tenido una buena introducción a los usos básicos del Bucle de WordPress, le presentaremos efectos y trucos adicionales del Bucle.

Página Inicial Fija

¿Puede mostrar algo especial sólamente en la página de inicio de su blog? Eso es correcto, solamente en la página de inicio o página principal y puede hacer que no se muestre en ninguna otra parte en su sitio. ¡Fácil! Nosotros llamamos a esto página inicial fija. El inicio de la primera página de su sitio realmente no es fija. Solamente está usando El Bucle para hacerla ver de la manera que se ve.

Para hacer que este truco funcione, use la función de etiqueta de plantilla conditional is_home().

En su archivo index.php, use un if () para retornar contenido adicional condicionalmente:

<?php get_header(); ?>
<?php if (is_home()) {
 // Estamos en la Página de Inicio, entonces ¡mostremos una foto de nuestro gatito!
 echo "<img src='/images/new_kitty.jpg' alt='Nuestro nuevo gato, Rufus!' />";
 // y ahora regresamos a nuestra página de inicio regular
} ?> 

La función is_home() sólo producirá un valor true si el visitante no está solicitando un artículo, categoria o fecha específica, por lo que sólo se muestra en la "página de inicio".

Para mayor información, lea Creando una Página de Inicio Fija.

Sólamente Extractos

La manera más fácil de mostrar extractos, en lugar del contenido completo de los artículos, es reemplazar todas las instancias de the_content() con the_excerpt().

Si no ha creado extractos expecíficamente para sus artículos, esta función automáticamente mostrará las primeras 120 palabras del artículo.

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

Diferentes Encabezados/Barras Laterales/Pies de Página

WordPress proporciona las Etiquetas de Inclusión get_header(), get_sidebar() y get_footer() para usarlas en sus archivos de plantilla. Estas funciones hacen fácil definir un encabezado/barra lateral/pie de página estándar que sea fácilmente editable. Cualquier cambio realizado a estos archivos inmediatamente se hará visible a los usuarios, sin ningún trabajo de su parte.

Pero a veces, puede que no quiera una barra lateral. Si no quiere una barra lateral, simplemente excluya el llamado a la función get_sidebar() de su plantilla. Por ejemplo, la plantilla single.php en el tema predeterminado de WordPress no incluye una barra lateral.

Para crear su propia barra lateral diferente, tiene dos opciones.

  1. Incluir el contenido de la Barra Lateral directamente en el archivo de plantilla en el que está trabajando. Si desea que category-3 tenga una barra lateral diferente, edite category-3.php e incluya el HTML y PHP necesario para generar su propia barra lateral.
  2. Usar la función PHP include para incluir otro archivo. La función get_sidebar() de WordPress sólo carga sidebar.php. Si crea un archivo llamado sideleft.php, debería incluirlo de la siguiente manera:
<?php include(TEMPLATEPATH . '/sideleft.php'); ?>

Basándose en la Jerarquía de Plantillas predeterminada de WordPress, si quiere utilizar los mismos elementos en múltiples o diferentes plantillas, probablemente es mejor colocarlas en archivos de plantilla separados y utilizar la función PHP include(). Si el elemento que está añadiendo es específico para un archivo de plantilla, probablemente es mejor incluirlo directamente en el archivo de plantilla.

Resúmen

Sólamente hemos explorado la superficie de lo que puede hacerse con El Bucle. Como recordatorio, los siguientes son recursos que le ayudarán a personalizar su propio Bucle de WordPress.