In web development, developers frequently encounter situations where site owners find the standard HTTP error pages (such as Access Denied or Page Not Found) too plain, particularly when competitors create visually engaging error pages. Check out these 404 pages for inspiration, and don't miss this example from Google.
Drupal also uses straightforward error pages, yet it addresses user needs effectively by allowing site builders and developers to customize these error pages out-of-the-box. Additionally, it offers ways to modify these pages.
Let's delve into customizing these pages.
The focus here is on the word "Page" in the phrase "HTTP error page," as an HTTP error page is essentially a page. This could be a Node page, View Page Display, Panel page, or Custom Route (URL) in Drupal.
In Drupal, some custom routes (URLs) are specified in the `system.routing.yml` file:
system.401:
path: '/system/401'
defaults:
_controller: '\Drupal\system\Controller\Http4xxController:on401'
_title: 'Unauthorized'
requirements:
_access: 'TRUE'
system.403:
path: '/system/403'
defaults:
_controller: '\Drupal\system\Controller\Http4xxController:on403'
_title: 'Access denied'
requirements:
_access: 'TRUE'
system.404:
path: '/system/404'
defaults:
_controller: '\Drupal\system\Controller\Http4xxController:on404'
_title: 'Page not found'
requirements:
_access: 'TRUE'
These routes generate error messages whenever a user tries to access non-existent or unauthorized pages on the site.
For instance, `Http4xxController` in Drupal renders the default content for HTTP errors.
Drupal's default options are quite basic, but it offers methods to customize error pages and express your creativity.
Here, we will explore two methods to modify error messages/pages:
1. Log in to your Drupal site as an administrator.
2. Create a content type named "error pages" (you can use an existing type if preferred).
3. Create a node page with the "error pages" content type, which will act as your error page.
4. Add content and style it as needed.
Next, specify the new node page URL as your error page:
1. Log in to your Drupal site as an administrator.
2. Go to `/admin/config/system/site-information`.
3. Under the "Error Pages" section, specify the URL of your new node page.
Now, your error pages are set up through the Drupal UI, reflecting the content and style of your Node Content.
Besides configuring error pages through the Drupal UI, you can use the `hook_theme_suggestions_HOOK_alter()` to suggest specific TWIG templates for error pages. Here's how you can do that:
1. Implement the `hook_theme_suggestions_HOOK_alter()` in your theme file.
2. This hook captures error messages and guides Drupal to use a specified TWIG template.
3. Place the error-specific TWIG file in your theme's template directory.
Below are two functions you can use to suggest error-specific TWIG templates to Drupal.
/**
* Implements hook_theme_suggestions_HOOK_alter().
*/
function THEMENAME_theme_suggestions_page_alter(array &$suggestions, array $variables) {
$route_name = \Drupal::routeMatch()->getRouteName();
switch ($route_name) {
case 'system.401':
$error = 401;
break;
case 'system.403':
$error = 403;
break;
case 'system.404':
$error = 404;
break;
}
if (isset($error)) {
$suggestions[] = 'page__' . $error;
}
}
/**
* Implements hook_theme_suggestions_HOOK_alter().
*/
function THEMENAME_theme_suggestions_page_alter(array &$suggestions, array $variables) {
$request = \Drupal::request();
if ($exception = $request->attributes->get('exception')) {
$status_code = $exception->getStatusCode();
if (in_array($status_code, array(401, 403, 404))) {
$suggestions[] = 'page__' . $status_code;
}
}
}
After adding one of these functions to your code, add the error-specific TWIG templates to your theme and format the HTML as desired.
This guide shows how Drupal enables you to configure HTTP error pages through both settings and code. Get started on revamping your HTTP error pages to showcase your creativity!