045 - Write a DTD for template XML installer files (templateDetails.xml)

chalet16 · **Joined:** Fri Nov 30, 2007 1:14 pm **Posts:** 40

Code:

 One line summary

Write a DTD for template XML installer files (templateDetails.xml).
Description

Review the PHP code for the template installer and use it to construct a
Document Type Definition (DTD) file which can be used to validate correct
syntax for any given Joomla! 1.5 templateDetails.xml file. Download at
least 10 templates from a range of sources and validate them against the
DTD using a suitable validating parser. Write a document describing how to
validate a template installer file.

You might find the following DTDs to be useful starting points:

   1. Components: http://dev.joomla.org/xml/1.5/component-install.dtd
   2. Modules: http://dev.joomla.org/xml/1.5/module-install.dtd 

(Note that these are not necessarily accurate or up-to-date).

The document should comply with current Joomla! Editorial Style Guidelines
and guidelines for the Template Tutorials Project.
Skills Needed

    * Knowledge of PHP
    * Knowledge of XML and DTDs would be useful. 

Difficulty

Advanced.
Work Product

DTD as described above. Document as described above.
Licensing

All code must be created using the GNU General Public License version 2.
http://www.gnu.org/licenses/old-licenses/gpl-2.0.html#SEC4

Documentation written for this task must be made available under the
Joomla! Electronic Documentation License.
Extra Credit (optional)

Do the same for Joomla! 1.5 component, module and plugin XML installer
files (these are all very similar so much of the work will already have
been done, but there are important variations that must be noted).
Time Limit

4 weeks.

My nick name is Chalet. I am 13 years old. I live in Thailand. I have been using Joomla for about 1 years. I'm trying to do this as fast as possible.

Sorry for my bad English and short introduce.

Claimed: Nov 29 Due: Dec 25

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

[/me]

AmyStephen · **Posted:** Fri Nov 30, 2007 3:26 pm

Welcome to Joomla! Chalet!

There is no hurry to complete this task, you have four weeks. Take your time so that you can learn and do a good job. We will find you a mentor who is talented in Joomla! development to assist you with your work. Meanwhile, please ask for help when you need it. We are here to help you be successful with your task.

Have fun and good luck in the contest!
Amy

chalet16 · **Joined:** Fri Nov 30, 2007 1:14 pm **Posts:** 40

I could find the way to make DTD for case like this.(non sequence)

Quote:

aaa
02/11/2007
abcd
....

and

Quote:

aaa
abcd
02/11/2007
....

to be both valid

Anyone know about this?

Thank you very much.

Chris Davenport · **Posted:** Wed Dec 05, 2007 9:09 pm

Hi Chalet,

Although I wrote the specification for this task I am not an expert on DTDs, so all I can do is suggest a possible course of action.

The specification for DTDs is here: http://www.w3.org/TR/xml/#dt-doctype but it is a difficult read, especially as it appears to be hopelessly entwined in the XML specification. From my quick reading of it, it appears that the order in which elements appear in the XML is constrained by the DTD, however I would suggest that you run both XML samples through a validating parser and see if it rejects only one of them. If it rejects neither then you don't really have a problem.

If, as seems likely, the order of the elements is significant, then I would suggest that you use the order given in the sample DTDs referenced in the task description. The object of this task is that the DTD produced will become the "gold standard" for validating template XML files. If this means that a strict order must be imposed then so be it. It is, of course, trivially easy for template developers to change the order of the elements so as to validate against the DTD.

Incidentally, the reason we want a DTD is that there is a class of errors encountered when installing templates that can be avoided by encouraging template developers to validate their XML files before distribution. But they can't do that without an accurate DTD to validate against.

Hope this helps. If it doesn't I'll try to find you a DTD expert!

Regards,
Chris.

chalet16 · **Joined:** Fri Nov 30, 2007 1:14 pm **Posts:** 40

Chris Davenport wrote:

Hi Chalet,

Although I wrote the specification for this task I am not an expert on DTDs, so all I can do is suggest a possible course of action.

