Tutorial:Advanced topics

Templates are executed in a 2-phase process that makes full use of the PHP parser to provide considerable flexibility and performance to the template designer. Templates are executed in the context of the document object so that the $this object is always the instantiation of the JDocument class.

Before template execution begins, the component will have been executed and its output buffered for later use.

Template execution then proceeds as follows:-

• template parameters (if any) are loaded.
• template language (if any) is loaded.
• if legacy mode is on then the configuration variables are copied as globals.
• the template file (index.php) is loaded and executed (by PHP). The output is buffered. This is phase 1 of the 2-phase process. Everything between <?php and ?> tags is executed as PHP code. Everything outside of these tags is output but otherwise ignored. As the output is being buffered, nothing is sent to the client web browser at this stage.
• a favicon.ico file is looked for, first in the Joomla! root directory, then in the template root directory. The latter will override the former if found.
• the output that was buffered in phase 1 is now parsed for <jdoc:include> elements. This is phase 2 of the process. For each jdoc element found, the appropriate renderer class is loaded and its render method is called. The output from the render method replaces the <jdoc:include> element itself in the output buffer. In the case of module renderer classes this triggers the execution of the modules and the buffering of their output.
• Certain template-specific HTTP headers are added to the list of headers to be output.
• Control is then passed back to the JApplication object which will handle the rest of the process of getting the now rendered web page back to the client web browser.

System error pages

By default Joomla! uses special templates when it needs to raise an error response. These are located in the templates/system directory. For server-level status codes these are named for the status code that is being raised. These are the default system error pages available:-

• templates/system/403.php (Status code: 403 Forbidden)
• templates/system/404.php (Status code: 404 Not Found)
• templates/system/500.php (Status code: 500 Internal Server Error)

The status codes are defined as part of the HTTP protocol in RFC2616. For further information on HTTP status codes see: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

These pages can be styled using the following CSS classes:

• errorboxheader
• errorboxbody
• techinfo

In addition, these system error pages are also available:

• templates/system/component.php (not sure when this is used)
• templates/system/offline.php is used to render the "site is offline" message.

Note that jdoc:include elements are not parsed in these error pages.

Custom error pages

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 the error.php is an independent file from Joomla!. Plugins do not run on the file. You cannot include modules or use <jdoc:include> statements.

Overriding the System Error Results

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

If you want to change the styling, copy the templates/system/css/error.css file into your templates/<template-name>/css directory.

Next, update the 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

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->code = '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

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->code = '404') {
	header("HTTP/1.0 404 Not Found");
} ?>

More HTTP status code information:

• HTTP/1.1 Status Code Definitions
• Google Webmaster - Analyzing Crawl Errors

This article is a small, well-defined item that could be completed by someone with a reasonable knowledge of the subject matter and a modest time commitment. If you would like to try writing this article you're welcome to do so. The subject may be self-evident, but if not then further details should be available on the discussion page. Please add {{inuse}} at the top of this page while editing. For other small, well-defined tasks, please look in the Cookie jar. Thank you.

Adding JavaScript

This chunk should describe in detail how to add JavaScript to the head of a template using the Joomla! 1.5 API calls. It should be aimed at people who have only minimal knowledge of PHP, HTML and JavaScript.

Add the following code to have the javascript library /media/system/js/sample.js included in your template.

<?php
$document = &JFactory::getDocument();
$document->addScript( '/media/system/js/sample.js' );
?>

Explanation

Ultimately you are trying to have the resulting HTML page have in the <head> ... </head> area have a javascript include:

For Example:

<script type="text/javascript" src="/media/system/js/sample.js"></script>

Ensure that the javascript you want to include is in the directory, from the above example:

/media/system/js/sample.js

When you are able to load both your page and see the <script> tag in the <head> area, and be able to load the javascript from the address

Again, using the example:

  http://www.example.com/media/system/js/sample.js

Then the script is integrated into your page, and you can proceed to using javascript in your HTML.

Do not directly add the <script> to your template's index.php.

The code will insert the the <script> line where your index.php has the following line:

<jdoc:include type="head" />

Add this PHP code to your page, in the head, or next to the javascript code you will use, depending on your preference.

<?php
$document = &JFactory::getDocument();
$document->addScript( '/media/system/js/sample.js' );
?>

Reload your template and view the paga, and ensure that the sample.js is included in the <head>

Different web browsers sometimes show differences in the way that they render a page. For this reason you may wish to find out which particular browser a visitor is using, in order to use some browser-specific CSS.

The following javascript defines a simple browser detection object, by decoding the navigator.userAgent string

/************************************/

function browserDetect() {

 var browserNames=new Array("Opera", "MSIE","Netscape","Firefox");
 this.name="NK";
 this.mainVersion="NK";
 this.minorVersion="NK";
 
 for (var i=0; i< browserNames.length; i++)
 {
  var pattern='('+browserNames[i]+')'+'.([0-9]+)\.([0-9]+)';    
  var myRegExp=new RegExp(pattern);
  if (myRegExp.test(navigator.userAgent))
   {
     var results=myRegExp.exec(navigator.userAgent);
     this.name=results[1];
     this.mainVersion=results[2];
     this.minorVersion=results[3];
     break;
   }
 }

}

/*****************************/

In order to use this in a script, you then create an instance of this object:-

var browser = new browserDetect();

The property browser.name will then give you then name of the browser (MSIE, Opera, Netscape or Firefox), browser.mainVersion will give you the main version number, browser.minorVersion will give you the minor version number.

However you should be aware that this is not-foolproof, and it is generally better (in this writer's opinion) to avoid writing browser-specific code as far as possible.

This article is a small, well-defined item that could be completed by someone with a reasonable knowledge of the subject matter and a modest time commitment. If you would like to try writing this article you're welcome to do so. The subject may be self-evident, but if not then further details should be available on the discussion page. Please add {{inuse}} at the top of this page while editing. For other small, well-defined tasks, please look in the Cookie jar. Thank you.

This article is a small, well-defined item that could be completed by someone with a reasonable knowledge of the subject matter and a modest time commitment. If you would like to try writing this article you're welcome to do so. The subject may be self-evident, but if not then further details should be available on the discussion page. Please add {{inuse}} at the top of this page while editing. For other small, well-defined tasks, please look in the Cookie jar. Thank you.

This article is a small, well-defined item that could be completed by someone with a reasonable knowledge of the subject matter and a modest time commitment. If you would like to try writing this article you're welcome to do so. The subject may be self-evident, but if not then further details should be available on the discussion page. Please add {{inuse}} at the top of this page while editing. For other small, well-defined tasks, please look in the Cookie jar. Thank you.