Difference between revisions of "Custom error pages"

From Joomla! Documentation

(New page: === Custom error pages === The standard system error pages can be overriden by adding specially-named and constructed files to the template directory. For example, this could be used to s...)
 
(Use getCode() instead of private attribute)
(22 intermediate revisions by 14 users not shown)
Line 1: Line 1:
−
=== Custom error pages ===
+
<noinclude><languages /></noinclude>
−
The standard system error pages can be overriden by adding specially-named and constructed files to the template directory. For example, this could be used to style the error pages so that they match the style of regular pages for the template.
+
<noinclude>{{JSplit}}</noinclude>
 +
<translate>
 +
<!--T:1-->
 +
Joomla! uses the <tt>templates/system/error.php</tt> file to handle several HTTP Status errors, including "403 Forbidden", "404 Not Found", and "500 Internal Server" errors. You can style the error results, if desired.
 +
</translate>
  
−
Placing one or more of the following files into the templates/<template-name> directory will override the similarly named file in the templates/system directory.
+
<translate>
 +
<!--T:2-->
 +
It is important to understand that ''error.php'' is an independent file from the Joomla! CMS but dependent on the Joomla! Platform. Plugins do not run on the file. You cannot include modules or use  <tt><jdoc:include></tt> statements.
 +
</translate>
  
−
* templates/<template-name>/403.php (HTTP Status code: 403 Forbidden)
+
<translate>
−
* templates/<template-name>/404.php (HTTP Status code: 404 Not Found)
+
====Overriding the System Error Results==== <!--T:3-->
−
* templates/<template-name>/500.php (HTTP Status code: 500 Internal Server Error)
+
To override the system error results, copy the <tt>templates/system/error.php</tt> file into your <tt>templates/<template-name></tt> directory.
−
* templates/<template-name>/component.php (not sure when this is used)
+
</translate>  
−
* templates/<template-name>/offline.php ("Site is offline" error page)
 
  
−
To render the error backtrace information when debugging mode is on you can call the renderBacktrace method like this:
+
<translate>
 +
<!--T:4-->
 +
If it finds one, Joomla! will use the <tt>error.php</tt> file from the current template, in place of the system file.
 +
</translate>
 +
 
 +
<translate><!--T:5-->
 +
You can format the page, as desired, to match your template.</translate>
 +
 
 +
<translate>
 +
====Overriding the System Styling==== <!--T:6-->
 +
If you want to change the styling, copy the <tt>templates/system/css/error.css</tt> file into your <tt>templates/<template-name>/css</tt> directory.
 +
</translate>
 +
<translate>
 +
<!--T:7-->
 +
Next, update your <tt>templates/<template-name>/error.php</tt> file to reference the new location of the stylesheet by changing this line, accordingly:
 +
</translate>
 +
 
 +
<source lang="css"><link rel="stylesheet" href="<?php echo $this->baseurl; ?>/templates/system/css/error.css" type="text/css" /></source>
 +
 
 +
<translate><!--T:8-->
 +
Then, simply change the <tt>error.css</tt>, as desired, for your styling requirements.</translate>
 +
 
 +
<translate>
 +
====Customizing Error Messages==== <!--T:9-->
 +
You can add conditional logic to vary the message returned, dependent upon the specific error code.
 +
</translate>
 +
 
 +
<translate>
 +
<!--T:10-->
 +
Here is an example of how to trap a 404 error and provide a custom message.
 +
</translate>
  
 
<source lang="php">
 
<source lang="php">
−
<?php if ($this->debug) :
+
<?php if ($this->error->getCode() == '404') { ?>
−
echo $this->renderBacktrace();
+
<div id="errorboxheader">Page not found</div>
−
endif; ?>
+
<div id="errorboxbody"><p>Sorry! That page cannot be found.</p>
 +
</div>
 +
</div>
 +
<?php } ?>
 
</source>
 
</source>
  
