Welcome back!Top of Mind from 3by400
Joomla 1.5 Template Tutorial
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 1.5 template.
How to convert an oswd.org template into a Joomla! 1.5 template.
0) Understand how Joomla places content.
In Joomla 1.5x, 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: RedTie
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 RedTie.zip
-rw-r--r-- 1 brent brent 17458 2009-01-26 08:55 RedTie.zip
$ unzip RedTie.zip
Archive: RedTie.zip
creating: RedTie/
creating: RedTie/images/
inflating: RedTie/images/bg_menu.gif
inflating: RedTie/images/bg_submenu.gif
inflating: RedTie/images/style.css
inflating: RedTie/images/tie_logo.gif
inflating: RedTie/index.html
$ cd RedTie/
$ ls -l *
-rw-r--r-- 1 brent brent 4699 2007-01-21 17:39 index.html
images:
total 28
-rw-r--r-- 1 brent brent 157 2007-01-21 16:16 bg_menu.gif
-rw-r--r-- 1 brent brent 70 2007-01-21 16:17 bg_submenu.gif
-rw-r--r-- 1 brent brent 2205 2007-01-21 17:36 style.css
-rw-r--r-- 1 brent brent 14443 2007-01-21 16:35 tie_logo.gif
4) Grock the layout
I open the index.html file in Firefox and see the layout. I open up firebug and find that the top of the page is two divs: "logo" and "topheader", The thing that appears to be a main menu is a div called "menu", the area under it is a div called "submenu", the main area is a div called 'contenttext', the left column is called "leftpanel' and the bottom of the page is called "footer".
Looks to me like the 'contenttext' will be our main content area and we'll have module positions called topheader, menu, submenu, leftpanel and footer. The topheader has two areas: the company info and the menu. This might become two module positions, we'll decide when we tear into it.
5) Start editing the files: the head element
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 language as:
<?php
// no direct access
defined( '_JEXEC' ) or die ( '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; ?>" >
b) Next, replace the title element and meta elements with the php code to generate them:<jdoc:include type="head" />
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. Joomla comes with a 'system.css' and 'general.css' stylesheet linked as:<link rel="stylesheet" href="/<?php echo $this->baseurl ?>/templates/system/css/system.css" type="text/css" />
<link rel="stylesheet" href="/<?php echo $this->baseurl ?>/templates/system/css/general.css" type="text/css" />where $this->baseurl is the url of the root of the website. For our local stylesheet, it appears to be in images/style.css. It really shouldn't be in 'images', now should it? Generally a Joomla template's stylesheet lives in 'css/template_css.css' so first we move the file:
$ mv images/style.css css/template_css.css
then link it into the index.php file by replacing the reference to style.css with:<link rel="stylesheet" href="/<?php echo $this->baseurl ?>/templates/redtie/css/template.css" type="text/css" />
Here I've made an executive decision: what we'll call our template. Each Joomla template lives in its own directory. I've decided the directory name will be 'redtie'.
Now we're through with the head element, on to the body.
6) The slash-and-burn editing of the body element
a) The name of the site should be in the reversed out (white) lettering on the tie, so we change the 'RedTie' to be the name of the site:
<div style="margin-top:70px" class="whitetitle"><?php echo $mainframe->getCfg('sitename');?></div>
b) I think I will divide the 'topheader' into two module positions. I'll replace the company name with:<jdoc:include type="module" name="topleft" />
creating a module position called 'topleft' and replace the links with:<jdoc:include type="module" name="topmenu" />
Yes, I could've called it 'toplinks', but 'topmenu' is more joomla-ish
c) speaking of menus, they come next. I replace the links in the 'menu' div with:
<jdoc:include type="module" name="mainmenu" />
and the 'submenu' div with:<jdoc:include type="module" name="submenu" />
d) Now for the main content. I replace everything in the "contenttext" div with:
<jdoc: include type="component" />
taking note that the header has a class of "titletext" with padding: 10px and the body has style "bodytext" with "padding: 12px". I may need to tweek the stylesheet later.
e) the left column:
I replace everything in the div with class 'graypanel' with: <jdoc:include type="module" name="left" />
I also see in there there are classes of 'smalltitle', 'smallredtext', 'bodytext' and 'smallgraytext'. We might have to redefine these in the stylesheet later to correspond with the Joomla classes.
f) finally replace everything in the footer div with: <jdoc:include type="module" name="footer" />
7) Adjust CSS Image Paths
now that the css and images are in seaprate directories, I have to change the paths in css/template_css.css as:
background-image:url(../images/tie_logo.gif)
background-image:url(../images/bg_menu.gif)
background-image:url(../images/bg_submenu.gif)
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>
8) Create the Thumbnail
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. It turns out to be 200x183, but close enough.
9) The XML shipping manifest
All the files in the template are listed in a file called 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. I copied the one from the default ruhk_milkyway and modified it thus:
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE install PUBLIC "-//Joomla! 1.5//DTD template 1.0//EN" "http://www.joomla.org/xml/dtd/1.5/template-install.dtd">
<install version="1.5" type="template">
<name>redtie</name>
<creationDate>1/26/2009</creationDate>
<author>Brent Laminack</author>
<authorEmail>This email address is being protected from spambots. You need JavaScript enabled to view it.</authorEmail>
<authorUrl>http://3by400.com</authorUrl>
<copyright>2009 all rights reserved</copyright>
<license>GNU/GPL</license>
<version>1.0.0</version>
<description>Based on RedTie template from oswd.com</description>
<files>
<filename>index.php</filename>
<filename>templateDetails.xml</filename>
<filename>template_thumbnail.png</filename>
<filename>images/bg_menu.gif</filename>
<filename>images/tie_logo.gif</filename>
<filename>css/template_css.css</filename>
</files>
<positions>
<position>topleft</position>
<position>topmenu</position>
<position>mainmenu</position>
<position>submenu</position>
<position>left</position>
<position>footer</position>
</positions>
<params>
</params>
</install>The important parts are to get all the files listed in the files section, and all the module positions we defined in the positions section.
10) Tar and zip it.
Joomla templates are distributed as gzipped tar files. "tar zcvf zipfile directory" does the trick, I go up one directory level, rename the directory to all lower case and tar-gzip it as:
$ cd ..
$ mv RedTie redtie
$ tar zcvf redtie.tar.gz redtie
redtie/
redtie/css/
redtie/css/template_css.css
redtie/template_thumbnail.png
redtie/index.php
redtie/templateDetails.xml
redtie/images/
redtie/images/tie_logo.gif
redtie/images/bg_submenu.gif
redtie/images/bg_menu.gif
$ ls -l redtie.tar.gz
-rw-r--r-- 1 brent brent 49206 2009-01-26 11:08 redtie.tar.gz
11) 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'
12) 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.
13) A few CSS Tweeks
The original menus weren't list items, so I threw in:
/* menu */
ul.menu {list-style-type: none;
}
ul.menu li {display: inline;
padding-right: 10px;
}
at the bottom of the css file to make them show up right. I also added the joomla class componentheading as an alias for titletext, contentheading as an alias for smalltitle and small, createdate, and modifydate as aliases for smallgraytext.
14) Go to the public side of your site and enjoy
Exercises for the reader:
restyle the left position to look more like the original
Summary: here's the original design
Here's the Joomla 1.5 site using it:
Here's the template for you to download and enjoy:
