Tutorial:Creating a basic Joomla! template - Jooml... http://docs.joomla.org/Tutorial:Creating_a_basic_J...

Tutorial:Creating a basic Joomla!

template
From Joomla! Documentation

Contents
1 Introduction
2 Setting up a directory structure
3 Creating a basic templateDetails.xml file
4 Creating a basic index.php file
5 Packaging the template for installation
5.1 Note to Mac OS X users
6 Conclusion

Introduction
The purpose of this tutorial is to serve as an introduction to creating Joomla!
templates. It will cover the essential files and code needed to create a basic
template. The code is presented so it can be cut and pasted with very little
modification needed.

Setting up a directory structure

To make the most basic template, create a new folder in the "templates" folder.
Name this folder after your template i.e. "mynewtemplate".

Using a text editor (or dedicated editor such as Adobe Dreamweaver) create
the files "index.php" and "templateDetails.xml"

To keep things organized, make 2 new folders called "images" and "css".
Inside the "css" folder create a file called "style.css".

Although it is fine to place all your CSS code directly in your "index.php" file to
start, many web developers prefer to place their CSS code in a separate file that
can be linked from multiple pages using the "link" tag.

This is the most basic practical setup.

1 of 6 Wednesday 01 September 2010 10:07 AM

Tutorial:Creating a basic Joomla! template - Jooml... http://docs.joomla.org/Tutorial:Creating_a_basic_J...

Outline of folder and file structure:

mynewtemplate/
css/
style.css
images/
index.php
component.php
templateDetails.xml

This article is a small, well-defined item that

could be completed by someone with a
reasonable knowledge of the subject matter and
a modest time commitment.

If you would like to try writing this article you're

welcome to do so. The subject may be self-evident,
but if not then further details should be available on
the discussion page. Please add {{inuse}} at the
top of this page while editing. For other small,
well-defined tasks, please look in the Cookie jar.

Thank you.

Creating a basic templateDetails.xml file

The templateDetails.xml file is essential. Without it, your template won't be seen by
Joomla!. The file holds key "metadata" about the template.

Lets look at an example:

2 of 6 Wednesday 01 September 2010 10:07 AM

Tutorial:Creating a basic Joomla! template - Jooml... http://docs.joomla.org/Tutorial:Creating_a_basic_J...

<?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-inst
<install version="1.5" type="template">
<name>mynewtemplate</name>
<creationDate>2008-05-01</creationDate>
<author>John Doe</author>
<authorEmail>john@example.com</authorEmail>
<authorUrl>http://www.example.com</authorUrl>
<copyright>John Doe 2008</copyright>
<license>GNU/GPL</license>
<version>1.0.2</version>
<description>My New Template</description>
<files>
<filename>index.php</filename>
<filename>component.php</filename>
<filename>templateDetails.xml</filename>
<filename>template_thumbnail.png</filename>
<filename>images/background.png</filename>
<filename>css/style.css</filename>
</files>
<positions>
<position>breadcrumb</position>
<position>left</position>
<position>right</position>
<position>top</position>
<position>user1</position>
<position>user2</position>
<position>user3</position>
<position>user4</position>
<position>footer</position>
</positions>
</install>

So, as you can see, we have a set of information between markup tags ( the
<thing> ). Your best approach is to cut and paste this into your
"templateDetails.xml" file and change the relevant bits (such as <name>
<author> ).

The <files> part should contain all the files that you use - you possibly don't
know what they are called yet - don't worry update it later.

Leave the positions as they are - these are a common set so you will be able to
switch easily from the standard templates.

Creating a basic index.php file

The index.php file becomes the core of every page that Joomla! delivers.
Essentially, you make a page (like any html page) but place PHP code where the
content of your site should go. Here is the bare-bones code ready for you to cut
and paste.

Lets start at the top:

3 of 6 Wednesday 01 September 2010 10:07 AM

Tutorial:Creating a basic Joomla! template - Jooml... http://docs.joomla.org/Tutorial:Creating_a_basic_J...

<?php 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; ?>" >

The first line stops naughty people looking at your coding and getting up to bad
things. The second tells the browser (and webbots) what sort of page it is. The
third line says what language the site is in.

Now the header for real:

<head>
<jdoc:include type="head" />
<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"
<link rel="stylesheet" href="<?php echo $this->baseurl ?>/templates/<?php echo $this->template?>/css/style.css"
</head>

The first line gets Joomla to put the correct header information in. This includes
the page title, meta information as well as system JavaScript. The rest creates
links to two system style sheets and to your own style sheet (if it's named
style.css and is located in the css folder).

Now for the main body:

<body>
<jdoc:include type="modules" name="top" />
<jdoc:include type="component" />
<jdoc:include type="modules" name="bottom" />
</body>

Amazingly, this will suffice! Yes, its a very basic layout, but it will do the job.
Everything else will be done by Joomla!. Note: you will need to ensure your
menu is set to go into the "top" module position.

Finish it off - one last bit:

</html>

Full template source code:

4 of 6 Wednesday 01 September 2010 10:07 AM

Tutorial:Creating a basic Joomla! template - Jooml... http://docs.joomla.org/Tutorial:Creating_a_basic_J...

<?php 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; ?>" >
<head>
<jdoc:include type="head" />
<link rel="stylesheet" href="<?php echo $this->baseurl ?>/templates/mynewtemplate/css/style.css" type="text/css"
</head>
<body>
<jdoc:include type="modules" name="top" />
<jdoc:include type="component" />
<jdoc:include type="modules" name="bottom" />
</body>
</html>

Packaging the template for installation

A directory with several loose files is not a convenient package for distribution.
So the final step is to make a package. This is a compressed archive containing
the directory structure and all the files. The package can be in ZIP format (with
a .zip extension), in TAR-gzip format (with a .tar.gz extension), or in TAR-bz2
format (with a .tar.bz2 extension).

If your template is in a directory mytemplate/ then to make the package you can
connect to that directory and use commands like:

tar cvvzf ../mytemplate.tar.gz *

zip -a -r ..\mytemplate.zip *.*

Note to Mac OS X users

Note to template developers using Mac OS X systems: the Finder's "compress"

menu item produces a usable ZIP format package, but with one catch. It stores
the files in AppleDouble format, adding extra files with names beginning with
" ._". Thus it adds a file named " ._templateDetails.xml, which Joomla 1.5.x can
sometimes misinterpret. The symptom is an error message, "XML Parsing Error
at 1:1. Error 4: Empty document". The workaround is to compress from the
command line, and set a shell environment variable "COPYFILE_DISABLE" to
"true" before using "compress" or "tar". See the AppleDouble article for more
information.

To set an environment variable on a Mac, open a terminal window and type:

export COPYFILE_DISABLE=true

Then in the same terminal window, change directories into where your template

5 of 6 Wednesday 01 September 2010 10:07 AM

Tutorial:Creating a basic Joomla! template - Jooml... http://docs.joomla.org/Tutorial:Creating_a_basic_J...

files reside and issue the zip command. For instance, if your template files have
been built in a folder in your personal directory called myTemplate, then you
would do the following:

cd myTemplate
zip -r myTemplate.zip *

Conclusion
You should now have created a template that works. It won't look like much yet.
The best thing to do now is start experimenting with the layout.

Retrieved from "http://docs.joomla.org

/Tutorial:Creating_a_basic_Joomla%21_template"
Categories: Cookie jar | Templates | Tutorials

This page was last modified on 26 July 2010, at 10:46.

Content is available under Joomla! EDL.

6 of 6 Wednesday 01 September 2010 10:07 AM