comments_template

Load the comment template specified in $file.

Description

comments_template( (string) $file = '/comments.php', (bool) $separate_comments = false ); 

Will not display the comments template if not on single post or page, or if the post does not have comments.

Uses the WordPress database object to query for the comments. The comments are passed through the filter hook with the list of comments and the post ID respectively.

The $file path is passed through a filter hook called , which includes the TEMPLATEPATH and $file combined. Tries the $filtered path first and if it fails it will require the default comment template from the default theme. If either does not exist, then the WordPress process will be halted. It is advised for that reason, that the default theme is not deleted.

Will not try to get the comments if the post has none.

Parameters (2)

0. $file — Optional. (string) => '/comments.php'
The file to load. Default /comments.php..
1. $separate_comments — Optional. (bool) => false
Whether to separate the comments by comment type. Default false.

Usage

  1. if ( !function_exists( 'comments_template' ) ) { 
  2. require_once ABSPATH . WPINC . '/comment-template.php'; 
  3.  
  4. // Optional. The file to load. Default '/comments.php'. 
  5. $file = '/comments.php'; 
  6.  
  7. // Optional. Whether to separate the comments by comment type. 
  8. // Default false. 
  9. $separate_comments = false; 
  10.  
  11. // NOTICE! Understand what this does before running. 
  12. $result = comments_template($file, $separate_comments); 
  13.  

Defined (1)

The function is defined in the following location(s).

/wp-includes/comment-template.php  
  1. function comments_template( $file = '/comments.php', $separate_comments = false ) { 
  2. global $wp_query, $withcomments, $post, $wpdb, $id, $comment, $user_login, $user_ID, $user_identity, $overridden_cpage; 
  3.  
  4. if ( !(is_single() || is_page() || $withcomments) || empty($post) ) 
  5. return; 
  6.  
  7. if ( empty($file) ) 
  8. $file = '/comments.php'; 
  9.  
  10. $req = get_option('require_name_email'); 
  11.  
  12. /** 
  13. * Comment author information fetched from the comment cookies. 
  14. */ 
  15. $commenter = wp_get_current_commenter(); 
  16.  
  17. /** 
  18. * The name of the current comment author escaped for use in attributes. 
  19. * Escaped by sanitize_comment_cookies(). 
  20. */ 
  21. $comment_author = $commenter['comment_author']; 
  22.  
  23. /** 
  24. * The email address of the current comment author escaped for use in attributes. 
  25. * Escaped by sanitize_comment_cookies(). 
  26. */ 
  27. $comment_author_email = $commenter['comment_author_email']; 
  28.  
  29. /** 
  30. * The url of the current comment author escaped for use in attributes. 
  31. */ 
  32. $comment_author_url = esc_url($commenter['comment_author_url']); 
  33.  
  34. $comment_args = array( 
  35. 'orderby' => 'comment_date_gmt',  
  36. 'order' => 'ASC',  
  37. 'status' => 'approve',  
  38. 'post_id' => $post->ID,  
  39. 'no_found_rows' => false,  
  40. 'update_comment_meta_cache' => false, // We lazy-load comment meta for performance. 
  41. ); 
  42.  
  43. if ( get_option('thread_comments') ) { 
  44. $comment_args['hierarchical'] = 'threaded'; 
  45. } else { 
  46. $comment_args['hierarchical'] = false; 
  47.  
  48. if ( $user_ID ) { 
  49. $comment_args['include_unapproved'] = array( $user_ID ); 
  50. } elseif ( ! empty( $comment_author_email ) ) { 
  51. $comment_args['include_unapproved'] = array( $comment_author_email ); 
  52.  
  53. $per_page = 0; 
  54. if ( get_option( 'page_comments' ) ) { 
  55. $per_page = (int) get_query_var( 'comments_per_page' ); 
  56. if ( 0 === $per_page ) { 
  57. $per_page = (int) get_option( 'comments_per_page' ); 
  58.  
  59. $comment_args['number'] = $per_page; 
  60. $page = (int) get_query_var( 'cpage' ); 
  61.  
  62. if ( $page ) { 
  63. $comment_args['offset'] = ( $page - 1 ) * $per_page; 
  64. } elseif ( 'oldest' === get_option( 'default_comments_page' ) ) { 
  65. $comment_args['offset'] = 0; 
  66. } else { 
  67. // If fetching the first page of 'newest', we need a top-level comment count. 
  68. $top_level_query = new WP_Comment_Query(); 
  69. $top_level_args = array( 
  70. 'count' => true,  
  71. 'orderby' => false,  
  72. 'post_id' => $post->ID,  
  73. 'status' => 'approve',  
  74. ); 
  75.  
  76. if ( $comment_args['hierarchical'] ) { 
  77. $top_level_args['parent'] = 0; 
  78.  
  79. if ( isset( $comment_args['include_unapproved'] ) ) { 
  80. $top_level_args['include_unapproved'] = $comment_args['include_unapproved']; 
  81.  
  82. $top_level_count = $top_level_query->query( $top_level_args ); 
  83.  
  84. $comment_args['offset'] = ( ceil( $top_level_count / $per_page ) - 1 ) * $per_page; 
  85.  
  86. /** 
  87. * Filters the arguments used to query comments in comments_template(). 
  88. * @since 4.5.0 
  89. * @see WP_Comment_Query::__construct() 
  90. * @param array $comment_args { 
  91. * Array of WP_Comment_Query arguments. 
  92. * @type string|array $orderby Field(s) to order by. 
  93. * @type string $order Order of results. Accepts 'ASC' or 'DESC'. 
  94. * @type string $status Comment status. 
  95. * @type array $include_unapproved Array of IDs or email addresses whose unapproved comments 
  96. * will be included in results. 
  97. * @type int $post_id ID of the post. 
  98. * @type bool $no_found_rows Whether to refrain from querying for found rows. 
  99. * @type bool $update_comment_meta_cache Whether to prime cache for comment meta. 
  100. * @type bool|string $hierarchical Whether to query for comments hierarchically. 
  101. * @type int $offset Comment offset. 
  102. * @type int $number Number of comments to fetch. 
  103. * } 
  104. */ 
  105. $comment_args = apply_filters( 'comments_template_query_args', $comment_args ); 
  106. $comment_query = new WP_Comment_Query( $comment_args ); 
  107. $_comments = $comment_query->comments; 
  108.  
  109. // Trees must be flattened before they're passed to the walker. 
  110. if ( $comment_args['hierarchical'] ) { 
  111. $comments_flat = array(); 
  112. foreach ( $_comments as $_comment ) { 
  113. $comments_flat[] = $_comment; 
  114. $comment_children = $_comment->get_children( array( 
  115. 'format' => 'flat',  
  116. 'status' => $comment_args['status'],  
  117. 'orderby' => $comment_args['orderby'] 
  118. ) ); 
  119.  
  120. foreach ( $comment_children as $comment_child ) { 
  121. $comments_flat[] = $comment_child; 
  122. } else { 
  123. $comments_flat = $_comments; 
  124.  
  125. /** 
  126. * Filters the comments array. 
  127. * @since 2.1.0 
  128. * @param array $comments Array of comments supplied to the comments template. 
  129. * @param int $post_ID Post ID. 
  130. */ 
  131. $wp_query->comments = apply_filters( 'comments_array', $comments_flat, $post->ID ); 
  132.  
  133. $comments = &$wp_query->comments; 
  134. $wp_query->comment_count = count($wp_query->comments); 
  135. $wp_query->max_num_comment_pages = $comment_query->max_num_pages; 
  136.  
  137. if ( $separate_comments ) { 
  138. $wp_query->comments_by_type = separate_comments($comments); 
  139. $comments_by_type = &$wp_query->comments_by_type; 
  140. } else { 
  141. $wp_query->comments_by_type = array(); 
  142.  
  143. $overridden_cpage = false; 
  144. if ( '' == get_query_var( 'cpage' ) && $wp_query->max_num_comment_pages > 1 ) { 
  145. set_query_var( 'cpage', 'newest' == get_option('default_comments_page') ? get_comment_pages_count() : 1 ); 
  146. $overridden_cpage = true; 
  147.  
  148. if ( !defined('COMMENTS_TEMPLATE') ) 
  149. define('COMMENTS_TEMPLATE', true); 
  150.  
  151. $theme_template = STYLESHEETPATH . $file; 
  152. /** 
  153. * Filters the path to the theme template file used for the comments template. 
  154. * @since 1.5.1 
  155. * @param string $theme_template The path to the theme template file. 
  156. */ 
  157. $include = apply_filters( 'comments_template', $theme_template ); 
  158. if ( file_exists( $include ) ) 
  159. require( $include ); 
  160. elseif ( file_exists( TEMPLATEPATH . $file ) ) 
  161. require( TEMPLATEPATH . $file ); 
  162. else // Backward compat code will be removed in a future release 
  163. require( ABSPATH . WPINC . '/theme-compat/comments.php');