How does template installation work?

File structure for packaging

The most basic files, such as index.php, component.php, templateDetails.xml, template_thumbnail.png, favicon.ico, params.ini should be placed directly in your template folder. The most common is to place images, CSS files, JavaScript files etc in separate folders. Joomla override files must be placed in folders in the folder "html".

When making the template folder, your language files should be copied to your template folder. The ones for the front end site should be placed directly in the template folder. If you have language files for the back end, these should be placed in a folder, named for instance "admin". All the language files will be copied automatically to the right folders if stated correctly in the templateDetails.xml.

Creating a thumbnail preview image

A thumbnail preview image should be 206 pixels in width and 150 pixels high. Recommended file format is png.

You can take a screen shot of your site/template using the key "Prnt Scrn" on Windows or the corresponding on Mac/Linux. (There are also many programs specialized in screen shots that can be used.) After making the screen shot, paste or open the picture in an image editor such as PhotoShop or Gimp and resize and crop your image to 206x150 pixles.

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 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: