Changing Statamic's layout for custom error pages

I’ve known for years that you can create your own error pages - like a 404, 403 - for Statamic by adding a file such as resources/views/errors/404.antlers.html. It’s a super simple way to make errors more user friendly, and can offer your visitors the next steps - maybe back to the home page, or to a different call to action area of your site.

It means you can make errors pretty.

And who doesn’t like that?

When you do this, your error file (such as the 404.antlers.html file) gets slotted in to your site’s main layout file. Which is great because it still feels like your site.

However, it can also be a cause for unnecessary overhead on your server.

Why? Well, if your main layout does things like:

include your site’s multi-level nav,
uses glide to process images
references or processes other entries
uses a stack of globals

you will find that your error page can actually become a bottleneck for your site’s performance.

This is especially images with glide-based images. Unless you’re using full image caching (which creates other UX issues for your site), even a glide-rendered image will still use a PHP process to get returned to the user.

For example’s sake, let’s say your error page pulls in 4 glide-generated images. That’s 5 processes: one for the main page, plus 1 for each image. And let’s say you’ve migrated a site from another platform and there is markup out there still linking to old assets (maybe a favicon, part of your theme, etc) which now create a 404 each. And for easy maths, you’ve got 10 404s being generated by visiting this one page. That’s 10 × 404 pages all being generated at once - but remember, 4 images each, so that’s actually 10 pages + (10 × 4) images. All that hit your server instantly: and can cause major performance errors.

Expensive, right?

OK so back to the point of all of this.

The 404.antlers.html file allows you to control your 404 page template, but still will use your site’s main layout.antlers.html file. Your 404.antlers.html content will get placed in your layout’s {{ template_content }} slot.

At Mity Digital, we’ve been working on a large content-driven site and wanted to ensure we don’t have these 404 bottlenecks, and wanted to create our own fully custom 404 page. Given Statamic’s routing includes a catch all, we can’t use a fully static 404 page without knowing every location to include within the the nginx configuration, so wanted to use a custom layout to strip out the unnecessary processing.

Given the docs are a wealth of knowledge, you’d think I’d look there. But no, I knew you could override different status codes so didn’t think to check, and did some source diving in to Statamic’s RendersHttpExceptions concern that shows the stack of layouts that the rendering process will use. Statamic will work through this list until it finds a layout file to use:

errors.layout
layouts.layout
config('statamic.system.layout', 'layout')
'statamic::blank

Out of the box, Statamic will pick up the third option - your site’s main layout. But look at how easy it is to have an errors layout! All we have to do is create resources/views/errors/layout.antlers.html and include our full layout (i.e. <html>, <head>, <body>, styles, etc) there.

And zing, Statamic will now use that as our layout, and inject our specific error mark up in to place.

Just make sure to include your {{ template_content }} variable, just like your site’s main layout file, to inject your error markup: 404, 403, 500, etc.

If I had bothered to look at the docs, I would have seen this documented too. That’ll teach me.

What you can also do is set a title variable in your 404 file that can be included in your new layout too.

In your 404.antlers.html file:

Copied!

1{{ title = '404 - Page Not Found' }}
2 
3<div>
4  Here is my custom 404 markup
5</div>

{{ title = '404 - Page Not Found' }}

<div>
  Here is my custom 404 markup
</div>

And then in your errors/layout.antlers.html file:

Copied!

 1<html>
 2  <head>
 3    <title>{{ title }}</title>
 4  </head>
 5  <body>
 6    <!-- your new layout markup -->
 7    {{ template_content }}
 8    <!-- your new layout markup -->
 9  </body>
10</html>

<html>
  <head>
    <title>{{ title }}</title>
  </head>
  <body>
    <!-- your new layout markup -->
    {{ template_content }}
    <!-- your new layout markup -->
  </body>
</html>

And now you’re all set: a custom 404 layout, including the title tag, meaning you can remove all of those expensive operations to make errors lighter and faster to handle.

Changing Statamic's layout for custom error pages

Comments