Custom WordPress “Comment Error” Page

Posted in:
December 19, 2011

If you've ever tried to submit a WordPress comment without filling in all of the required fields, you'll be redirected to an empty unstyled page that looks like the image below.1

WordPress Comment Error

Now with other types of errors, such as 404 Not Found or 403 Forbidden errors, WordPress uses the 404.php file within your theme. But there are no standard theme files for displaying comment form error pages.

Fortunately, with WordPress versions 3.0 and beyond, customizing the comment error page can be accomplished without too much difficulty. If you've ever taken a look into wp-comments-post.php, the file that handles posted comments, you'll see that when an error is encountered, the function wp_die() is called. To customize the output from wp_die(), you can use the wp_die_handler filter in your theme's functions.php file.

Using the wp_die_handler Filter with your own Die Handler Function

There are three steps to get this working:2

  1. Set up the wp_die_handler filter.
  2. Return your custom wp_die_handler function.
  3. Write your custom wp_die_handler function.

Alright, let's open up your theme's functions.php file and get started.

1. Set up the wp_die_handler filter

add_filter('wp_die_handler', 'get_my_custom_die_handler');

2. Return your custom wp_die_handler function

function get_my_custom_die_handler() {
    return 'my_custom_die_handler';
}

The above function might seem a bit unnecessary, but for the wp_die_handler filter to properly work, this intermediary function is required.

3. Write your custom wp_die_handler function

function my_custom_die_handler($message,$title='',$args=array()) {
    //your code
}

A good starting point for your custom wp_die_handler function is the _default_wp_die_handler() function which you will be replacing.3 Simply change the HTML and CSS to match the design of your website and you're done.

An even better solution would be to rewrite the function so that it looks for a new comment error theme file. Such an approach would make customization easier. We've included sample code for this approach below.

function my_custom_die_handler($message, $title='', $args=array()) {
 $errorTemplate = get_theme_root().'/'.get_template().'/commenterror.php';
 if(!is_admin() && file_exists($errorTemplate)) {
    $defaults = array( 'response' => 500 );
    $r = wp_parse_args($args, $defaults);
    $have_gettext = function_exists('__');
    if ( function_exists( 'is_wp_error' ) && is_wp_error( $message ) ) {
        if ( empty( $title ) ) {
            $error_data = $message->get_error_data();
            if ( is_array( $error_data ) && isset( $error_data['title'] ) )
                $title = $error_data['title'];
        }
        $errors = $message->get_error_messages();
        switch ( count( $errors ) ) :
        case 0 :
            $message = '';
            break;
        case 1 :
            $message = "<p>{$errors[0]}</p>";
            break;
        default :
            $message = "<ul>\n\t\t<li>" . join( "</li>\n\t\t<li>", $errors ) . "</li>\n\t</ul>";
            break;
        endswitch;
    } elseif ( is_string( $message ) ) {
        $message = "<p>$message</p>";
    }
    if ( isset( $r['back_link'] ) && $r['back_link'] ) {
        $back_text = $have_gettext? __('&laquo; Back') : '&laquo; Back';
        $message .= "\n<p><a href='javascript:history.back()'>$back_text</a></p>";
    }
    if ( empty($title) )
        $title = $have_gettext ? __('WordPress &rsaquo; Error') : 'WordPress &rsaquo; Error';
    require_once($errorTemplate);
    die();
 } else {
    _default_wp_die_handler($message, $title, $args);
 }
}

Then in a separate file, which we've called commenterror.php, you can create your comment error page. A basic version of the file is included below.4

commenterror.php

<html>
<head>
<title><?php echo $title; ?></title>
</head>
<body>
<?php echo $message; ?>
</body>
</html>

While we've shown only the most basic example, you can opt to use WordPress template tags, such as in your other theme files and it might be helpful to model this new template after your 404.php error template.

  1. This unstyled error box is also displayed for some errors that a logged in user can cause as well, such as attempting to access admin pages above their access level or when encountering errors related to 3rd party plugins. [↩]
  2. Note: This can easily be accomplished via a plugin, especially if you want to easily add this code into multiple websites, however, to keep this tutorial simple, we are just modifying the theme's functions.php file. [↩]
  3. See WordPress' functions.php and search for _default_wp_die_handler. [↩]
  4. Because this is an error file, it is important that your file is greater than 512 bytes, even after gzip compression, due to an old Internet Explorer bug, where smaller pages would not be recognized. [↩]
Tags: ,

Trackbacks

Trackback URL:

Leave a Reply

Want us to work on your project?

Contact us today for a quote. Click here to submit details regarding your project.

If you are making a general inquiry, send an email to info@velvetblues.com