Joomla Template Tutorial
How to convert an oswd.org template into a Joomla! template.
0) Understand how Joomla places content. In Joomla 1.0x, there is one central content 'component' surrounded by several smaller 'modules'. These modules are placed in template positions. To see the positions on a Joomla page, add '?tp=1' to the page's url.
1) Go to http://www.oswd.org and pick a template. Hints: Pick one that uses list items for menus, clean design, can envision modules on the current design. We'll work with one of the more popular designs: andreas01
2) Download it. It'll be a zip file. As long as I was on the oswd website, I took a screen capture of the template for later use. I used knsapshot from my Kubuntu desktop and saved it as a png file.
3) Unzip the template and see what we've got. Looks like this:
-rw------- 1 brent brent 2927 2005-07-25 20:52 andreas01.css
-rw------- 1 brent brent 362 2005-06-09 03:09 bg.gif
-rw------- 1 brent brent 16833 2005-07-23 03:07 front.jpg
-rw------- 1 brent brent 4716 2005-07-25 20:59 index2.html
-rw------- 1 brent brent 4651 2005-07-25 21:02 index.html
-rw------- 1 brent brent 793 2005-07-25 21:07 print.css
-rw------- 1 brent brent 1290 2005-07-23 05:14 test.jpg
I open the index.html file in Firefox and see the layout. I open up firebug and find that the left column is generated by the css div called 'avmenu', the center by 'content' and the right by the 'extras'. The footer is 'footer'.
4) Start editing the files. Looks like we'll mainly need to edit the index page. Joomla is php based, so the index.html needs to become index.php as:
mv index.html index.php
a) We add php code to the top to make sure the template's not called apart from Joomla and to set the endocing as:
defined( '_VALID_MOS' ) or die( 'Restricted access' );
// needed to seperate the ISO number from the language file constant _ISO
$iso = explode( '=', _ISO );
// xml prolog
echo '<?xml version="1.0" encoding="'. $iso .'"?' .'>';
b) Next, replace the title element and meta elements with the php code to generate them:
<?php mosShowHead(); ?>
<meta http-equiv="Content-Type" content="text/html; <?php echo _ISO; ?>" />
Aside: regarding directory paths. All Joomla pages are generated by the index.php file in the top directory. All urls of all file references have to be relative to that one program. In other words, no matter where our files live, we can only reference them relative to the top url. In Joomla terms, this is defined as the $mosConfig_live_site variable. We now have to decide where our template files will live. Generally, they're under the top_level_directory/templates/your_template_name directory. We need to decide what we'll call our template. andreas01 will do. So...
c) We can now link to the stylesheets. The template comes with both screen and print stylesheets, so we can reference them as:
<link xhref="<?php echo $mosConfig_live_site;?>/templates/andreas01/andreas01.css" rel="stylesheet" type="text/css" media="screen"/>
<link xhref="<?php echo $mosConfig_live_site;?>/templates/andreas01/print.css" rel="stylesheet" type="text/css" media="print"/>
Hopefully staring at this will show the relationship between the $mosConfig_live_site variable and where our files live.
Now we're through with the head element, on to the body.
5) In the body we really start the slash-and-burn editing.
a) The image tag of the header photo has to be reworked with the mosConfig_live_site path as:
<img id="frontphoto" xsrc="<?php echo $mosConfig_live_site;?>/templates/andreas01/front.jpg" width="760" height="175" alt="" />
b) Next, we delete everything in the <div id="avmenu"> section and replace it with:
<?php mosLoadModules ( 'left', -2 ); ?>
The 'left' is clearly the module position. The second parameter is how to display the modules in this position. A good article on this is:
The condensed description of the 2nd parameter is:
0 = each module in a table
1 = each module in a table and wraps the whole thing in a horizontal table
-1 = raw output of the module without the module title
-2 = raw output of the module with the module's title
-3 = raw output of the module with title and with some padding divs .
We'll stick with -2
c) Do the same mayhem with the 'extras' div that'll be our right position:
<?php mosLoadModules ( 'right', -2 ); ?>
d) The main content section becomes:
<?php mosMainBody(); ?>
Why not another LoadModules? Remember that Joomla has one main content section with modules around it? This is the main content section.
e) and finally the footer:
<?php mosLoadModules ( 'footer', -2 ); ?>
Design by <a xhref="http://andreasviklund.com">Andreas Viklund</a>.
6) One tweek to the css. We can't add php to the css file to get the $mosConfigLifeSite. Why do we need this? The we have to have the correct path to the background image in the css file: the bg.gif image. So, I move one of the lines from the css file to the end of the head element as:
background: #f4f4f4 url(<?php echo $mosConfig_live_site;?>/templates/andreas01/bg.gif) top center repeat-y;
7) Remember the screenshot I took? I now scale it to be about 200x150 and save it in our build directory as template_thumbnail.png. I used the gimp for this.
8) Now comes our shipping manifest: the templateDetails.xml file. This is an XML file that serves as a packing list. It contains a list of all the other files the templates uses and the copyright info. It'll look like:
<?xml version="1.0" encoding="iso-8859-1"?>
<mosinstall type="template" version="1.0.0">
<author>Andres Viklund & Brent Laminack</author>
<description>This is a demo of taking a popular template from oswd.org and turning it into a Joomla! template</description>
9) Tar and zip it.
Joomla templates are distributed as gzipped tar files. "tar zcvf zipfile directory" does the trick, as:
I go up one directory level and do:
tar zcvf andreas01.tgz andreas01
Log into the administrator side of your joomla site, and go to 'installers->templates-site'
hit the 'browse' button and select the andreas.tgz file we just created,
then the 'upload file & install'
11) Select as default
after the install, click the 'continue...' and you'll be taken to the template manager. (or go to site->template manager->site templates)
click the radio button next to 'andreas01' and the 'default' icon in the toolbar. Notice as you hover your mouse over the name of the template, you see a thumbnail picture. That's what the template_thumbnail.png file was for.
12) A menu tweek.
As the admin, go to modules->site modules and click on the 'main menu' module. toward the bottom, you'll see a pull-down for 'menu style'. We want 'flat list' to work properly with the template. This will make the menu items simple list items that will style properly. I then did the same for the 'othermenu'. I then balanced by moving some left modules to the right and unpublishing the polls.
13) Go to the public side of your site and enjoy
Excersises for the reader:
Replace the Anreas01 in the header with something more appropriate
Replace the Haiku in the header with a module such as a newsflash module
Andreas01 is fixed width. I prefer fluid layouts. Make the center column fluid
Summary: here's the original template:
Here's the joomla site using it:
Here's the Joomla template for you to download and enjoy: