Creating Your First Custom Standard WordPress Comment Templates in Legacy Core PHP Implementations

Understanding WordPress Comment Template Hierarchy

Before diving into custom templates, it’s crucial to grasp how WordPress resolves comment display. WordPress uses a template hierarchy, similar to how it determines which template file to use for posts, pages, or archives. For comments, the primary template file is typically comments.php. However, WordPress also looks for more specific templates based on the context, such as comments-post.php for the submission form itself, though this is less commonly overridden directly by theme developers for display purposes.

The comments.php file is included by other template files (like single.php, page.php, or singular.php) using the get_template_part() or locate_template() functions. This means that if a theme doesn’t have a specific comments.php, WordPress falls back to the default theme’s comments.php, or ultimately, the one provided by WordPress core. Our goal is to create custom versions of this file that can be selectively loaded.

Leveraging get_comments_template() for Customization

The most robust way to introduce custom comment templates without directly modifying core WordPress files or a parent theme’s comments.php is by using the get_comments_template() filter. This filter allows you to hook into the process WordPress uses to locate the comment template file. By returning a custom file path, you can instruct WordPress to use your specific template.

This approach is particularly useful when you need different comment layouts for different post types or specific conditions. For instance, you might want a simpler comment display for a custom post type like ‘events’ compared to standard blog posts.

Implementing a Basic Custom Comment Template

Let’s create a scenario where we want a distinct comment template for posts of the ‘post’ type. We’ll create a new file within our theme’s directory and then use the get_comments_template() filter to point WordPress to it.

First, create a new file in your active theme’s directory (e.g., /wp-content/themes/your-theme-name/custom-comments.php). This file will contain your custom HTML structure and PHP logic for displaying comments.

custom-comments.php Example

This example provides a basic structure, iterating through comments and displaying author, date, and content. It also includes the comment form.

<?php
if ( postswalk() ) {
    wp_list_comments( array(
        'style' => 'ol',
        'short_ping' => true
    ) );
}

if ( comments_open() ) {
    comment_form( array(
        'title_reply_before' => '<h3>',
        'title_reply_after' => '</h3>'
    ) );
}
?>

Registering the Custom Template with the Filter

Now, add the following code to your theme’s functions.php file. This code hooks into the get_comments_template filter and checks if the current post type is ‘post’. If it is, it returns the path to our custom template file.

<?php
function my_custom_comments_template( $template ) {
    global $post;

    if ( $post && $post->post_type == 'post' ) {
        $new_template = trailingslashit(get_template_directory()) . 'custom-comments.php';
        return $new_template;
    }

    return $template;
}
add_filter( 'get_comments_template', 'my_custom_comments_template' );
?>

Conditional Loading for Different Post Types

The previous example demonstrates a simple conditional load. For more complex scenarios, you can expand the conditional logic within the filter function. For instance, you might want a different template for custom post types or even for specific individual posts.

Example: Different Templates for ‘post’ and ‘event’ Post Types

Let’s assume you have a custom post type registered as ‘event’. You can create two separate comment template files: comments-post.php and comments-event.php. Then, modify your functions.php to load them conditionally.

<?php
function conditional_comment_templates( $template ) {
    global $post;

    if ( ! $post ) {
        return $template;
    }

    $post_type = $post->post_type;

    if ( $post_type == 'post' ) {
        $new_template = trailingslashit(get_template_directory()) . 'comments-post.php';
        return $new_template;
    } elseif ( $post_type == 'event' ) {
        $new_template = trailingslashit(get_template_directory()) . 'comments-event.php';
        return $new_template;
    }

    return $template;
}
add_filter( 'get_comments_template', 'conditional_comment_templates' );
?>

Advanced: Overriding Specific Comment Elements

While creating entirely new comment template files is powerful, sometimes you only need to modify specific parts of the comment output, like the comment structure or the author’s gravatar. WordPress provides filters for these granular adjustments.

Modifying the Comment Structure with comment_text

The comment_text filter allows you to modify the actual comment content before it’s displayed. This can be useful for adding custom HTML, sanitizing content in a specific way, or even conditionally displaying elements based on comment metadata.

<?php
function my_custom_comment_content( $comment_text, $comment, $args ) {
    if ( $comment->comment_approved == '0' ) {
        $comment_text = '<em>Your comment is awaiting moderation.</em>' . $comment_text;
    }

    // Example: Add a custom class to paragraphs within comments
    $comment_text = str_replace( '<p>', '<p class="custom-comment-paragraph">', $comment_text );

    return $comment_text;
}
add_filter( 'comment_text', 'my_custom_comment_content', 10, 3 );
?>

Customizing the Comment Form with comment_form_defaults

The comment_form_defaults filter allows you to alter the default arguments passed to the comment_form() function. This is useful for changing labels, adding custom fields, or modifying the submit button’s text.

<?php
function my_custom_comment_form_fields( $defaults ) {
    $defaults['comment_field'] = '<p class="comment-form-comment"><label for="comment">Your Thoughts</label><textarea id="comment" name="comment" cols="45" rows="8" aria-required="true"></textarea></p>';
    $defaults['title_reply'] = 'Share Your Ideas';
    $defaults['label_submit'] = 'Post Comment';

    return $defaults;
}
add_filter( 'comment_form_defaults', 'my_custom_comment_form_fields' );
?>

Best Practices and Considerations

• Child Themes: Always implement custom templates and functions within a child theme. This prevents your customizations from being overwritten when the parent theme is updated.
• Code Organization: Keep your custom comment template files organized within your theme’s directory. Use descriptive filenames.
• Performance: While filters offer flexibility, excessive or poorly written filters can impact performance. Profile your site if you notice slowdowns.
• Accessibility: Ensure your custom comment templates are accessible. Use semantic HTML, provide proper ARIA attributes where necessary, and test with screen readers.
• Security: Always sanitize and escape user-generated content when displaying it. WordPress functions like esc_html() and esc_attr() are essential.
• Testing: Thoroughly test your custom templates across different browsers and devices, and with various comment scenarios (moderated comments, nested comments, etc.).

By mastering the get_comments_template() filter and understanding the available hooks for comment content and forms, you can create highly customized and context-aware comment sections for your WordPress sites.