Create a Custom 404 Error Page for Mambo

Have you ever wondered how to create a custom 404 error page in Mambo? Custom 404 pages are often the most-visited pages on a web site. Visitors most commonly land on them when they mistype an URL or follow an outdated backlink. And, just as search engines stop when they hit a 404, most visitors also jump right off the site. However, a well-written 404 page can not only keep visitors on your site it can enhance their experience.

To create a custom 404 page in Mambo requires four steps. Let's deal with the content first.

Create your 404 Page

Login to your Mambo administrator backend and go to the Static Content Manager. Create a new static content item and give it a meaningful title, for example, "Page Not Found". Create your content the same way you do for any static content.

• A good 404 page will be brief and helpful to visitors. It needs to be larger than 512 bytes to avoid triggering the Internet Explorer default (unhelpful) 404 page - don't worry about this too much because unless your Mambo template is an extreme minimalist design your page will be larger than 512 bytes!
• Start with a simple apology. Nobody likes to land on 404 error pages and the opening statement will help set the tone for your web site. Something simple and friendly, such as "We are sorry that the requested URL could not be found."
• Give your visitors some information. If your site error logs show that users are making common mistakes then explain what these are and how to correct them. Common mistakes may be things such as misspelling the URL, following old links, or adding .html to the end of your URL. Many visitors are not web-savvy and get confused when they land on a 404 page - help them out!
• Give them some links to follow. These could be links to your home page, links to your most popular content, or if you provide products or services, then links to these pages can be useful. Keep it simple and do not reproduce your menu.
• Point them to your search box.
• Add an email link or link to your contact page so they can notify you of site problems.

After you have saved and published your content item, go to any menu that is unpublished and that you do not intend to use on your site. Create a menu item link to the static content item.

Now, you need to get the URL to your new 404 page. The quickest and easiest way to do this is to publish the menu you used for linking to the page. Once published you should see the menu on your site. Click on the link to check that this is all working and bookmark it - you will need this URL later.
Unpublish that menu when you have got the URL.

NOTE: If your site is live and you feel comfortable with temporarily disabling SEF URL's then go to Global Configuration and turn SEF off. Copy the non-SEF link to your new 404 error page. Turn SEF back on in Global Configuration and reload the page to copy the SEF enabled URL to the 404 as well. You don't need to touch the .htaccess file when you turn SEF off temporarily and if you are quick your site visitors are unlikely to notice. The reason for having both versions of the URL are explained here.

Create a Template for the 404 Page

I can sense your eyes glassing over from here! Take a deep breath because this should take you only a few minutes. What we do next is we COPY the template you are using on your site. Take a copy of the entire directory for the template you are using. Rename the folder to something meaningful (I use "error" for my template name). Then open up the templateDetails.xml file and find <name>name of template</name>. Substitute the name of the template for the same name you gave to the folder.

To make it easier to identify which template to use, I also edit the template_thumbnail.png by adding a big "404" text layer to it.

Important! A 404 error page is not much use if it does not return the correct headers. Search engines baulk at 404 pages that return 200 OK header responses. So, to make our new 404 into a "real" 404 we open the index.php of the new template and add this to the very top.

<?php header("HTTP/1.1 404 Not Found"); header("Status: 404 Not Found"); ?>

This MUST be the top line in your template's index.php and must not have any spaces above it or beside it.

In some cases, you may need to add this code above that line:

<?php ob_start(); ?> 

I also edit the template to get rid of extra things that are not needed on a 404 page, but this is optional. Save the files and install or upload the new template to your site in the usual manner.

Once installed, go to your Mambo administrator backend -> Template Manager -> Site Templates.
Click on "Assign" and assign your new error template to the static content item you created.

If you revisit the link you saved earlier you should now see the 404 page and if you look at the HTTP response you will see that it is returning a 404.

Okay, so now we have the Mambo 404 page ready to go. It's time to tell the server to use that page.

Telling the Server to Use Your 404 Page

If Your Web Site is Running on CGI:

When PHP is running under CGI it is effectively disconnected from Apache and Apache directives no longer work (this is what .htaccess is - a method of overriding Apache directives, see my guide to .htaccess). The method of setting up error document handling can vary so if your server space does not have cPanel installed you will need to ask your host how to enable custom error pages on their servers.

If your site does use cPanel, check back in a few days for a tutorial on how to use cPanel to create a custom 404 page.

If Your Web Site is Running on Apache:

Most hosts allow htaccess overrides. If you have enabled SEF URL's in Mambo then you already have an .htaccess file in place. If you do not have a file named .htaccess (note the dot or period before the name "htaccess") in your site root then please check with your host before proceeding. An incorrectly written .htaccess directive can potentially bring down your site.

If you are not able to use .htaccess on your server check back in a few days for my tutorial on how to use cPanel to create a custom 404 page.

If you are using .htaccess and are running Apache 2, you may be able to use Apache's error handling to directly use your new 404 page. This method has not been tested by me on Apache 4 so if you do try it don't blame me if anything goes wrong!
This is where the non-SEF URL to your page comes in. Apache treats each forward slash / as indicating a directory so it cannot understand the Mambo SEF URL's. Depending on how your server is set up, it may not understand the query strings in the non-SEF URL's either so when you add this to your .htaccess file, save, but be prepared to go back and edit it out if necessary.

This is what we add to .htaccess:

ErrorDocument 404 /your-non-sef-url

The file is always relative to the site root, so for Mambo this .htaccess directive will be something like this:

ErrorDocument 404 /index.php?option=com_content&task=view&id=179&Itemid=30

Don't worry about using a non-SEF URL because the rewriting of the URL happens after the error document handling and visitors hitting a 404 will land on the correct page.

If this does not work for you and you are not using cPanel on your server space, you will need to create a redirect page. Open any text editor and enter this:

 <?php
  header( "HTTP/1.1 301 Moved Permanently" );
  header( "Status: 301 Moved Permanently" );
  header( "Location: http://your-SEF-URL" );
  exit();
?>

Save this file as error.php and place it in your site root.

In .htaccess, enter this:

ErrorDocument 404 /error.php

Note: Although a redirect to a 404 is not ideal, this method will not cause problems for search engines.

Test

Test that your .htaccess directives work by refreshing your site in your browser then entering a non-existent URL on your site. If your new 404 page loads then you know its all working.

Check your Error Logs
Whether you use a custom 404 error page or leave the server to deliver the default message, files that cannot be found can result in a lot of unnecessary HTTP requests to your server. It is important to minimise these and, ideally, the only 404 errors you should see in your logs will be errors relating to misspelled URL's. This becomes even more important when you are using a page from within Mambo as your custom 404 error page - not only will your server have HTTP requests to deal with but it will also generate database queries. Even on very large, busy sites I have used Mambo for 404's without problems. The secret to this is to ensure you do not have any missing images or files within your site.

Use your error logs to pinpoint missing image files or problems within your site that are generating 404 errors. If your own site has internal 404 errors you will create unnecessary server load.

If you are worried about server load or if your site is not performing optimally then it is safer to use a static 404 error page. I will be showing you how to do this in another tutorial.

If your site is running on IIS I will be adding a tutorial for this within the next few days.

UPDATE: The tutorial for using your custom Mambo 404 Error Page with IIS has now been published.