10. La plantilla de comentarios de un Tema de WordPress

ThemeShaper es el sitio del Equipo de Temas de Automattic, que, en junio de 2009, publicaron una muy popular serie de 11 artículos de Ian Stewart, bajo el título: How To Create a WordPress Theme: The Ultimate WordPress Theme Tutorial (Como crear un Tema de WordPress: el tutorial definitivo).

El año pasado, reflotaron y actualizaron ese tutorial. Esta vez con 16 artículos a cargo de Michelle Langston: The ThemeShaper WordPress Theme Tutorial: 2^nd Edition (Tutorial de Temas de WordPress de ThemeShaper. Segunda edición).

Me propongo traducir libremente esas 16 entradas (además de la introducción) e ir publicándolas a medida que las tenga listas.
Al final de cada entrada va el listado con todas las entradas de este tutorial.

(El artículo original y en inglés, fue publicado el 4 de noviembre de 2012)

Odio la plantilla de comentarios. Listo, lo dije. Puede ser un entrevero muy confuso.

Afortunadamente, lo he acomodado. Sí, todavía es un lío. Pero lo he acomodado un poco. Para este tutorial sobre la plantilla de comentarios, básicamente, lo vamos a probar para ver que es lo que pasa, le voy a mostrar algunos recortes de código personalizado que va a necesitar agregar a su archivo inc/template-tags.php, y luego le voy a dejar todo el fardo a usted. Con suerte, empezará a tener sentido. Pero, al menos, tendrá una horrible plantilla de comentarios.

Echemos un rápido vistazo a este listado de lo que se hará con esta plantilla.

1. Evitar la carga de la plantilla para los bots y en las entradas protegidas con contraseña.
2. Comprobar si existen comentarios.
3. Distinguir entre los comentarios y los trackbacks / pingbacks de manera que se puedan mostrar los trackbacks con un maquetado más simple. De ahora en más, me referiré a ambos,  trackbacks y pingbacks, como “Pingbacks”.
4. Si existen comentarios, mostrarlos — con navegación para los comentarios paginados.
5. Si los comentarios están abiertos, mostrar el formulario de comentarios «Responder».

Todo esto es un montón para una sola plantilla. Pero escrito de esta manera, es bastante claro.

Retrollamadas personalizadas para Comentarios y Pingbacks

Vamos a utilizar la función wp_list_comments() que, convenientemente, devuelve el código de una lista ordenada de comentarios y pingbacks (también encadenados) para su entrada.

Para hacer que el código de nuestra plantilla de comentarios funcione, va a utilizar una función de retrollamada personalizada, que controla el diseño  de los comentarios y pingbacks existentes. Abra inc/template-tags.php y pegue la siguiente función al final del archivo.

if ( ! function_exists( 'shape_comment' ) ) :
/**
 * Template for comments and pingbacks.
 *
 * Used as a callback by wp_list_comments() for displaying the comments.
 *
 * @since Shape 1.0
 */

function shape_comment( $comment, $args, $depth ) {
	$GLOBALS['comment'] = $comment;
  switch ( $comment->comment_type ) :
  	case 'pingback' :
    case 'trackback' :
?>
	<li class="post pingback">
  	<p><?php _e( 'Pingback:', 'shape' ); ?> <?php comment_author_link(); ?><?php edit_comment_link( __( '(Edit)', 'shape' ), ' ' ); ?></p>
  <?php
  	break;
    default :
  ?>
    <li <?php comment_class(); ?> id="li-comment-<?php comment_ID(); ?>">
    	<article id="comment-<?php comment_ID(); ?>" class="comment">
      	<footer>
        	<div class="comment-author vcard">
          	<?php echo get_avatar( $comment, 40 ); ?>
            <?php printf( __( '%s <span class="says">says:</span>', 'shape' ), sprintf( '<cite class="fn">%s</cite>', get_comment_author_link() ) ); ?>
          </div><!-- .comment-author .vcard -->
          <?php if ( $comment->comment_approved == '0' ) : ?>
            <em><?php _e( 'Your comment is awaiting moderation.', 'shape' ); ?></em>
            <br />
          <?php endif; ?> 
          <div class="comment-meta commentmetadata">
            <a href="<?php echo esc_url( get_comment_link( $comment->comment_ID ) ); ?>"><time pubdate datetime="<?php comment_time( 'c' ); ?>">
            <?php
              /* translators: 1: date, 2: time */
              printf( __( '%1$s at %2$s', 'shape' ), get_comment_date(), get_comment_time() ); ?>
            </time></a>
            <?php edit_comment_link( __( '(Edit)', 'shape' ), ' ' );
            ?>
          </div><!-- .comment-meta .commentmetadata -->
        </footer> 
        <div class="comment-content"><?php comment_text(); ?></div> 
        <div class="reply">
          <?php comment_reply_link( array_merge( $args, array( 'depth' => $depth, 'max_depth' => $args['max_depth'] ) ) ); ?>
        </div><!-- .reply -->
      </article><!-- #comment-## --> 
    <?php
    break;
    endswitch;
	}
endif; // ends check for shape_comment()

if ( ! function_exists( 'shape_comment' ) ) :
/**
 * Template for comments and pingbacks.
 *
 * Used as a callback by wp_list_comments() for displaying the comments.
 *
 * @since Shape 1.0
 */

function shape_comment( $comment, $args, $depth ) {
	$GLOBALS['comment'] = $comment;
  switch ( $comment->comment_type ) :
  	case 'pingback' :
    case 'trackback' :
?>
	<li class="post pingback">
  	<p><?php _e( 'Pingback:', 'shape' ); ?> <?php comment_author_link(); ?><?php edit_comment_link( __( '(Edit)', 'shape' ), ' ' ); ?></p>
  <?php
  	break;
    default :
  ?>
    <li <?php comment_class(); ?> id="li-comment-<?php comment_ID(); ?>">
    	<article id="comment-<?php comment_ID(); ?>" class="comment">
      	<footer>
        	<div class="comment-author vcard">
          	<?php echo get_avatar( $comment, 40 ); ?>
            <?php printf( __( '%s <span class="says">says:</span>', 'shape' ), sprintf( '<cite class="fn">%s</cite>', get_comment_author_link() ) ); ?>
          </div><!-- .comment-author .vcard -->
          <?php if ( $comment->comment_approved == '0' ) : ?>
            <em><?php _e( 'Your comment is awaiting moderation.', 'shape' ); ?></em>
            <br />
          <?php endif; ?> 
          <div class="comment-meta commentmetadata">
            <a href="<?php echo esc_url( get_comment_link( $comment->comment_ID ) ); ?>"><time pubdate datetime="<?php comment_time( 'c' ); ?>">
            <?php
              /* translators: 1: date, 2: time */
              printf( __( '%1$s at %2$s', 'shape' ), get_comment_date(), get_comment_time() ); ?>
            </time></a>
            <?php edit_comment_link( __( '(Edit)', 'shape' ), ' ' );
            ?>
          </div><!-- .comment-meta .commentmetadata -->
        </footer> 
        <div class="comment-content"><?php comment_text(); ?></div> 
        <div class="reply">
          <?php comment_reply_link( array_merge( $args, array( 'depth' => $depth, 'max_depth' => $args['max_depth'] ) ) ); ?>
        </div><!-- .reply -->
      </article><!-- #comment-## --> 
    <?php
    break;
    endswitch;
	}
endif; // ends check for shape_comment()

Permítanme explicar con más detalle qué es lo que está pasando aquí. Primero, este código se repite para cada comentario o trackback que tengamos. En las líneas 131-134, utilizamos una sentencia switch de php, que es similar a las sentencias if… else. Dicho de forma sencilla, las sentencias switch le permiten determinar primero el valor de una variable y mostrar códigos diferentes dependiendo del valor de la misma.

En español, en nuestra plantilla de comentarios, la sentencia switch dice: “en el caso de que este comentario en particular sea un pingback o un trackback, formatearlo con el código de las lineas 135-136.”
Aquí tienen como se ven nuestros pingbacks:

Es muy dulce. También es bastante básico, pero se puede embellecer casi que con solo css. Hablaremos sobre css en una futura lección.

Note la ausencia de una etiqueta de cierre <li> en la línea 137. wp_list_comments() agrega automáticamente esa parte.

Ahora, en la línea 138, la declaración break significa que hemos terminado con los pingbacks y trackbacks. La declaración default en la línea 139 dice, en español, “cuando el comentario actual no sea de ninguno de los casos precedentes, formatéelo con el código por defecto de las líneas 141 a 161.” Dado que los únicos casos anteriores son los pingbacks y trackbacks, este etiquetado se aplicará a todos los comentarios regulares.

Otra vez, muy básico, pero ya le vamos a dar color más adelante.

Es importante que cada etiqueta li de los comentarios tenga agregada la función comments_class() (vea la línea 141), porque, del mismo modo que body_class() y post_class(), comment_class() agrega a los comentarios clases útiles, a las que se puede apuntar con CSS. Por ejemplo, los comentarios realizados por el autor de la entrada reciben una clase llamada “bypostauthor”, de forma de poder distinguir los comentarios del autor del resto de los comentarios.

