There are a lot of great Joomla templates on the web. But there are even more plain old HTML website templates. In this tutorial, I show you step by step how to convert a template from oswd.org into a Joomla template.

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:
ls -l
total 52
-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:
<?php
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[1] .'"?' .'>';
?>

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:
<div id="avmenu">
<?php mosLoadModules ( 'left', -2 ); ?>
</div> 
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:
http://www.howtojoomla.net/content/view/11/2/
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:
<div id="extras">
<?php mosLoadModules ( 'right', -2 ); ?>
</div> 
d) The main content section becomes:
<div id="content">
<?php mosMainBody(); ?>
</div>
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:
<div id="footer">
<?php mosLoadModules ( 'footer', -2 ); ?>
Design by <a xhref="http://andreasviklund.com">Andreas Viklund</a>.
</div>

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:
<style>
body {
background: #f4f4f4 url(<?php echo $mosConfig_live_site;?>/templates/andreas01/bg.gif) top center repeat-y;
}
</style>

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">
<name>Andreas01</name>
<creationDate>08/09/2007</creationDate>
<author>Andres Viklund & Brent Laminack</author>
<copyright>GNU/GPL</copyright>
<authorEmail>This email address is being protected from spambots. You need JavaScript enabled to view it.</authorEmail>
<authorUrl>http://3by400.com</authorUrl>
<version>1.0</version>
<description>This is a demo of taking a popular template from oswd.org and turning it into a Joomla! template</description>
<files>
<filename>index.php</filename>
<filename>template_thumbnail.png</filename>
<filename>andreas01.css</filename>
<filename>print.css</filename>
<filename>bg.gif</filename>
<filename>front.jpg</filename>
</files>
</mosinstall>

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
andreas01/
andreas01/andreas01.css
andreas01/bg.gif
andreas01/front.jpg
andreas01/index2.html
andreas01/print.css
andreas01/test.jpg
andreas01/index.php
andreas01/templateDetails.xml
andreas01/template_thumbnail.png

10) Install
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: