Joomla! Documentation™

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?

It is important to understand how template installation works.

Install via Admin Panel (packed template file)

Log into the back-end of your site (www.your-site.com/administrator/)

Click on: Extensions -> Extension Manager

You see the page "Extension Manager"

From here you can install your Templates, Plugins, Modules, Components and Languages. You have different options:

1. Install from Web - to select an extension listed on the Joomla! Extension Directory
2. Upload Package File - to select a package from your PC, upload and install it
3. Install from Folder - to enter the path where the package is located on your webserver
4. Install from URL - to enter the URL to the package

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.

Here, we choose the second method: Upload Package File

Drag and drop file to the upload area to upload. Alternatively you can also click the button "Or browse the file" to select the package from your PC.

If the package contains no errors you are done and get a success message like the one below.

Verify installation

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.

Install via FTP (unpacked template file)

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'.

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.

File structure for packaging

This Article Needs Your Help

<translate> The most basic files, such as index.php, component.php, templateDetails.xml, template_thumbnail.png, favicon.ico, params.ini should be placed in your /templates folder. The usual practice is to place images, CSS files, JavaScript files etc. in separate folders. The Joomla override files must be placed in folders in the /templates/<template_name>/html folder. </translate>

<translate> When making the template folder, your language files should be copied to your /templates folder. The ones for the Frontend site should be placed directly in the template folder. If you have language files for the Backend, these should be placed in a folder, named, for instance, /administrator. All the language files will be copied automatically to the right folders if listed correctly in the templateDetails.xml. </translate>

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

Warning!

<translate>

Note on the Component Dependent Modules

</translate> <translate> Sometimes modules (or plugins and so on) use a component's models and helpers and such. On these occasions it would be nice to be able to package your module in a way that it gets uninstalled when the component itself gets uninstalled. This is called dependency management that has been desired in Joomla but hasn't been done yet. It is suggested that you follow the standards and use a package as described below. </translate>

<translate>

What is a Package?

</translate> <translate> A package is a extension that is used to install multiple extensions at one time. Use a package if you have, for example, a component and a module that are dependent upon each other. Combining them in a package will allow the user to install and uninstall both extensions in a single operation. Package extensions can be used with Joomla and higher. </translate>

<translate>

How Do I Create a Package?

</translate> <translate> A package extension is created by zipping all .zip files of the extensions together with a .xml manifest file. For example, if you have a package composed of: </translate>

<translate>

• component helloworld
• module helloworld
• library helloworld
• system plugin helloworld
• template helloworld

The package should have the following tree in your zip file: </translate>

 -- pkg_helloworld.xml
 -- packages <dir>
     |-- com_helloworld.zip
     |-- mod_helloworld.zip
     |-- lib_helloworld.zip
     |-- plg_sys_helloworld.zip
     |-- tpl_helloworld.zip
 -- pkg_script.php

<translate> The pkg_helloworld.xml could have the following contents: </translate>

 <?xml version="1.0" encoding="UTF-8" ?>
 <extension type="package" version="1.6" method="upgrade">
 <name>Hello World Package</name>
 <author>Hello World Package Team</author>
 <creationDate>May 2012</creationDate>
 <packagename>helloworld</packagename>
 <version>1.0.0</version>
 <url>http://www.yoururl.com/</url>
 <packager>Hello World Package Team</packager>
 <packagerurl>http://www.yoururl.com/</packagerurl>
 <description>Example package to combine multiple extensions</description>
 <update>http://www.updateurl.com/update</update>
 <scriptfile>pkg_script.php</scriptfile>
 <files folder="packages">
   <file type="component" id="com_helloworld" >com_helloworld.zip</file>
   <file type="module" id="helloworld" client="site">mod_helloworld.zip</file>
   <file type="library" id="helloworld">lib_helloworld.zip</file>
   <file type="plugin" id="helloworld" group="system">plg_sys_helloworld.zip</file>
   <file type="template" id="helloworld" client="site">tpl_helloworld.zip</file>
 </files>
 </extension>

<translate> When you zip this and install it, you will see that all extensions will be installed. The package will be visible in the extension list so that a user might uninstall all extensions contained in the package. </translate>

<translate> Remember to use the package uninstaller instead of individual subpackage uninstallers to avoid orphan extension entries in the extension manager. </translate>

<translate>

Id = <file id="not_arbitrary">

The id element in <file ..> tag is not arbitrary! The id= should be set to the value of the element column in the #__extensions table. If they are not set correctly, upon uninstallation of the package, the child file will not be found and uninstalled. </translate>

<translate>

Plugin "group" attribute

The group attribute is required for the package installer to locate the plugin for uninstall. Group refers to the <folder> name specified in the plugin manifest file.</translate>

<translate>

Manifest Filename and Packagename

The naming of the manifest file and the ability to uninstall the package file itself are closely related. The manifest file must have a pkg_ prefix. The remainder of the manifest name (without the .xml extension) is to be used as <packagename>. Or, the other way around, a package you want to identify as blurpblurp_J3 gets that as its <packagename> and should be in a manifest file named pkg_blurpblurp_J3.xml. Failure to do so will make it impossible to uninstall the package itself.</translate>

<translate> An optional <pkg_script.php> which contains a class pkg_<packagename>InstallerScript with public function postflight can be used. (This works in Joomla! 3.6 and later).</translate>

<translate>

Extension Tag

</translate> <translate> As of Joomla! 3.4, you should include method="upgrade" in the <extension> tag if you want your package to succeed in updating itself on subsequent installations.</translate>

<translate> The version attribute of the <extension> tag should be set to the minimum supported version of Joomla for this package. For example, if your package only supports Joomla! 3.2 and above, set this to 3.2.</translate>

<translate> Note: This version attribute is purely optional. It has no influence on Joomla's installation routine. As of Joomla 4, the version attribute has therefore been removed from all core extensions. See pull request 29960 on github.com</translate> <translate>

Extension Uninstall Dependency

</translate> <translate> As of Joomla! 3.7.0, a package extension can declare that its child elements cannot be uninstalled independently with a <blockChildUninstall>true</blockChildUninstall> element in the package manifest. If your package needs all its extensions to operate effectively, set this to true or 1. </translate>