Para cambiar el tamaño predefinido de su gravatar, simplemente cambie el 40 de la línea 145.

		<?php echo get_avatar( $comment, 40 ); ?>

		<?php echo get_avatar( $comment, 40 ); ?>

Ese 40 indica el tamaño, en pixeles, de su gravatar. De hecho, si quiere alterar el diseño de los comentarios individuales, debería modificar el código de las líneas 141 a 160 (o de la 135-136 para los pingbacks).

Al igual que con los pingbacks, no necesitamos una etiqueta </li> para corresponder a la etiqueta de apertura <li> de la línea 141, porque la agregará WordPress más adelante.

Todo bien, terminamos nuestro caso default con el break de la línea 168, y finalizamos la declaración switch en la línea 169 con endswitch.

La plantilla de comentarios (comments.php)

No lo he espantado ¿verdad? Seré honesto: no es tan aterrador. Tenemos que poner en uso dentro de la plantilla de comentarios nuestra función shape_comment(), la que ya recorrimos más arriba.

Hay comentarios PHP que son de ayuda y que lo guiarán para comprender que es lo que está pasando. Pegue este código en el archivo comments.php.

<?php
/**
 * The template for displaying Comments.
 *
 * The area of the page that contains both current comments
 * and the comment form. The actual display of comments is
 * handled by a callback to shape_comment() which is
 * located in the inc/template-tags.php file.
 *
 * @package Shape
 * @since Shape 1.0
 */
?>
 
<?php
/*
 * If the current post is protected by a password and
 * the visitor has not yet entered the password we will
 * return early without loading the comments.
 */
if ( post_password_required() )
	return;
?>

	<div id="comments" class="comments-area">
  <?php // You can start editing here -- including this comment! ?>
  <?php if ( have_comments() ) : ?>
	  <h2 class="comments-title">
   		<?php
     		printf( _n( 'One thought on “%2$s”', '%1$s thoughts on “%2$s”', get_comments_number(), 'shape' ),
      		number_format_i18n( get_comments_number() ), '<span>' . get_the_title() . '</span>' );
      ?>
    </h2>
    <?php if ( get_comment_pages_count() > 1 && get_option( 'page_comments' ) ) : // are there comments to navigate through? If so, show navigation ?>
    <nav role="navigation" id="comment-nav-above" class="site-navigation comment-navigation">
    	<h1 class="assistive-text"><?php _e( 'Comment navigation', 'shape' ); ?></h1>
      <div class="nav-previous"><?php previous_comments_link( __( '← Older Comments', 'shape' ) ); ?></div>
      <div class="nav-next"><?php next_comments_link( __( 'Newer Comments →', 'shape' ) ); ?></div>
    </nav><!-- #comment-nav-before .site-navigation .comment-navigation -->
    <?php endif; // check for comment navigation ?>
    <ol class="commentlist">
    	<?php
    	  /* Loop through and list the comments. Tell wp_list_comments()
         * to use shape_comment() to format the comments.
         * If you want to overload this in a child theme then you can
         * define shape_comment() and that will be used instead.
         * See shape_comment() in inc/template-tags.php for more.
         */
        wp_list_comments( array( 'callback' => 'shape_comment' ) );
      ?>
    </ol><!-- .commentlist -->
    <?php if ( get_comment_pages_count() > 1 && get_option( 'page_comments' ) ) : // are there comments to navigate through? If so, show navigation ?>
    <nav role="navigation" id="comment-nav-below" class="site-navigation comment-navigation">
    	<h1 class="assistive-text"><?php _e( 'Comment navigation', 'shape' ); ?></h1>
      <div class="nav-previous"><?php previous_comments_link( __( '← Older Comments', 'shape' ) ); ?></div>
      <div class="nav-next"><?php next_comments_link( __( 'Newer Comments →', 'shape' ) ); ?></div>
    </nav><!-- #comment-nav-below .site-navigation .comment-navigation -->
    <?php endif; // check for comment navigation ?>
  <?php endif; // have_comments() ?>
  <?php
  	// If comments are closed and there are comments, let's leave a little note, shall we?
    if ( ! comments_open() && '0' != get_comments_number() && post_type_supports( get_post_type(), 'comments' ) ) :
  ?>
  	<p class="nocomments"><?php _e( 'Comments are closed.', 'shape' ); ?></p>
  <?php endif; ?>
  <?php comment_form(); ?>
</div><!-- #comments .comments-area -->

<?php
/**
 * The template for displaying Comments.
 *
 * The area of the page that contains both current comments
 * and the comment form. The actual display of comments is
 * handled by a callback to shape_comment() which is
 * located in the inc/template-tags.php file.
 *
 * @package Shape
 * @since Shape 1.0
 */
?>
 