The specification for DTDs is here: http://www.w3.org/TR/xml/#dt-doctype but it is a difficult read, especially as it appears to be hopelessly entwined in the XML specification. From my quick reading of it, it appears that the order in which elements appear in the XML is constrained by the DTD, however I would suggest that you run both XML samples through a validating parser and see if it rejects only one of them. If it rejects neither then you don't really have a problem.

If, as seems likely, the order of the elements is significant, then I would suggest that you use the order given in the sample DTDs referenced in the task description. The object of this task is that the DTD produced will become the "gold standard" for validating template XML files. If this means that a strict order must be imposed then so be it. It is, of course, trivially easy for template developers to change the order of the elements so as to validate against the DTD.

Incidentally, the reason we want a DTD is that there is a class of errors encountered when installing templates that can be avoided by encouraging template developers to validate their XML files before distribution. But they can't do that without an accurate DTD to validate against.

Hope this helps. If it doesn't I'll try to find you a DTD expert!

Regards,
Chris.

Thank you very much .

chalet16 · **Joined:** Fri Nov 30, 2007 1:14 pm **Posts:** 40

I have finished written templateDetails.dtd .
Could you upload it or tell me what URL would you will upload templateDetails.dtd to easy write document how to use it?

Thank you

PS. templateDetails.dtd is rename to templateDetails.dtd.txt and attach with this replies

chalet16 · **Joined:** Fri Nov 30, 2007 1:14 pm **Posts:** 40

Could any one upload templateDetails.dtd into joomla site ?

Thank you

Chris Davenport · **Posted:** Sat Dec 08, 2007 7:59 am

Hi Chalet,

I'm going to try and look at this in more detail over the weekend, but it looks really good so far!

Don't forget this part of the task specification:

Quote:

Write a document describing how to validate a template installer file.

This is most important as many template designers won't bother to use the DTD if the procedure is not explained to them. Remember to include instructions on how to add the DOCTYPE declaration to the XML file.

This work is going to be really useful to a lot of people.

Have fun!
Chris.

Chris Davenport · **Posted:** Sun Dec 09, 2007 12:34 am

Hi Chalet,

I've had a chance to play with the DTD now and it requires a few minor corrections:

I think that in the order of the subelements should to be the same as that used in the component and module DTDs referenced in the task description.
Also in the license subelement needs to be required (ie. "license" instead of "license?")
Arguments for should be

Code:

type (template) #REQUIRED
client (site|administrator) "site"
version CDATA #IMPLIED

should be removed as it is not relevant for templates.
Please use the same indentation as the DTDs referenced in the task description.

Good work so far!

Chris.

chalet16 · **Joined:** Fri Nov 30, 2007 1:14 pm **Posts:** 40

Chris Davenport wrote:

Hi Chalet,

I've had a chance to play with the DTD now and it requires a few minor corrections:

I think that in the order of the subelements should to be the same as that used in the component and module DTDs referenced in the task description.
Also in the license subelement needs to be required (ie. "license" instead of "license?")
Arguments for should be

Code:

type (template) #REQUIRED
client (site|administrator) "site"
version CDATA #IMPLIED

should be removed as it is not relevant for templates.
Please use the same indentation as the DTDs referenced in the task description.

Good work so far!

Chris.

Thank you very much.

But for "I think that in the order of the subelements should to be the same as that used in the component and module DTDs referenced in the task description." and " should be removed as it is not relevant for templates." I don't sure I should do that because in beez template it have administration element.

Quote:

....

en-GB.tpl_beez.ini

en-GB.tpl_beez.ini

left
right
.....

And all of template packed with Joomla it has different order than module and component.

Module's DTD:

Code:

<!ELEMENT install (name, creationDate, author, authorEmail, authorUrl, copyright, license, version, description, files*, languages*, media*, params?) >

but in Joomla Template (beez and rhuk_milkyway)

Code:

<install version="1.5" type="template">
   <name>beez</name>
   <version>1.0.0</version>
   <creationDate>19 February 2007</creationDate>
   <author>Angie Radtke/Robert Deutz</author>
....

It has very different from module's dtd.

Chris Davenport · **Posted:** Sun Dec 09, 2007 3:11 pm

chalet16 wrote:

But for ..... " should be removed as it is not relevant for templates." I don't sure I should do that because in beez template it have administration element.

Wow! I learn something new every day. You are right, I had foolishly assumed that a site template would not have any reason to put files into the administrator directory. Please leave in.

chalet16 wrote:

And all of template packed with Joomla it has different order than module and component.

That's true, but the idea is that these DTDs will become the standard against which all the core extensions will be validated. Third-party developers will be free to do the same if they wish. Consequently, once the DTDs are finalised we will amend the core extensions so they will validate against them. Although we might alter the order before we finalise, we want the order to be the same for all extensions.

How are you doing with the documentation for this task? I would suggest you show how to validate using the rxp validator as this seems to be the most readily available.

Keep up the good work!

Chris.

dynedain · **Posted:** Wed Dec 12, 2007 6:50 pm

How is this task coming? Is there a DTD available on the Joomla servers like there is for component and moduule installers? If so, what is the address?

Chris Davenport · **Posted:** Wed Dec 12, 2007 7:18 pm

Once Chalet has completed it I will upload the DTD to http://dev.joomla.org/xml/1.5/template-install.dtd so that templates can include the DOCTYPE to reference it. So (from memory) you would include:

Code:

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

in your templateDetails.xml file(s).

Regards,
Chris.

dynedain · **Posted:** Wed Dec 12, 2007 9:32 pm

Thanks! That will really be a help. Now if only the component installer DTD could be updated.....

Chris Davenport · **Posted:** Wed Dec 12, 2007 9:40 pm

Well, I very much hope that Chalet will attempt the Extra Credit option.

Quote:

Extra Credit (optional)

Do the same for Joomla! 1.5 component, module and plugin XML installer
files (these are all very similar so much of the work will already have
been done, but there are important variations that must be noted).

Regards,
Chris.

chalet16 · **Joined:** Fri Nov 30, 2007 1:14 pm **Posts:** 40

OK Now I have edit templateDetails.xml
And here is a document describe how to validate with DTD.
You can download it at http://www.whyworldhot.com/validate.odt (1.2MB)

Chris Davenport · **Posted:** Fri Dec 14, 2007 4:19 pm

Hi Chalet,

This really is very good work and I'm sure it will be much appreciated by a lot of template developers. I have already uploaded the DTD to the "official" location on dev.joomla.org. Your documentation will be incorporated into the official docs as soon as possible.

One correction to make, and that's my fault, not yours. The DOCTYPE declaration is missing the public id. Please change to read as follows:-

Code:

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

I tested all using xmllint, rxp, Eclipse and validome and all worked perfectly.

Please consider going for the extra credit work and check/update the component, module and plugin DTDs. You'll make a lot of people very happy if you do.

When you are happy with the work, please call for a final review.

Regards,
Chris.

PS: What is your last name? I'd like to make sure that you are credited with the work.

dynedain · **Posted:** Fri Dec 14, 2007 4:40 pm

Excellent!

Thank you so very much for doing this! I love using Eclipse which will automatically show errors and warnings from the DTD info.

Please please consider doing the module and template installers as well! It would be very much appreciaited!

chalet16 · **Joined:** Fri Nov 30, 2007 1:14 pm **Posts:** 40

Chris Davenport wrote:

Hi Chalet,

This really is very good work and I'm sure it will be much appreciated by a lot of template developers. I have already uploaded the DTD to the "official" location on dev.joomla.org. Your documentation will be incorporated into the official docs as soon as possible.

One correction to make, and that's my fault, not yours. The DOCTYPE declaration is missing the public id. Please change to read as follows:-

Code:

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

I tested all using xmllint, rxp, Eclipse and validome and all worked perfectly.

Please consider going for the extra credit work and check/update the component, module and plugin DTDs. You'll make a lot of people very happy if you do.

When you are happy with the work, please call for a final review.

Regards,
Chris.

PS: What is your last name? I'd like to make sure that you are credited with the work.

Chalet is my nickname. My firstname is "Witchakorn" and my lastname is "Kamolpornwijit".

I had change doctype in document (same links).

I think I will do all of the extra work because it's very similar to this work.

Thank you

AmyStephen · **Posted:** Fri Dec 14, 2007 4:53 pm

WONDERFUL Witchakorn!

I learned a great deal from you, much thanks! Nicely, nicely done, too.

One question. When I got to http://www.validome.org/xml/ - I do not see "DTD" near the Validate button. (Page 8 ).

Did I misunderstand the instructions?

Thanks so much - and especially for taking on the Extra Credit challenge - YOU ROCK!

Amy

chalet16 · **Joined:** Fri Nov 30, 2007 1:14 pm **Posts:** 40

AmyStephen wrote:

WONDERFUL Witchakorn!

I learned a great deal from you, much thanks! Nicely, nicely done, too.

One question. When I got to http://www.validome.org/xml/ - I do not see "DTD" near the Validate button. (Page 8 ).

Did I misunderstand the instructions?

Thanks so much - and especially for taking on the Extra Credit challenge - YOU ROCK!

Amy

"DTD" is here.

AmyStephen · **Posted:** Fri Dec 14, 2007 5:06 pm

When I got to http://www.validome.org/xml/ - I do not see "DTD" near the Validate button. (Page 8 ).

Thanks,
Amy

chalet16 · **Joined:** Fri Nov 30, 2007 1:14 pm **Posts:** 40

AmyStephen wrote:

When I got to http://www.validome.org/xml/ - I do not see "DTD" near the Validate button. (Page 8 ).

Thanks,
Amy

I am confusing with this site. What should I do?

AmyStephen · **Posted:** Fri Dec 14, 2007 5:21 pm

Is this the page you really want http://www.validome.org/grammar/ ?

If so, just update your document, changing http://www.validome.org/xml/ to http://www.validome.org/grammar/ .

Thanks!
Amy

Chris Davenport · **Posted:** Sat Dec 15, 2007 1:03 am

That's strange Amy. I can see DTD (and Schema) radio button next to Validate, exactly as the screenshot. Don't understand why you're not seeing it.

But actually, it doesn't matter as you don't need to click it anyway! With the correct DOCTYPE in the XML the validator will fetch the DTD from dev.joomla.org and perform the validation without you having to specify anything else.

Chris.

chalet16 · **Joined:** Fri Nov 30, 2007 1:14 pm **Posts:** 40

AmyStephen wrote:

Is this the page you really want http://www.validome.org/grammar/ ?

If so, just update your document, changing http://www.validome.org/xml/ to http://www.validome.org/grammar/ .

Thanks!
Amy

OK I have update document (in the same link again)
but I am confusing why page is different?

AmyStephen · **Posted:** Sat Dec 15, 2007 4:43 am

I don't know.

Sounds like it looks the same for you and Chris.

Maybe the better approach is to do as Chris suggests - not mention the Radio Buttons, at all. Since the DOCTYPE tells the validator what to do, it hardly matters anyway.

Very odd.
Thanks for this amazing work. (And for the extra credit work you also plan to share :-*

).

Amy

Chris Davenport · **Posted:** Sat Dec 15, 2007 5:57 pm

Just a quick update.....

I have amended the core templates (Milkyway, Beez and Khepri) to include the new DOCTYPE and to ensure that they validate against it.

Chris.

chalet16 · **Joined:** Fri Nov 30, 2007 1:14 pm **Posts:** 40

Chris Davenport wrote:

Well, I very much hope that Chalet will attempt the Extra Credit option.

Quote:

Extra Credit (optional)

Do the same for Joomla! 1.5 component, module and plugin XML installer
files (these are all very similar so much of the work will already have
been done, but there are important variations that must be noted).

Regards,
Chris.

What is module XML installer? What is different with http://dev.joomla.org/xml/1.5/module-install.dtd?

Please review plugin-install.dtd.
Thank you

dynedain · **Posted:** Mon Dec 17, 2007 5:04 pm

Quote:

What is module XML installer? What is different with http://dev.joomla.org/xml/1.5/module-install.dtd?

As far as I understand, that is the XML DTD necessary for installing modules on Joomla. There also is one for components, but both are out of date and were never setup quite right in the first place.

Joomla! Discussion Forums

Forum rules: Please click here to view the forum rules

045 - Write a DTD for template XML installer files (templateDetails.xml)

Quick reply

Who is online