Posts Tagged ‘template’

Overwriting Joomla module or component views in the template

Monday, January 26th, 2009

Most of the Joomla modules and components have one or more templates that define how the content will be displayed by Joomla. These files are stored in the modules/mod_[module]/tmpl and components/com_[component]/views/[view]/tmpl folders and can be overwritten by the template.

Typical Joomla module has one view and this view is stored in file named default.php in the tmpl folder of the mode. Differently from modules, the standard components have several views, each for different component mode.

For example, the mod_poll module has one view that displays a list of poll options and buttons. The com_content component has several views: archive, article, category, frontpage, section.

Default views of the modules and components may be overwritten in the template by creating a file in specific location: the templates/[template]/html/com_[component]/[view]/ folder for the component and the templates/[template]/html/mod_[module]/ folder for the module. While rendering, Joomla looks into these folders for files that overwrite views and if a file with the same name exists, it uses it instead of the default view file.

The Beez template, shipped with Joomla, overwrites the templates of several components and modules so you can look through its html folder to get examples on how to customize component and module views for different modes.

Creating new Joomla template

Saturday, October 11th, 2008

You can download the GreenField template on this page: GreenField template for Joomla.

The simplest way to create a new template is to base it on one of the existent template. Joomla is shipped with three templates, beez, JA_Purity, and rhuk_milkyway. rhuk_milkyway is the default template so let’s copy it to the greenfield folder and modify its design.

Milkyway template

Milkyway template

The goal, Greenfield template.

The goal, Greenfield template.

First, the template information in templateDetails.xml should be changed because Joomla reads the template name from this file and now we have two rhuk_milkyway templates. To change it, open the greenfield\templateDetails.xml file and change template information tags as follows:

<name>Green Field</name>
<creationDate>10/08/08</creationDate>
<author>CMS Lamp</author>
<authorEmail>cms.lamp@gmail.com</authorEmail>
<authorUrl>http://cmslamp.com/</authorUrl>
<copyright></copyright>
<license>GNU/GPL</license>
<version>1.0.0</version>
<description>Nice green theme</description>

The params section in templateDetails.xml may be removed and the content of the params.ini file can be removed too. Then we can continue by editing index.php.

index.php has milkyway-related includes and HTML tags so let’s remove them: several links to styles, code related to text order (ltr/rtl), the id and class attrbites of the body tag, html tags in body tag. GreenField will not support complex layouting and some of the placeholders so all these content may be removed too (from index.php and templateDetails.xml).

We end up with a very simple index.php:

<?php
// no direct access
defined( '_JEXEC' ) or exit( 'Restricted access' );
?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="<?php echo $this->language;
?>" lang="<?php echo $this->language; ?>" >
<head>
<jdoc:include type="head" />
</head>
<body>
<!-- breadcrumb -->
<jdoc:include type="modules" name="breadcrumb" />
<!-- message -->
<jdoc:include type="message" />
<!-- left column -->
<jdoc:include type="modules" name="left" style="rounded" />
<!-- main column -->
<jdoc:include type="component" />
<!-- right column -->
<jdoc:include type="modules" name="right" style="xhtml"/>
<!-- page footer -->
<jdoc:include type="modules" name="syndicate" />
<!-- powered by -->
<?php echo JText::_('Powered by') ?> <a href="http://www.joomla.org">Joomla!</a>,
<a href="http://cmslamp.com/joomla-template/greenfield">Joomla template</a> by
<a href="http://cmslamp.com/">CMS Lamp</a>.
</body>
</html>

and templateDetails.xml:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE install PUBLIC "-//Joomla! 1.5//DTD template 1.0//EN"
"http://dev.joomla.org/xml/1.5/template-install.dtd">
<install version="1.5" type="template">
  <name>Green Field</name>
  <creationDate>10/08/08</creationDate>
  <author>CMS Lamp</author>
  <authorEmail>cms.lamp@gmail.com</authorEmail>
  <authorUrl>http://cmslamp.com/</authorUrl>
  <copyright></copyright>
  <license>GNU/GPL</license>
  <version>1.0.0</version>
  <description>Nice green theme</description>
  <files>
    <filename>index.php</filename>
    <filename>templateDetails.xml</filename>
    <filename>template_thumbnail.png</filename>
    <filename>params.ini</filename>
  </files>
  <positions>
    <position>menu</position>
    <position>breadcrumb</position>
    <position>left</position>
    <position>right</position>
    <position>syndicate</position>
  </positions>
</install>

Creating HTML template is a complex task, so I suppose that HTML template is available. In this case the next step is very simple: accuratelly copy the content from the HTML template to the GreenField Joomla template, placing <jdoc:include … /> in correct places.

jdoc modules include allows to select block decorator. It may be one of the standard decorators defined in templates\system\html\modules.php: none, table, horz, xhtml, rounded, and outline, or template-specific decorators from html\modules.php file of the particular template.

The GreenField template has one decorator for blocks, called gfblock, which applied to the top, menu, left, and right placeholders. This decorator adds nice border and caption for the module blocks. The top placeholder processed differently: menu module output is changed to match the HTML template menu.

To make GreenField looks similar to the HTML template, site headline and slogan patrameters should be added. After registering parameters in templateDetails.xml and set their default values in params.ini they will appear in template parameters in Joomla adminstrating section.

And the final step is adding theme files to templateDetails.xml.

You can download the GreenField template on this page: GreenField template for Joomla.

How Joomla template index.php works

Wednesday, October 8th, 2008

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:

  1. Initialize parameters, which are based on attributes of the jdoc:include tag.
  2. Executing module PHP file from modules folder.
  3. Framing module output with decorating function from the templates\system\html\modules.php or templates\{current_template}\html\modules.php file.