Whether or not you’ll be working with an XML generator component, your HTML editor, or an XML editor, it’s good to understand what the templateDetails.xml file contains and what each part of it is meant to do. If there are any issues with your package, knowing what each part does will greatly ease troubleshooting and aid in fixing your installation. If any piece of your template is not added to this file in the appropriate tags, your package will produce errors upon installation.

Here’s our templateDetails.xml file as it stands as of Chapter 3:

<?xml version="1.0" encoding="iso-8859-1"?>
<mosinstall type="template" version="1.0.0">
    <name>my_nature_design</name>
    <creationDate>12/22/06</creationDate>
    <author>my name</author>
    <copyright>GNU/GPL</copyright>
    <authorEmail>[email protected]</authorEmail>
    <authorUrl>http://www.mysite.com</authorUrl>
    <version>2.2</version>
    <description>A simple and stylish template. Based on Rhuk's
                                   Solarflare II design</description>
    <files>
        <filename>index.php</filename>
        <filename>template_thumbnail.png</filename>
    </files>
    <images>
        <filename>images/advertisement.png</filename>
        <filename>images/arrow.png</filename>
            <filename>images/button_bg.png</filename>
        <filename>images/contenthead.png</filename>
        <filename>images/indent1.png</filename>
        <filename>images/indent2.png</filename>
        <filename>images/indent3.png</filename>
        <filename>images/indent4.png</filename>
        <filename>images/header_short.jpg</filename>
        <filename>images/menu_bg.png</filename>
        <filename>images/powered_by.png</filename>
        <filename>images/spacer.png</filename>
        <filename>images/subhead_bg.png</filename>
        <filename>images/title_back.png</filename>
    </images>
    <css>
        <filename>css/template_css.css</filename>
    </css>
</mosinstall>

Now, all we really changed was the name of the template so that we could differentiate it from the original Rhuk template in our Joomla! Administration Panel. The rest of the information in this XML file is still Rhuk’s. Let’s learn what each tag does.

<?xml version="1.0" encoding="iso-8859-1"?>

This is XML’s DOCTYPE, and you’re pretty much going to leave it alone. We’re pretty sure that our template is only going to be used primarily with computers using Western languages, so we’ll leave the encoding as iso-8859-1. If you’re hoping for a wide distribution of your template on machines using other languages, it might be better to set this to UTF-8.

<mosinstall type="template" version="1.0.0">

You’ll notice that everything else is tucked into this <mosinstall... tag. Don’t forget to add the closing </mosinstall> tag at the very end of your file!

The attributes type="template" and version="1.0.0" tell the installer that we are installing a template and also what version of Joomla! it’s optimally designed for. If you’re using a development version of Joomla! that’s greater than 1.0.0 (probably 1.0.8 or 1.0.12 as at the time of writing) you should enter those numbers into the version attribute. We’ll change the version number 1.0.8 for our templateDetails.xml file.

<name>my_nature_design</name>

As mentioned, we added our own template name in Chapter 3 when we set up our development area. This tag defines the name of your template. This name is also used to generate the directory within the template directory. As a result, you cannot use characters that the file system cannot handle, like spaces or special symbols. You’ll notice in Chapter 3 that the file directory that we manually created and copied was named with the same name as the one we entered into the <name> tag. This is required for the template to work properly.

<creationDate>12/22/06</creationDate>

We did update this initially as well. Obviously, you’ll enter the date when your template was created. While the double-digit month/day/year format is standard, there are no real requirements for this tag. You can use any date format you’d like such as a general “May 2007”, the more American “May 30, 2007”, or “2007-05-30”. Just pick something you know your template’s users are going to recognize as a date.

<author>my name</author>

Here you’ll add your name to the template, or perhaps a team, group, or corporate name if a group of you designed the template together.

<copyright>GNU/GPL</copyright>

You’ll place your copyright information in this tag. Rhuk released the solar_flare_ii template under the GNU/GPL license. If you’re not familiar with the GNU/GPL License you can learn more about it at http://www.gnu.org/copyleft/gpl.html. You may wish to do the same with your template. If you do this, it has to be freely distributed, available to all, and changeable by all with no permissions necessary so long as they acknowledge you.

If you’ve created a completely original design that you intend to sell commercially, or just want to be able to grant permission for any other possible use, you’ll need to place specific copyright information and the name of the person or organization that holds the copyright. Something like © 2007 My Name, All Rights Reserved, is generally recognized as legal with or without any formal copyright filing procedures (but you should look up how to best formally copyright your design material).

Our design is leveraged from the Rhuk design for educational purposes, although the GNU/GPL license is more than adequate. Its text is perhaps a bit “softwareish” and “tech-heavy” for our intended audience, so we’re going to redistribute the new nature template under the more general-public-friendly Creative Commons License. We’ll use the CC Labs DHTML License Chooser to assist us in selecting an appropriate license. It can be found at http://labs.creativecommons.org/dhtmllicense/:

Figure 5.3 Creative Commons DHTML license chooser

We’ll of course allow sharing of the template, and let others “remix” and derive new works from it (as we remixed Rhuk’s) with proper credit. We will, however, prevent it from being used commercially, and use the Require Share-Alike option. This means that no one can legally take the template package and offer it for sale or use it in such a way that it generates income for them without our permission. If they reuse or redesign the package in any other non-commercial way they’re free to do so, they’re simply required to give us and Rhuk due credit.

Our licensing agreement looks like the following:

my_nature_design by Tessa Blakeley Silver for Packt Publishing, remix inspired by: rhuk_solar_flare_ii, is licensed under a Creative CommonsAttribution-NonCommercial-ShareAlike 2.5 License.

