Creating Joomla Templates
|
Learn how to code your own Joomla template by downloading the HD-Framework and following the master-class below. The guide covers everything you need to know to create your own template for Joomla 1.5 & 1.6+
|
 |
template structure | the html | the css | the xml for 1.5 | the xml for 1.6 | template overides | zipping up!
This guide provides an overview of how a Joomla template works and how you can build one yourself. It makes reference to HD-Framework, a lightweight bare-bones template framework that provides a clean starting point for you to build your own unique fast loading sites. The guide covers template building for both Joomla 1.5 & Joomla 1.6 with the main difference between the two highlighted in the XML section near the end of this page.
The HD-Framework is available to download for Joomla 1.5 here.
It is also available to download for Joomla 1.6 & 1.7 here.
The guide presumes you have some basic knowledge of HTML & CSS but don't worry if you don't as it does include links to more in-depth tutorials for your reference.
Template Structure
All templates are stored within folders in the templates directory. They can contain many sub-folders and additional files but there are only really three essential files that are needed to create a basic template, they are…
|
|
templateDetails.xmlThis file acts as a map, listing all the files that the template will require (including separate image files) in order to install correctly. It provides details of the template itself (such as name, author, copyright information, description) and also lists all the various module positions that are available.
|
To keep things tidy the CSS file is often stored within its own folder (called “css”) and any images used in the template are stored in a file called “images”.
The HD Framework also includes a folder called "html". This is where the template overide files are stored.
|
|
|
|
index.phpThis file draws out the structure of the web-page, determining which module positions will be used, how they will be set out, and which CSS file(s) it will refer to for styling purposes. The index.php file can be edited via Joomla’s administration panel.
|
||
|
|
template.css / editor.cssThis sets the style of the template. It determines text colour, size, font and line space. It sets the widths and heights of the module positions and also other elements such as background images, hyperlinks and rollovers. The CSS file can also be edited via Joomla’s administration panel. Only one CSS file is required but for reasons that will be explained later the HD-Framework uses two files (“editor.css” & “template.css”). |
|
There are three other files that are often found within the template folder but are not essential for the template to work.
template_thumbnail.pngThis is the thumbnail image that represents the template. It is displayed in the admin panel > template manager when a user rolls the mouse over the list of templates that are installed.
favicon.icoThe favicon is the small 16x16 px image displayed beside the URL and the bookmarks page in most browsers. If it isn’t used the joomla icon is displayed as default. Favicons can be created online at http://favicon.cc
error.phpThis is the error file that is displayed if someone tries to a view a non-exisant or mispelt URL. Also known as a "404" page, if you do not have one in your template folder then Joomla's default error page is displayed instead. |
The HTML
The HTML file that you edit via the template manager is actually the index.php file. It is structured in the same way as standard HTML with a <head> section (where the hidden code is stored) and a <body> section (where the displayed code is stored) but you will notice that unlike standard HTML web pages it is very brief (the entire code is displayed below); this is because the PHP populates the page with additional HTML (such as article/module content) pulled from the MySQL database. So every page you visit on your Joomla site is essentially this file plus database data.
The area in yellow highlights the document type. The default language of the website is determined by the Joomla configuration settings and echoed on line 2.
The area highlighted in green is the <head> section. The first line requests the main metadata settings from the Joomla database (including meta description, meta keywords, meta author, etc). You can also set metadata here that will overwrite the deault settings: for example Line 7 sets the metagenerator tag to echo the template parameters (instead of the standard Joomla 1.5).
Line 5 & 6 set out the location of the CSS files. If you change the name of the template or CSS file you will need to ensure this line is also changed as otherwise the route to the file will be broken. In this case you will notice there are two small snippets of PHP in this section:-
<?php echo $this->baseurl ?> This inserts the base url (eg. hyde-design.co.uk) in its place.
<?php echo $this->template ?> This inserts the template name (eg. hd-framework) in its place.
Both are useful if you intend to install the template on numerous sites or wish to change the template name but don't want to keep updating all the references for it. Links to additional CSS/Javascript files will also be placed in the <head> section and if you use Google's webmaster tools this is where the verification code should be stored.
The area highlighted in blue is the <body> section. This is essentially a list of divs that will be displayed in that specific order but calls upon the Joomla database to populate the divs with content and calls upon the CSS file to state the height/width position and styling elements (text colour, background image, etc). The important element here is that for every div that is treated as a module position the following code is included…
<jdoc:include type="modules" name="whatever"/></strong></p>
<p> </p>
<p>With “whatever” being the module position title. Similarly, the Joomla Article contents will be displayed in place of this code…</p>
<p><br /><strong><jdoc:include type="component"/></strong><br /><br /></p>
<p>If you are new to HTML & CSS then there is a more in-depth guide to designing wireframes <a href="http://www.hyde-design.co.uk/joomla-training/building-joomla-templates/css-wireframes">here.
If you are feeling a bit adventurous and would like to include collapsable module positions in your template (so that the layout varies depending on which modules are used) then click here.
The CSS
The CSS file contains all of the styling information that you apply to the divs specified in the HTML file. You only really need one CSS file but the HD-Framework template uses two: editor.css and template.css. The first file houses all the typography styles whereas the second file houses the layout styles. It is split in two because Joomla’s default WYSIWYG editor (TinyMCE) checks the template folder for the inclusion of “editor.css” and, if found, lets you use those CSS classes in the WYSIWYG editor. By seperating this file in two you ensure that the site typography can be viewed accurately in the editor without the interference of background images, background colours and other layout elements.
The below code is the entire CSS for the template.css file.
The area in yellow is the reset area, ensuring the values for the classes "float" and "clear" are set out properly.
The area in green sets out the style of the main body including the background image which is stored in a folder called "images". It also sets out the size of the container that houses all the divs on the page, ensuring that the maximum width of the page is 980px and that the container will be centred in the middle of the browser screen. Anything beyond a width of 980px may exceed the display of smaller monitor screens so it is advised to keep within this limit (otherwise those users may have to scroll from left to right to view the whole screen).
The area in blue sets out the main wireframe, including the div heights, widths, padding and the direction in which they float (in relation to the previous divs). Don't forget, if you're new to CSS there is a more in-depth guide to designing wireframes here.
The below code is the entire CSS for the editor.css file.
Again, the area in yellow is the reset area, it ensures that the padding and margin values are reset and that there is no border applied to any of the images.
The green area sets out the style for some common css rules, including the font family, font size, line height and colour of the main body text. In addition it sets out the rules for anything tagged as H1, H2 and H3 as well as .componentheading and .contentheading (classes that are commonly used by Joomla for page headings).
The final blue area includes the CSS instructions (including the link, visited and hover states) for the class known as .class1
Tagging content with classes allows them to be styled differently from the main body text, therefore the hyperlink behaviour (colour, underline, text-weight) of any content tagged with .class1 will be different to the normal hyperlink behaviour. Because this CSS file is titled editor.css Joomla's default WYSIWYG editor will pick up this class and include it in the editor so you can easily apply it to content. Otherwise you can apply classes to article tect by wrapping it with the following HTML...
<span class=".whatever"> </strong>text<strong> </span></strong></p> <p> </p> <p>As this is a template file, these CSS rules will be applied to <em>all</em> pages on your site, for information on how you can use the <a href="http://www.hyde-design.co.uk/free-joomla-extensions/hd-customcss">HD-CustomCSS module to apply different styles to different pages, click here.
The XML (1.5)
The templateDetails.xml file can't be edited via the template manager so you should only really edit this before you install a template. The file can be broken down into four sections: Authorship, file-map, module positions and parameters. It is important to note that the XML file for Joomla 1.6 templates is different to the XML file for Joomla 1.5. If you're building for Joomla 1.6 you can skip this bit and jump to here. If you're building for Joomla 1.5 you can read this bit only and skip the following section. And if you're interested in the difference between the two then just read both...
The below is the entire code for the 1.5 version of templateDetails.xml
The yellow section defines this as being an installation for Joomla 1.5 and provides authorship details such as template name, author name, author date, etc. It also includes the description that is displayed the first time you install the template. It is important to note that the name of the template is the one used when creating the folder during the installation process, therefore if you change the name of the "hd-framework" template make sure you also change any reference to this in the index.php file or broken links may occur.
The section in green lists all the files within the template that you wish to install. Each individual filename is tagged <filename> and folders are tagged <folder>. All files within a folder will automatically be installed so you do not have to tag those filenames seperately.
The section in blue lists all the module positions you wish to include in the template. This is the same list that appears in the drop down menu of the Module Manager page. Users can also type in their own module position names but it is useful for them if the positions are stated beforehand.
The section in pink includes the parameters. These are the elements that appear on the template manager page that allow you to change how your template operates. In this case line 32 declares a text only parameter that the index.php file uses as a metagenerator tag (replacing <meta generator="Joomla 1.5"> with whatever is typed in the parameter box) and line 34 is merely a text box that allows you to save notes with the template manager page. This are fairly simple changes but parameters can be used to switch style-sheets, completely changing the appearence, layout and behaviour of your template. A more in depth guide to template parameters is available <a href="http://www.hyde-design.co.uk/joomla-training/building-joomla-templates/template-parameters">here.
The XML (1.6)
The below is the entire code for the 1.6 version of templateDetails.xml
Like the version for 1.5 it maps out the authorship details (highlighted in yellow), the files it will install (green), the module positions it uses (blue) and the parameters (pink), only the format of the tags is slightly different. A parameter is declared between <field> tags which is in turn part of a <fieldset> which is encased in <fields> tags, which is finally encased between <config> tags.
Template Overides
One of the more powerful features of Joomla 1.5 is the ability to overide certain default Joomla settings from within a template. In other words you can simply replicate various core files and tweak them to your liking and they will be used as a priority over the core files.
The overide files must be stored within your templates directory in a folder called “html”. Further sub folders may also be needed to mirror the directory structure, however you do not need to include any “views” or “tmpl” folders.
For example the PHP file that sets out the article display layout is housed here…
yourWebsite > Components > com_content > views > article > tmpl > default.php
But to include it within your template folder you simply drop the “views” or “tmpl” inclusion to make…
yourTemplate > html > com_content > article > default.php
When your template is set to default, Joomla will check if there are any overides in the “html” folder and (if so) will use them instead of the default settings.
Finally... Zipping up!
Now that you have your files in place, simply zip the contents up and try installing on a Joomla site.
In case you missed them previously here is the full list of links to the more detailed guides:-