Distributing Joomla! templates
From Joomla! Documentation
Revision as of 18:59, 29 January 2011 by Mvangeest
- 1 How to choose a suitable license
- 2 How does template installation work?
- 3 File structure for packaging
- 4 Creating a thumbnail preview image
- 5 Packaging the template for installation
How to choose a suitable license
If you want to distribute your extension, you will need to choose a license carefully. Read Extensions and GPL for more information.
If you want to publish your extension on the Joomla Extensions Directory, you will need to make sure your license is compatible. Make sure you've read the JED Entries License Checklist before choosing a license.
How does template installation work?
Install via Admin Panel (packed template file)
</translate> <translate> Log into the back-end of your site (www.your-site.com/administrator/)</translate>
<translate> Click on: Extensions -> Extension Manager</translate>
<translate> You see the page "Extension Manager"</translate>
<translate> From here you can install your Templates, Plugins, Modules, Components and Languages. You have three options:</translate>
Install from Web - (select an extension listed on the Joomla! Extension Directory)</translate>
Upload Package File - (select a package from your PC, upload and install it)</translate>
Install from Directory - (enter the path where the package is located on your webserver)</translate>
Install from URL - (enter the URL to the package)</translate> <translate> Option 4 does everything for you, your environment needs to be properly configured to allow this. Option 2 requires you to download the extension to your PC. Option 3 requires you to unzip and move the folders/files to your webserver. All options require the webserver to have write access to the webspace.</translate>
<translate> Here, we choose the second method: Upload Package File</translate>
<translate> Select the package from your PC and click the button "Upload File & Install"</translate>
<translate> If the package contains no errors you are done and get a success message like the one below.</translate>
</translate> <translate> Go from tab 'Install' to tab 'Manage', set the 'Type' filter to 'Template'. The installed template should appear in the list. If it does, the template is properly installed. Now you can assign one of styles to a menu item or set the style as default. For administrator templates make sure you have two windows of the template manager. Activate the new template in one of them and reset it in the other one if something went wrong.</translate>
Install via FTP (unpacked template file)
</translate> <translate> Templates can also be installed via FTP without packaging them. Simply select the template folder on your PC and upload it to your server, using your favourite FTP software. Be sure you upload the template folder to the directory: /path_to_joomla/templates/ - where /path_to_joomla/ is the location of your Joomla! installation on the server. This method is mostly used when you have created a template yourself, and do not want to have to package it to install the template, or if you want to upload more than one template at once. You must then go into extension manager and click on Discover in the sub menu. Click on "Discover" in the toolbar if your template doesn't immediately appear. A list of uninstalled items in the FTP should then appear. Click the checkbox to the left of your template and click on the button 'Install'.</translate>
<translate> Note: Do not try to use FTP to install Components, Modules and Plugins if you are a beginner/novice. These items need database entries which have to be inserted manually if you bypass the package installer.</translate>
File structure for packaging
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
<translate> A thumbnail preview image should be 206 pixels in width and 150 pixels high. Recommended file format is png.</translate>
<translate> 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 pixels. </translate>
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 -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:
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:
cd myTemplate zip -r myTemplate.zip *