In this tutorial, we will expand on the material Kristof already covered a while ago since there are some neat additional options available to us.
If you’ve worked with Magento for any length of time, you will most certainly be familiar with the dreaded “There has been an error processing your request” page. Clearly, the goal is to make sure that this page never appears to our online customers on a live site, but, on occasion it may still show up. For example if you’ve just sent out a newsletter and have an onslaught of visits, if your server runs out of MySQL connections, your visitors will still see this page.
Similarly, Magento provides an easy way to show a maintenance page. All you have to do is create an empty file called maintenance.flag in your Magento document root and your site will be redirected to the built in maintenance page.
This is all well but as part of a professional solution for your clients, we would like to be able to customize these pages so that they are more in line with the design of the site. Luckily, it is very easy to customize these templates. The principle is very similar to customizing a standard Magento skin folders, so, let’s dig into it.
Note that the Magento version used for this tutorial is 1.5.
1. Structure of the Error Pages
The error report and maintenance pages are rendered from template located under
[MAGENTO_ROOT]/errors. As you can see from the screenshot, the folder contains some php files and a folder called default that reminds us of the way the normal Magento skin folders are structured. You will notice that the skin folder also contains files with the same name as the error root folder. The difference between them is that the files in the error root are just there to route the specific page processing. They include the
processor.php file, instantiate the report class and call the appropriate method which in turn will render the actual page template. For example, the
503.php file has these three lines:
require_once 'processor.php'; $processor = new Error_Processor(); $processor->process503();
The actual page HTML will be in the phtml files under the default skin folder.
So let’s examine the various files of interest here.
In the error folder:
The good guys from the Magento dev team have provided us with a sample configuration file that we can use to create our specific configuration to customize our error/maintenance pages. We will look into this file in a moment and create our
local.xml file once we decide what we want to achieve.
This file is the “engine” that contains all the rendering logic. It implements the
Error_Processing class that reads the error template configuration from the
local.xml file, loads the configured design and runs the configured design.
404.php, 503.php, report.php
These are the “routing” pages that just invoke the appropriate methods in the
The default design folder:
This is the master template file that contains the HTML for all the pages that are handled by the error sub-system. This page will include one of the phtml files listed below. Since this page contains the header and footer you’d clearly want to modify it to implement your own branded design.
This is a 404 Not Found page template. I haven’t seen that one appear on a Magento site since there is already a 404 CMS page built into Magento. However, this page may be useful if you want to change the default 404 handling and direct all 404s to this template. For our purposes, we will ignore this template.
This is the “Temporarily Unavailable” page that also dubs as the maintenance page shown when the site is in maintenance mode. For example, when you are performing upgrades from Magento Connect or manually put the
maintenance.flag file up.
We’ll definitely want to customize this page.
This page contains the HTML and PHP code that renders the error report page shown above. It’s certainly another candidate for our customization.
images and css folders
These folders contain the skin CSS and images used by the error/maintenance templates.
2. The local.xml File
Before we dive into customizing the phtml, we should realize that, like with the standard Magento design templates, a similar paradigm is also in effect here. In other words, we don’t want to “hack” the files in the default design, but create our own error design and customize the files there. For this, we will need to create a
local.xml file with the appropriate configuration. Opening the supplied sample XML file, we see:
<?xml version="1.0" encoding="UTF-8"?> <config> <skin>default</skin> <report> <!-- "action" can be set to "print" to show exception on screen and "email" to send exception on specified email --> <action>print</action> <!-- in "subject" you can set subject of email --> <subject>Store Debug Information</subject> <!-- "email_address" admin email address --> <email_address></email_address> <!-- "trash" is handle about trace info value "leave" is for store on disk value "delete" is for cleaning --> <trash>leave</trash> </report> </config>
The comments in the file are pretty clear but we’ll quickly explain the various elements.
<skin> – this is the element describing which skin folder the error processor should use. So, to create our own skin, we will change “default” to our own custom skin folder, for example:
<action> – is an element that governs what will happen when an error is reported. The values are:
blank: This is the default value and means that the error report will not be shown on the page but saved in the report file under var/report/
The following two elements allow you to set a default email recipient and subject and are relevant only if you set the action to “email” and are self-explanatory. Note that Magento will append the error report number to the subject line automatically.
<trash> is the final element and allows you to specify what you want to happen with the error report files dumped in
var/report/. Again, the comments are self-explanatory.
So, we will settle for the following
<?xml version="1.0" encoding="UTF-8"?> <config> <skin>magebase</skin> <report> <action>email</action> <subject>XYZ Store Debug Information</subject> <email_address>firstname.lastname@example.org</email_address> <trash>leave</trash> </report> </config>
In other words, we’ll create a “magebase” skin, we want our customers to be able to submit error reports to us and also leave the report files on the server. If the customer sends a report, our email will have the subject line: “XYZ Store Debug Information [error-number]” and it will be sent to the specified email address (do change that on your own site).
3. Creating a Custom Skin
That’s easy, just create a new sub-folder under
errors/ and copy the files and folders from the
errors/default/ skin there. Done!
Of course, if you this won’t show any changes in the design but, the error page would now look like this:
Now, the task is to customize our design.
4. Customizing the Skin
We mentioned above that the main HTML for these pages comes from
page.phtml containing the following code:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> <title><?php echo $this->pageTitle?></title> <base href="<?php echo $this->getSkinUrl()?>" /> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <meta name="description" content="" /> <meta name="keywords" content="" /> <meta name="robots" content="*" /> <link rel="stylesheet" href="css/styles.css" type="text/css" /> <link rel="icon" href="images/favicon.ico" type="image/x-icon" /> <link rel="shortcut icon" href="images/favicon.ico" type="image/x-icon" /> </head> <body> <div class="wrapper"> <div class="page"> <div class="header-container"> <div class="header"> <a href="<?php echo $this->getBaseUrl()?>" title="Magento Commerce" class="logo"><img src="images/logo.gif" alt="Magento Commerce" /></a> </div> </div> <div class="main-container"> <div class="main col1-layout"> <?php require_once $contentTemplate; ?> </div> </div> <div class="footer-container"> <div class="footer"> <address class="copyright">Magento is a trademark of Magento Inc. Copyright © 2010 Magento Inc.</address> </div> </div> </div> </div> </body> </html>
So, clearly, the first thing we’d want to do is replace the logo image, link title attribute and image alt attribute, as well as the footer text. Then we can move onto the included phtml templates. And work on our CSS. We can also add or replace the images in the images folder if we need some fancy background or other imagery.
We won’t go into details about how to structure your HTML/CSS, we will leave that up to you since it’s standard web development work.
So, after our Magebase error page makeover, our new pages look like this:
We saw how we can easily customize the default Magento maintenance and error pages by configuring the
local.xml file, creating a custom skin folder and adjusting the HTML and CSS supplied in the default skin. You can play around with the settings in
local.xml to get the configuration you want and add more meaningful content to the pages themselves.
If you want to change the actual default processing that happens in
processor.php, then you’d have to extend the Error_Processor class in your own file and include it in the other
*.php files. Bear in mind that those changes may be overwritten during an upgrade. Your custom skin, however, would not be affected.
Finally, there doesn’t seem to be an easy way to create language/locale specific error pages but you can create your custom skin templates in your store’s main language.
Originally published on magebase.com. Copyright © 2011 Magebase - All Rights Reserved.