<?php
/*
 * If the current post is protected by a password and
 * the visitor has not yet entered the password we will
 * return early without loading the comments.
 */
if ( post_password_required() )
	return;
?>

	<div id="comments" class="comments-area">
  <?php // You can start editing here -- including this comment! ?>
  <?php if ( have_comments() ) : ?>
	  <h2 class="comments-title">
   		<?php
     		printf( _n( 'One thought on “%2$s”', '%1$s thoughts on “%2$s”', get_comments_number(), 'shape' ),
      		number_format_i18n( get_comments_number() ), '<span>' . get_the_title() . '</span>' );
      ?>
    </h2>
    <?php if ( get_comment_pages_count() > 1 && get_option( 'page_comments' ) ) : // are there comments to navigate through? If so, show navigation ?>
    <nav role="navigation" id="comment-nav-above" class="site-navigation comment-navigation">
    	<h1 class="assistive-text"><?php _e( 'Comment navigation', 'shape' ); ?></h1>
      <div class="nav-previous"><?php previous_comments_link( __( '← Older Comments', 'shape' ) ); ?></div>
      <div class="nav-next"><?php next_comments_link( __( 'Newer Comments →', 'shape' ) ); ?></div>
    </nav><!-- #comment-nav-before .site-navigation .comment-navigation -->
    <?php endif; // check for comment navigation ?>
    <ol class="commentlist">
    	<?php
    	  /* Loop through and list the comments. Tell wp_list_comments()
         * to use shape_comment() to format the comments.
         * If you want to overload this in a child theme then you can
         * define shape_comment() and that will be used instead.
         * See shape_comment() in inc/template-tags.php for more.
         */
        wp_list_comments( array( 'callback' => 'shape_comment' ) );
      ?>
    </ol><!-- .commentlist -->
    <?php if ( get_comment_pages_count() > 1 && get_option( 'page_comments' ) ) : // are there comments to navigate through? If so, show navigation ?>
    <nav role="navigation" id="comment-nav-below" class="site-navigation comment-navigation">
    	<h1 class="assistive-text"><?php _e( 'Comment navigation', 'shape' ); ?></h1>
      <div class="nav-previous"><?php previous_comments_link( __( '← Older Comments', 'shape' ) ); ?></div>
      <div class="nav-next"><?php next_comments_link( __( 'Newer Comments →', 'shape' ) ); ?></div>
    </nav><!-- #comment-nav-below .site-navigation .comment-navigation -->
    <?php endif; // check for comment navigation ?>
  <?php endif; // have_comments() ?>
  <?php
  	// If comments are closed and there are comments, let's leave a little note, shall we?
    if ( ! comments_open() && '0' != get_comments_number() && post_type_supports( get_post_type(), 'comments' ) ) :
  ?>
  	<p class="nocomments"><?php _e( 'Comments are closed.', 'shape' ); ?></p>
  <?php endif; ?>
  <?php comment_form(); ?>
</div><!-- #comments .comments-area -->

La función comment_form() (en la línea 66), es la responsable de producir el formulario completo de comentarios. Aquí tienen lo que produce, de forma predefinida (que es como lo estamos usando). Sin estilizar aún, por supuesto:

Si quisiera cambiar elementos del formulario de comentarios, podría hacerlo pasándole diferentes parámetros a la función comment_form(). Vea el Codex para una lista completa de posibles parámetros.

Y eso es todo. Ya tiene una buena plantilla de comentarios para llamar usted mismo.

Todas las entradas de esta serie:

• 
  Tutorial de ThemeShaper sobre creación de Temas para WordPress
• 
  1. El desarrollo de su «sentido temático»
• 
  2. Herramientas para el desarrollo de Temas de WordPress
• 
  3. Creación de una estructura HTML para su Tema de WordPress
• 
  4. Plantillas y estructura de directorios de un Tema de WordPress
• 
  5. Configuración de las funciones de su Tema
• 
  6. Asegure su Tema de WordPress
• 
  7. La plantilla cabecera del tema de WordPress: header.php
• 
  8. La plantilla Index de su Tema de WordPress
• 
  9. Las plantillas Entrada Individual, Entrada de Adjuntos y error 404 del Tema de WordPress
• 
  10. La plantilla de comentarios de un Tema de WordPress
• 
  11. La plantilla de búsqueda (search) y la plantilla página (page) del tema de WordPress
• 
  12. La plantilla Archivo
• 
  13. Las plantillas “sidebar” (barra lateral) y “footer” (pie de página) del tema de WordPress
• 
  14. Como resetear y reconstruir los CSS de su Tema de WordPress y definir su diseño
• 
  15. Fondo y cabecera personalizados
• 
  16. Distribuir su Tema de WordPress