−
Note that jdoc:include elements are not parsed in these error pages.
+
<translate>
−
<noinclude>[[Category:Advanced]][[Category:Templates]][[Category:Topics]]</noinclude>
+
====HTTP Status Code==== <!--T:11-->
 +
When a request is made for a page on your site, the server returns an HTTP status code in response to the request. Joomla! returns a '200 - the server successfully returned the page' for error pages. This is problematic for those working with Google Webmaster Services and trying to get a sitemap resolved.
 +
</translate>
 +
 
 +
<translate>
 +
<!--T:12-->
 +
If you want Joomla! to return a status code for the error, you can do so by adding logic before the DOCTYPE line, as follows:
 +
</translate>
 +
 
 +
<source lang="php">
 +
<?php
 +
if ($this->error->getCode() == '404') {
 +
header("HTTP/1.0 404 Not Found");
 +
} ?>
 +
</source>
 +
 
 +
<translate>
 +
====More HTTP Status Code Information==== <!--T:13-->
 +
</translate>
 +
 
 +
<translate>
 +
<!--T:14-->
 +
* [[S:MyLanguage/Create_a_Custom_404_Error_Page|Create a Custom 404 Error Page]]
 +
* [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html HTTP/1.1 Status Code Definitions]
 +
* [[wikipedia:List_of_HTTP_status_codes|List of HTTP status codes]]
 +
</translate>
 +
 
 +
<translate>
 +
====Using Theme Header and Footer on Standard Error Page==== <!--T:15-->
 +
</translate>
 +
{{JVer|1.5}}
 +
<translate>
 +
<!--T:16-->
 +
If you want to see the error page in theme design and don't like redirecting to error page URL or duplicating HTML in the error page template, here is a way to apply your theme template to the error page.
 +
</translate>
 +
 
 +
<translate>
 +
<!--T:17-->
 +
First, put the following code in <tt>templates/<template-name>/error.php</tt>:
 +
</translate>
 +
 
 +
<source lang="php">
 +
<?php
 +
// no direct access
 +
defined( '_JEXEC' ) or die( 'Restricted access' );
 +
 
 +
include dirname(__FILE__) . "/index.php";
 +
?>
 +
 
 +
</source>
 +
 
 +
<translate>
 +
<!--T:18-->
 +
Then make the following edits to <tt>templates/<template-name>/index.php</tt>:
 +
</translate>
 +
 
 +
<translate>
 +
<!--T:19-->
 +
1. Find the following code in <tt>index.php</tt>
 +
</translate>
 +
 
 +
<source lang="php">
 +
<jdoc:include type="head" />
 +
</source>
 +
 
 +
<translate>
 +
<!--T:20-->
 +
and replace it with the following
 +
</translate>
 +
 
 +
<source lang="php">
 +
<?php if (!$this->error->getCode()) : ?>
 +
<jdoc:include type="head" />
 +
<?php else : ?>
 +
<title><?php echo $this->error->getCode() ?> - <?php echo $this->title; ?></title>
 +
<?php endif; ?> 
 +
</source>
 +
 
 +
<translate>
 +
<!--T:21-->
 +
2. Find the following code in <tt>index.php</tt>
 +
</translate>
 +
 
 +
<source lang="php">
 +
<jdoc:include type="component" />
 +
</source>
 +
 
 +
<translate>
 +
<!--T:22-->
 +
and replace it with the following
 +
</translate>
 +
 
 +
<source lang="php">
 +
<?php if ($this->error->getCode()) : /* check if we are on error page, if yes - display error message */ ?>
 +
  <p><strong><?php echo $this->error->getCode() ?> - <?php echo $this->error->message ?></strong></p>
 +
  <p><strong><?php echo JText::_('JERROR_LAYOUT_NOT_ABLE_TO_VISIT'); ?></strong></p>
 +
  <ol>
 +
    <li><?php echo JText::_('JERROR_LAYOUT_AN_OUT_OF_DATE_BOOKMARK_FAVOURITE'); ?></li>
 +
    <li><?php echo JText::_('JERROR_LAYOUT_SEARCH_ENGINE_OUT_OF_DATE_LISTING'); ?></li>
 +
    <li><?php echo JText::_('JERROR_LAYOUT_MIS_TYPED_ADDRESS'); ?></li>
 +
    <li><?php echo JText::_('JERROR_LAYOUT_YOU_HAVE_NO_ACCESS_TO_THIS_PAGE'); ?></li>
 +
    <li><?php echo JText::_('JERROR_LAYOUT_REQUESTED_RESOURCE_WAS_NOT_FOUND'); ?></li>
 +
    <li><?php echo JText::_('JERROR_LAYOUT_ERROR_HAS_OCCURRED_WHILE_PROCESSING_YOUR_REQUEST'); ?></li>
 +
  </ol>
 +
  <p><strong><?php echo JText::_('JERROR_LAYOUT_PLEASE_TRY_ONE_OF_THE_FOLLOWING_PAGES'); ?></strong></p>
 +
 
 +
  <ul>
 +
  <li><a href="<?php echo $this->baseurl; ?>/index.php" title="<?php echo JText::_('JERROR_LAYOUT_GO_TO_THE_HOME_PAGE'); ?>"><?php echo JText::_('JERROR_LAYOUT_HOME_PAGE'); ?></a></li>
 +
  </ul>
 +
 
 +
  <p><?php echo JText::_('JERROR_LAYOUT_PLEASE_CONTACT_THE_SYSTEM_ADMINISTRATOR'); ?>.</p>
 +
<?php else : ?>
 +
  <jdoc:include type="component" />
 +
<?php endif; ?>
 +
</source>
 +
 
 +
<translate>
 +
<!--T:23-->
 +
Now your theme template is applied to error pages too.
 +
</translate>
 +
 
 +
<translate>
 +
<!--T:24-->
 +
'''Note:''' Module includes in template will not work on error page created by this method (but will work on other pages).
 +
</translate>
 +
 
 +
<noinclude>
 +
<translate>
 +
<!--T:25-->
 +
[[Category:Tutorials]]
 +
[[Category:Template Development]]
 +
</translate>
 +
</noinclude>

Revision as of 04:42, 13 November 2015

Other languages:
Deutsch • ‎English • ‎Nederlands • ‎español • ‎français • ‎русский • ‎中文（台灣）‎
Split-icon.png
Split Page into Specific Joomla! Versions - J2.5 and 3.x

It has been suggested that this article or section be split into specific version Namespaces. (Discuss). If version split is not obvious, please allow split request to remain for 1 week pending discussions. Proposed since 8 years ago.

Joomla! uses the templates/system/error.php file to handle several HTTP Status errors, including "403 Forbidden", "404 Not Found", and "500 Internal Server" errors. You can style the error results, if desired.

It is important to understand that error.php is an independent file from the Joomla! CMS but dependent on the Joomla! Platform. Plugins do not run on the file. You cannot include modules or use <jdoc:include> statements.

Overriding the System Error Results[edit]

To override the system error results, copy the templates/system/error.php file into your templates/<template-name> directory.

If it finds one, Joomla! will use the error.php file from the current template, in place of the system file.

You can format the page, as desired, to match your template.

Overriding the System Styling[edit]

If you want to change the styling, copy the templates/system/css/error.css file into your templates/<template-name>/css directory. Next, update your templates/<template-name>/error.php file to reference the new location of the stylesheet by changing this line, accordingly: 

<link rel="stylesheet" href="<?php echo $this->baseurl; ?>/templates/system/css/error.css" type="text/css" />

Then, simply change the error.css, as desired, for your styling requirements.

Customizing Error Messages[edit]

You can add conditional logic to vary the message returned, dependent upon the specific error code.

Here is an example of how to trap a 404 error and provide a custom message. 