The end result is a license that keeps the spirit of the GNU/GPL license but is much less vague. It tells the user upfront that it allows sharing which is important to us for educational purposes, gives continued credit to the original Rhuk author, prevents commercial distribution without permission, and by requiring share-alike encourages a continued friendly Joomla!-esque atmosphere for open-source collaboration. It also states the version number of the license making it very easy for anyone to look it up and read it in detail.

Additionally, a Licensing Primer for Developers and Designers can be found on the Joomla! forums at http://forum.joomla.org/index.php/topic,22653.0.html.

<authorEmail>[email protected]</authorEmail>
<authorUrl>http://www.mysite.com</authorUrl>

Here, we’ll place a good contact email address for people who might have questions about the template. This is especially important if you’re going to use a straight-up copyright. Make sure people who are seeking permission to use your design can do so, there’s probably cash at stake! While publishing via a Copyright, GPL, or CC license, it’s a good idea to ensure that the email address is best suited for taking technical questions about your template. You are not responsible to be available for “tech-support”, especially under the GNU/GPL or CC license, as everyone’s system and use of Joomla! is unique, so who knows what would go wrong from user to user. However, it would be nice to offer any input or ideas that might help someone else troubleshoot problems that they are having with the template.

Last, in the authorURL tags, place the website address with a page, you feel best encompasses what you want to portray to your target template audience. This is essentially an opportunity to get your URL out there and toot your horn so go on, take advantage of it.

<version>2.2</version>

You may find that your template goes through some revisions before it’s complete, especially if you happen to be working on a team. Perhaps, this is an older template that you’ve just upgraded and overhauled to run a little more smoothly. If you can apply versioning to this template, go ahead and do so. This is the first version of this look for the template so we’ll take it back to version 1.0:

<files>
    <filename>index.php</filename>
    <filename>template_thumbnail.png</filename>
</files>

OK, everything and anything that is not a CSS, or an image that is used in the actual template goes in here. This essentially means your index.php file and the thumbnail preview we made at the beginning of this chapter. You must also place any references to JavaScripts you write or JavaScript libraries used by your template. Path information for your files is relative to the root of your template, hence, your index.php file is just listed. However, if you use JavaScripts that are located inside a folder called js you must indicate that path in the filename <filename>js/moofx.js</filename>.

Be careful that each additional file is listed inside its own <filename>...</filename> tags. We didn’t add any JavaScripts so we’re good to move on.

<images>
    <filename>images/advertisement.png</filename>
    <filename>images/arrow.png</filename>
    <filename>images/button_bg.png</filename>
    <filename>images/contenthead.png</filename>
    <filename>images/indent1.png</filename>
    <filename>images/indent2.png</filename>
    <filename>images/indent3.png</filename>
    <filename>images/indent4.png</filename>
    <filename>images/header_short.jpg</filename>
    <filename>images/menu_bg.png</filename>
    <filename>images/powered_by.png</filename>
    <filename>images/spacer.png</filename>
    <filename>images/subhead_bg.png</filename>
    <filename>images/title_back.png</filename>
</images>

All image files that your template uses will be listed within these tags. Again, each image file must be enclosed with <filename>... </filename> tags. As mentioned, path information for the files is relative to the root of your template. Chances are that you’ve tucked all your template images inside an images folder. Hence, you see the image/filename.png path detailed above. If you didn’t use a directory called images or you’ve broken your images into sub-directories within your main image directory, it’s OK. You must still detail each image with its full path: <filename>images/top-level/filename.png</filename>. We redesigned and overwrote the original Rhuk images for our template, so we can pretty much leave the image calls alone. However, we did rename our main header image, so we’ll replace header_short.jpg with our file name, my_nature_header.jpg.

<css>
    <filename>css/template_css.css</filename>
</css>

Last, you’ll add your style sheet (or style sheets if you are using more than one). Again, the filename is surrounded with <filename>...</filename> tags, and its path must be relative to your template’s root.

Here’s what our final template version looks like:

<?xml version="1.0" encoding="iso-8859-1"?>
<mosinstall type="template" version="1.0.8">
    <name>my_nature_design</name>
    <creationDate>12/22/06</creationDate>
    <author>Tessa Blakeley Silver</author>
    <copyright>my_nature_design by Tessa Blakeley Silver for Packt
                  Publishing, remix inspired by: rhuk_solar_flare_ii,
                  is licensed under a Creative Commons
                  Attribution-NonCommercial-ShareAlike 2.5 License.
                                                       </copyright>
    <authorEmail>[email protected]</authorEmail>
    <authorUrl>http://www.packtpub.com</authorUrl>
    <version>1.0</version>
    <description>A simple and stylish template. Based on Rhuk's
                         Solarflare II design for the
                         Joomla! Template! Design! book</description>
    <files>
        <filename>index.php</filename>
        <filename>template_thumbnail.png</filename>
    </files>
    <images>
        <filename>images/advertisement.png</filename>
        <filename>images/arrow.png</filename>
        <filename>images/button_bg.png</filename>
        <filename>images/contenthead.png</filename>
        <filename>images/indent1.png</filename>
        <filename>images/indent2.png</filename>
        <filename>images/indent3.png</filename>
        <filename>images/indent4.png</filename>
        <filename>images/my_nature_header.jpg</filename>
        <filename>images/menu_bg.png</filename>
        <filename>images/powered_by.png</filename>
        <filename>images/spacer.png</filename>
        <filename>images/subhead_bg.png</filename>
        <filename>images/title_back.png</filename>
    </images>
    <css>
        <filename>css/template_css.css</filename>
    </css>
</mosinstall>