How Joomla template index.php works
index.php is the main file of any Joomla template. This file is loaded by the CMS during displaying each page of the site. It inclides all necessary content, other PHP files, CSS styles, images and so on.
index.php may contain jdoc includes and PHP code blocks with custom PHP code. Since PHP is a very flexible language the code in PHP code blocks can do anything to build the output. Joomla CMS provides the developers with the API that simplifies the template development by providing shortcuts for frequently reused code fragments.
A few API examples:
<link rel="stylesheet" href="<?php echo $this->baseurl;
?>/templates/system/css/system.css" type="text/css" />
<?php if($this->countModules(’left’)) : ?>
<div id="maincolumn">
<?php else: ?>
<div id="maincolumn_full">
<?php endif; ?>
As you may see on these examples, the index.php file is executed in the context of some object and this object has a few usefull methods and properties for template developers:
- title - page title
- description - page description
- language - page language
- params - collection of template parameters, defined in templateDescription.xml
- template - name of the template
- direction - document direction, ltr (left-to-right) or rtl (right-to-left)
- countModules(condition) - counts modules based on the given condition
This object is an instance of the JDocumentHTML class, defined in the libraries\joomla\document\html\html.php file. By reviewing the code of that file you can find more information about properties and methods of this class.
jdoc:include is a shortcut to the $this->getBuffer(type, name, args) function call. jdoc:include and getBuffer function create corresponded renderer class and executes its render(…) method. The following renderers are available:
- component - outputs the component
- head - renders head HTML elements such as script, link, meta, style.
- message - displays message queue
- module - renders module blocks which are in the given placeholder.
- modules - renders all modules in the given placeholder.
Among these renderers only module and modules can accept name and parameters. For the modules renderer the name argument contains placeholder name, for the module renderer the name contains module name that will be renderer.
The modules renderer calls the module renderer for each module placed in the placeholder and the module renderer calls JModuleHelper::renderModule(module, params) to render the module blocks.
JModuleHelper is defined in libraries\joomla\application\module\helper.php and contains methods for loading module settings from the database and rendering the module.
Module performs the following steps to render its content:
- Initialize parameters, which are based on attributes of the jdoc:include tag.
- Executing module PHP file from modules folder.
- Framing module output with decorating function from the templates\system\html\modules.php or templates\{current_template}\html\modules.php file.