<?php  if ($this->error->getCode() == '404') { ?>
	<div id="errorboxheader">Page not found</div>
		<div id="errorboxbody"><p>Sorry! That page cannot be found.</p>
		</div>
	</div>
<?php } ?>

HTTP Status Code[edit]

When a request is made for a page on your site, the server returns an HTTP status code in response to the request. Joomla! returns a '200 - the server successfully returned the page' for error pages. This is problematic for those working with Google Webmaster Services and trying to get a sitemap resolved.

If you want Joomla! to return a status code for the error, you can do so by adding logic before the DOCTYPE line, as follows: 

<?php 
if ($this->error->getCode() == '404') {
	header("HTTP/1.0 404 Not Found");
} ?>

More HTTP Status Code Information[edit]

Using Theme Header and Footer on Standard Error Page[edit]

Joomla 1.5 If you want to see the error page in theme design and don't like redirecting to error page URL or duplicating HTML in the error page template, here is a way to apply your theme template to the error page.

First, put the following code in templates/<template-name>/error.php: 

<?php
// no direct access
defined( '_JEXEC' ) or die( 'Restricted access' );

include dirname(__FILE__) . "/index.php";
?>

Then make the following edits to templates/<template-name>/index.php:

1. Find the following code in index.php 

<jdoc:include type="head" />

and replace it with the following 

<?php if (!$this->error->getCode()) : ?>
<jdoc:include type="head" />
<?php else : ?> 
<title><?php echo $this->error->getCode() ?> - <?php echo $this->title; ?></title>
<?php endif; ?>

2. Find the following code in index.php 

<jdoc:include type="component" />

and replace it with the following 

<?php if ($this->error->getCode()) : /* check if we are on error page, if yes - display error message */ ?>
  <p><strong><?php echo $this->error->getCode() ?> - <?php echo $this->error->message ?></strong></p>
  <p><strong><?php echo JText::_('JERROR_LAYOUT_NOT_ABLE_TO_VISIT'); ?></strong></p>
  <ol>
    <li><?php echo JText::_('JERROR_LAYOUT_AN_OUT_OF_DATE_BOOKMARK_FAVOURITE'); ?></li>
    <li><?php echo JText::_('JERROR_LAYOUT_SEARCH_ENGINE_OUT_OF_DATE_LISTING'); ?></li>
    <li><?php echo JText::_('JERROR_LAYOUT_MIS_TYPED_ADDRESS'); ?></li>
    <li><?php echo JText::_('JERROR_LAYOUT_YOU_HAVE_NO_ACCESS_TO_THIS_PAGE'); ?></li>
    <li><?php echo JText::_('JERROR_LAYOUT_REQUESTED_RESOURCE_WAS_NOT_FOUND'); ?></li>
    <li><?php echo JText::_('JERROR_LAYOUT_ERROR_HAS_OCCURRED_WHILE_PROCESSING_YOUR_REQUEST'); ?></li>
  </ol>
  <p><strong><?php echo JText::_('JERROR_LAYOUT_PLEASE_TRY_ONE_OF_THE_FOLLOWING_PAGES'); ?></strong></p>

  <ul>
  <li><a href="<?php echo $this->baseurl; ?>/index.php" title="<?php echo JText::_('JERROR_LAYOUT_GO_TO_THE_HOME_PAGE'); ?>"><?php echo JText::_('JERROR_LAYOUT_HOME_PAGE'); ?></a></li>
  </ul>

  <p><?php echo JText::_('JERROR_LAYOUT_PLEASE_CONTACT_THE_SYSTEM_ADMINISTRATOR'); ?>.</p>
<?php else : ?>
  <jdoc:include type="component" />
<?php endif; ?>

Now your theme template is applied to error pages too.

Note: Module includes in template will not work on error page created by this method (but will work on other pages).

Retrieved from "https://docs.joomla.org/index.php?title=Custom_error_pages&oldid=259506"