112 - Write a document describing how to package a Joomla! 1.5 template for dist

[littlegeniuz]

Hello, my name is Thomas Gummerer. I am 17 years old and going to the highscool.
I'm intrested in Open Source Software, because I don't want to pay for good software. The second reason is, that I can look on the Code and modify it, without conflicting laws.
I am using Joomla! on my own website since one year. Now its time to give something back to the community, and what chance could be better then a contest sponsored by Google.

So my Plan is to write a document which is easy understandable and readable.
The second important point for me is, that it is platform independent(both Linux and Windows users should be able to use it).

At least I have two questions:
How should this document look like and in which format should it be?

Description:

One line summary
Write a document describing how to package a Joomla! 1.5 template for
distribution.

Description
The document should:-

    * describe how the installation process works.
          o briefly describe what steps the template installer performs
when installing a template.
    * describe the file structure required.
          o describe the basic files required and where they should be placed.
          o describe a recommended structure for including CSS, JavaScript
and images.
          o describe the structure required to support template overrides.
    * describe how to create the templateDetails.xml file.
          o include a basic templateDetails.xml that can be copy/pasted.
          o describe the usage of each of the nodes.
          o it is not necessary to describe in detail the node
as this is documented elsewhere.
    * describe how to create the thumbnail preview image.
          o recommended size and format.
          o briefly describe how to take a screenshot and scale the image
using The Gimp.
    * describe how to create the archive files.
          o on your preferred platform, give a step-by-step account of how
to create an archive file containing the template.
          o for example, you might describe how to use WinZip on Microsoft
Windows, or Eclipse on Linux.
          o you only need to describe one platform/tool/archive file
combination.
          o use annotated screenshots of the process where appropriate.
          o remember that Joomla! natively supports archive files in .zip,
.tar.gz and .tar.bz2 formats.

Google Task
[me=AmyStephen]Changed subject slightly for sorting all threads to match against Google resource  [/me]

[AmyStephen]

Hi Thomas!

It is so cool to see people who are already members of our community participate in this contest. Thanks for your willingness to contribute to our community. All we have is what members have contributed - and now you are part of that grand tradition!

I'm happy to pay for good software - I just want to be able to do what I need to do with it after purchasing it. I agree with you that being able to look at code and learn from it and modify it and share it with others without breaking the law is very good! Joomla! is evidence of how valuable it can be to allow others to improve someone else's work. It's cool you get these concepts already. That's how the world changes and things improve - newer generations bring it in.

Regarding your questions, the main point is that the document should be easy to understand. Simple. Step by step instructions. Images are very helpful. Keep your language natural, not cryptic. Define technical terms. We prefer receiving this work in Open Office Writer .odt file format.

We are here to help you be successful with your project. Feel free to ask questions when you have them. If you have a draft of your work that you want the community to review, share that and call for a review.

Good luck with the contest!
Amy

[AmyStephen]

GHOP Contestants Please Read: Task Process Start to Finish for important updates on the contest.

[littlegeniuz]

Hi,
I have an other question about the document: How does template override work?

tom

[AmyStephen]

If you look at the BEEZ template, you will see an html sub-folder.

That is an example of the template overrides in action.

If you click into the folder, you will find the names of components and modules. For example: com_content or mod_latestnews.

As you drill down into the folders, you eventually find the php files. These are "views" or files used to process the output from the component or module.

When existing, Joomla! uses these view files as a replacement to the core view files.

Code: Select all

templates
---- beez
---- ---- html
---- ---- ---- com_content
---- ---- ---- ---- article
---- ---- ---- ---- ---- default.php
---- ---- ---- ---- ---- form.php

Hope that helps!

Do you have a draft that we might be able to review? Is there anything we can do? Don't forget to ask for help, if needed.

Thanks for your contributions to the Joomla! community,
Amy

[littlegeniuz]

Thanx for the help.

Today I finished the first Draft, but there are still some screenshots missing.

I would be happy if someone could give me some feedback, so I could improve the document!

tom

[AmyStephen]

This is EXCELLENT work! 

Typos
posible --> possible
Recomendet --> recommended (several places, looks like a mass change lol)

Be gender neutral.

Put this file in every folder. So no one can see the contents of the folders, even if he knows the path to it.

Try this approach:

Put this file in every folder to prevent browsing of folder contents.

Template overrides

This is going to be an area of confusion since it is a new concept for our community.

For overrides create a subfolder with the name of the component or the module. In this subfolder you can place a php file, identically with the php file of the component or the module you want to override. This new php file contains the new function of the component or the module.

This is a suggestion. Interested in the viewpoint of others familiar with template overrides, as well.

Template overrides allow the designer to rearrange Joomla!'s layouts. So, for example, assume you wanted the author name to be printed beneath the article. You could do so using a template override. To begin, you could copy the article view, default layout located at components\com_content\views\article\tmpl\default.php into the html\com_content\article\default.php, applying changes desired.

As you can see from the example, template overrides are stored in a folder system that follows this pattern:

your template \ html \ component or module name \ view name \ layout file.php

If you only want to alter the article layout, that is the only file required. When Joomla! finds a layout file for a component or module view within the html folder, it uses this file instead of the core layout. Thus, an override.

Add "," after then

Then change the descriptions between the tags and add other tags for filename, position and param.

Released? Published? idk

The day you finished the template (format mm/dd/yy)

You are already close to final. Very good!
Amy

[HarryB]

Looks good to me...a couple of suggestions

2.3 Template Overrides - use Amy's verbiage and maybe add a few words like this: "The big advantage of the template overrides is that one does not have to "hack the core" to customize the layouts."

4.1 How to make a screenshot - maybe a reference to the Firefox "Screengrab" plugin as an alternate way of taking a  screenshot...for those who are not familiar with or do not have The Gimp installed?

General - maybe include an example of an actual templateDetails.xml file as an appendix or whatever.  RHUK Milkyway might be a good example.  It's not too complicated and does have a couple of fairly simple overrides. 

5.2 Linux - show example for filename.tar.gz too.  Reason I say this is that I know that most Windows zip programs can decompress tar.gz files.  Not so sure about tar.bz2 files. (if I'm wrong here never mind!)


Good work 

[ianmac]

A suggestion for a slight amendment to Amy's verbage:

Template overrides allow the designer to customize component and module output.  So, for example, assume you wanted the author name to be printed beneath the article. You could do so using a template override. To begin, you could copy the default layout of the article view (located at components\com_content\views\article\tmpl\default.php) into the html\com_content\article\default.php and apply desired changes to the new file.

As you can see from the example, template override files are stored in a folder system that follows this pattern:

your template \ html \ component or module name \ view name \ layout file.php

If you only want to alter the article layout, that is the only file required. When Joomla! finds a layout file for a component or module view within the html folder, it uses this file instead of the core layout. Thus, an override.

The BEEZ template is included with the default Joomla! install and demonstrates how the output of components and modules can be customized.

Ian

[Chris Davenport]

Hi Thomas,

This is an excellent first draft.  You're definitely on the right track. 

A few points to consider:

The title of the document should be "How to Package a Joomla! 1.5 Template for Distribution", not "installation".

Section 1: "How does the installation process work?" needs a bit of work.  Remember there are three modes to describe: Upload package file, install from directory and install from URL.  I think it is also worth mentioning that the installer unpacks the uploaded package into a temporary directory and where that directory is.  You state that the installer saves some information about the template into the database.  Well, unless those pesky devs have changed things again, that isn't true. :-)  I don't think anything is saved in the database (which incidentally makes manual installation of templates pretty simple).  If you need help understanding the sequence of events, just ask on the forum.

"TemplateDetails.xml" should be "templateDetails.xml".  Windows doesn't care about case, but most other platforms do.

In 2,2 Recommended folder structure, it might be worth mentioning that template_thumbnail.png and favicon.ico are both optional and that params.ini is only required if the template has parameters.

2.3 Template Overrides needs expanding as noted by others.

3.1 Sample (of templateDetails.xml).  I think the sample needs to be more comprehensive and include all possible elements for a templateDetails.xml file as it will be relatively simple for a reader, cutting and pasting, to strip out the ones not required.  Consequently, you need to include and elements.  I think Beez may have examples of these elements.

Note that TPL_RHUK_MILKYWAY is a translatable string.  I seem to remember there was a bug that prevented it from actually being translated, but maybe this has been fixed now.

In another GHOP task we are attempting to write a Document Type Definition (DTD) for 1.5 templates and as this sample will be used a lot it would be a good idea to include the appropriate DOCTYPE and ensure that it will validate against it.  Please add the following line between the and tags:

Code: Select all

<!DOCTYPE install PUBLIC "http://dev.joomla.org/xml/1.5/template-install.dtd">

and re-order the tags as follows: name, creationDate, author, authorEmail, authorUrl, copyright, license, version, description, files, languages, administration, params.

3.2 Description of the nodes:
Under "install", note that you can add a "client" argument which can take the value "site" for a front-end template, or "administrator" for a back-end template.

5.1 Creating the archive file - Windows
You describe opening Explorer then clicking on New -> ZIP compressed folder.  Is this a native function in Explorer now?  Or do you have to install a separate ZIP program, like WinZip?  I've not used Windows for some years so I may be a bit out-of-date here.  If it's not native you will need to describe where to get it.  Also, good place for a screenshot, but I think you knew that. :-)

Might be an idea to add an instruction for Mac users.  I don't have a Mac myself so I don't know how you would do it, but others in the community will know.

Seems like a long list, but actually these are mostly minor points.  This is a really good attempt.  Keep up the good work. 

Chris.

[ianmac]

One more thing to note...  You should also include the tag - it makes templateDetails.xml files a lot shorter and easier to read!

Ian

[AmyStephen]

