HUBzero Help - Documentation: Packaging

Packaging

Preparation

File Structure

The most basic files, such as index.php, error.php, templateDetails.xml, template_thumbnail.png, favicon.ico 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".

/{TemplateName}
  /css
    ... CSS files ...
  /html
    ... Overrides ...
  /images
    ... Image files ...
  /js
    ... JavaScript files ...
  error.php
  index.php
  templateDetails.xml
  template_thumbnail.png
  favicon.ico

Thumbnail Preview Image

A thumbnail preview image named template_thumbnail should be included in your template. Image size is 206 pixels in width and 150 pixels high. Recommended file format is PNG.

Packaging

Packaging a template for distribution is easy. Just "zip" up the module directory into a compressed archive file. When the ZIP file is installed, the language file is copied to the appropriate language sub-directory of /language/ and is loaded each time the template is loaded. All of the other files are copied to the /templates/{TemplateName} subfolder of the HUB installation.

Note to Mac OS X users

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:

cd myTemplate
zip -r myTemplate.zip *

Manifest

This XML file just lines out basic information about the template such as the owner, version, etc. for identification by the installer and then provides optional parameters which may be set in the Template Manager and accessed from within the module's logic to fine tune its behavior. Additionally, this file tells the installer which files should be copied and installed.

A typical template manifest:

<?xml version="1.0" encoding="utf-8"?>
<extension 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>
</extension>

Let's go through some of the most important tags:

EXTENSION: The install tag has several key attributes. The type must be "template".
NAME: You can name the templates in any way you wish.
FILES: The files tag includes all of the files that will will be installed with the template.
POSITIONS: The module positions used in the template.

The one noticeable difference between this template manifest and the typical manifest of a module or component is the lack of config. While templates may have their own params for further configuration via the administrative back-end, they aren't as commonly found as in other extension manifests. Most HUBzero templates do not include them.

Download

Only this page

This page and all sub-pages