The Joomla! Forum ™

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:



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

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

_________________
http://Twitter.com/AmyStephen
http://www.alltogetherasawhole.org/

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

_________________
http://Twitter.com/AmyStephen
http://www.alltogetherasawhole.org/

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

tom

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.



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

_________________
http://Twitter.com/AmyStephen
http://www.alltogetherasawhole.org/

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

This is EXCELLENT work!  8)

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

Be gender neutral.

Try this approach:


Template overrides

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


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


Add "," after then


Released? Published? idk


You are already close to final. Very good!
Amy

_________________
http://Twitter.com/AmyStephen
http://www.alltogetherasawhole.org/

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 

_________________
If you need a helping hand, use the one at the end of your own arm.
www.hrpr.com

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


Ian

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:

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

_________________
Joomla Leadership Team - Production Working Group

Joomla Web Services http://www.kickstarter.com/projects/964120480/joomla-web-services
Lion Coppice http://www.lioncoppice.org

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

Ian

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

_________________
http://Twitter.com/AmyStephen
http://www.alltogetherasawhole.org/

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

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

tom

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

Amy

_________________
http://Twitter.com/AmyStephen
http://www.alltogetherasawhole.org/

Got it finally!

installer


URL into (space)


Recommended


Add / after php (like others)


Really, really good work.
Amy

_________________
http://Twitter.com/AmyStephen
http://www.alltogetherasawhole.org/

Very good work!  Almost done now. 

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

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.

_________________
Joomla Leadership Team - Production Working Group

Joomla Web Services http://www.kickstarter.com/projects/964120480/joomla-web-services
Lion Coppice http://www.lioncoppice.org

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 

_________________
If you need a helping hand, use the one at the end of your own arm.
www.hrpr.com

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

Here is the link

tom

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.

_________________
Joomla Leadership Team - Production Working Group

Joomla Web Services http://www.kickstarter.com/projects/964120480/joomla-web-services
Lion Coppice http://www.lioncoppice.org

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

Now the link should work.

tom

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

I give this a rating of   out of  !

_________________
If you need a helping hand, use the one at the end of your own arm.
www.hrpr.com

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!

_________________
Leonard Bernstein for President -
Web Development Services: www.BernsteinForPresident.com
My Software Freedom Blog: Trombonechamp.Wordpress.com

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

_________________
http://Twitter.com/AmyStephen
http://www.alltogetherasawhole.org/