Excellent work here - but we need you to take these ideas and work them into a revision, as soon as possible. The due date is upon us.

Again, EXCELLENT work! You should feel very good about this!

Amy

[littlegeniuz]

Thanks for your feedback.
Here is the next draft, with screenshots and your suggestions implemented.

I have another question: How does the tag work?
And could someone make the screenshot for How to make a archive file (Windows) for me, because I have only a German Version of Windows.

thanks
tom

[littlegeniuz]

Excuse me, I have forgotten to attach the document!
Here it is: LINK

tom

[AmyStephen]

Tom -
I get a blank page when I click that link.

Amy

[AmyStephen]

Got it finally!

installer

There are three modes with which you can start the intaller:

URL into (space)

from the specified URLinto the folder

Recommended

Recomendet folder structure

Add / after php (like others)

%path%/php

Really, really good work.
Amy

[Chris Davenport]

Very good work!  Almost done now. 

Can you copy/paste the sample XML file from here please:

Code: Select all

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE install PUBLIC "-//Joomla! 1.5//DTD template 1.0//EN" "http://dev.joomla.org/xml/1.5/template-install.dtd">
<install version="1.5" type="template" client="site">
	<name>Name of your template</name>
	<creationDate>Creation date</creationDate>
	<author>Your name</author>
	<authorEmail>your E-mail</authorEmail>
	<authorUrl>your Homepage</authorUrl>
	<copyright>your copyright notice</copyright>
	<license>Licence of your template</license>
	<version>Version of your template</version>
	<description>Description of your template</description>
	<files>
		<filename>put your filenames here</filename>
	</files>
	<languages>
		<language tag="language">Name of the language file</language>
	</languages>
	<administration>
		<languages folder="admin">
			<language tag="language">Name for the admin language file</language>
		</languages>
 	</administration>
	<positions>
		<position>all used positions</position>
	</positions>
	<params>
		<param name="parameter1" type="input" label="Parameter 1">
		</param>
	</params>
</install>

This is your original sample tweaked so that it validates against our new DTD (I gave you an incorrect DOCTYPE last time, for which I apologise).  There was nothing really wrong with your original (the installer would have been fine with it), but DTDs impose a higher level of rigour and I think it is important that examples used in documentation do actually validate, as this now does.

Couple of other minor tweaks needed:

• We have never specified a format for creationDate and a number of different formats are currently in use.
• In the table explaining the XML tags, you have instead of .  While the English spelling (licence) is perfectly okay in the description (and indeed preferred), the installer requires the American spelling (license) in the XML tags themselves.  [Note to self: must see if we can make the installer more tolerant]
• In the language table entry, you explain that the "tag parameter is for the language contained".  I think you need to say that the parameter is the ISO language code for the language (example: "en-GB")
• Under 5.2 Linux, you might like to include instructions for producing .zip files (using gzip).  Just for completeness.

You're nearly there!  I think with these final few, minor tweaks, we'll be able to say it's finished.

Well done.
Chris.

[HarryB]

Yet one more small correction:

5.2 Linux, 1. Create a tar.gz. file

change tar -czf filename.tar.bz2 to tar -czf filename.tar.gz

excellent work 

[littlegeniuz]

I think I have finished this document and it's ready for the final review.

Here is the link

tom

[Chris Davenport]

Hi Tom,

Err.... You don't seem to have made the changes suggested by Amy, Harry or myself (above).  Or perhaps that's the wrong link.

Regards,
Chris.

[littlegeniuz]

Excuse me, I have uploaded an old version of the document.

Now the link should work.

tom

[HarryB]

Took a quick look at latest and looks done to me!   

I give this a rating of   out of  !

[trombonechamp]

Good job!

You might want to consider putting things like directory names, button names, file names, etc. in quotes. 
You will probably want a space before the parenthesis in section 2.2. 
Under section 4.3, Firefox should be capitalized.

Under Linux, the terminal is what you get if you press Ctrl+Alt+F1,F2,etc.  A "terminal emulator" is a program for X that acts like a terminal.  So really, what you may want to say in section 5.2 is "your favorite terminal emulator (Konsole, xterm, etc.)".  Do you really need to change this?  No.  Any Linux user will know what you mean either way.  It is your choice; I could care less either way.  The real name, though, is terminal emulator. (But some new users may think a "terminal emulator" it is some rare program they don't have, so you may want to list some off if you choose this route)

You did a great job on this!

[AmyStephen]

I give this a rating of   out of  !

That is high praise, indeed! And, I agree! I think we all do!

Certainly, consider Max's comments (previous) - he has had *excellent* advice for many of the entries, and what he says is worth considering.

This work is accepted, as is, too.

When you publish your work on Google, the task will be marked as complete. As you can tell, this is well received and obviously quality work. I appreciate all of the community involvement - and it was great to see you integrate in what others felt was important. You have good ability working with others.

This document is going to be useful and used. Thank you for your contributions to Joomla!. Once your Google task is closed, you will be free to select another task, if you choose.

Amy