Joomla! Discussion Forums

Below is a list of topics that can/should/might be covered by the template tutorial and related documentation.  Please suggest any additions or amendments in this thread.  I'm sure I must have forgotten something really important. :-)

We can carry on tweaking this list as we go, but I'd like to get started on the next step which is to actually write something. :-)

This is actually a copy of the list in the new developer wiki here: http://developer.joomla.org/wiki/Outline_for_Template_Tutorials.  If you have write access to the wiki you can make amendments directly there.  If not then make your suggestions in this thread.

Introduction to Joomla! templates
What is the purpose of a template?
What can you do with a template?
Templates supplied with Joomla!
How to switch templates
How to install templates

Understanding Joomla! templates
Where are templates located?
What is the typical template directory structure?
What is the purpose of the templateDetails.xml file?
What is the purpose of the index.php file?

Upgrading a Joomla! 1.0.x template
Legacy mode
Upgrading your index.php file
Upgrading your templateDetails.xml file
Changes to CSS classes
Replacing patTemplate
New features introduced in Joomla! 1.5 templates

Customising the Milkyway template

Customising the Beez template

Creating a basic Joomla! template
Setting up a directory structure
How to edit the files
Creating a basic templateDetails.xml file (not needed???)
Creating a basic index.php file
Testing the template

More advanced Joomla! templates
Quirks mode and how to avoid it
Which DocType header to use
Setting up page width
About CSS page layouts
Source ordering
Horizontal centering
PHP essentials (eg. echo, if-then-else)
Adding images
Declaring module positions
Finding module positions on any given page
Changing the site favicon

Cascading Style Sheets (CSS)
Where to put CSS files
List of core CSS classes with explanations
Page class suffixes
Module class suffixes

More on Joomla! modules
Counting modules in a given module position
Counting modules in multiple module positions
Collapsing columns
Creating rounded corners
What is module chrome?
Applying custom module chrome
Cascading module chrome styles

Web content accessibility
Introduction to web content accessibility
Accessibility standards
Validating against accessibility standards
Source ordering

Template parameters
Defining a parameter in templateDetails.xml
Parameter types supported
Page for each parameter type
Retrieving parameter data in a template file

Fonts and typography
Font families
Font metrics
Text resizing

Template overrides
How to override the output from the Joomla! core

Template translations
Creating a language definition (INI) file
Adding a language file to the templateDetails.xml file
Embedding translatable strings in the template file

Distributing Joomla! templates
How to choose a suitable license
How does template installation work?
File structure for packaging
Creating a thumbnail preview image
Packaging the template

Advanced topics
How are templates executed?
Customising the 403 and 404 error pages
Adding JavaScript
Enhancing template performance
Administrator (back-end) templates

Appendix
What jdoc:include types are available?
Standard module chrome styles
Default CSS classes
Configuration variables deprecated in Joomla! 1.5
Where can you learn about HTML?
Where can you learn about CSS?
Operators for use with the countModules function
Objects
Security do's and don't's
AJAX
Glossary

Hi!
If there is some possibility then I am ready to contribute.

Thanks!

Hi Sukalyan,

I've just sent you an email.  Thanks for volunteering.

Regards,
Chris.

Hello Chris,

I would like to volunteer and assist the Joomla Community in development of documentation or whatever is necessary. My background is in graphic design, technical support and most recently web development.  I have experience in creating step by step standard operating manuals and training pamphlets with unbelievable attention to detail (sometimes to my own demise, but I believe it is appreciated in technical documentation!) 

My experience in Joomla is about six months so I consider myself a newbie. I've been learning by trial and error and would like to hasten my path of knowledge by jumping in and helping out. I have minimal experience in php and css and have modified templates but never created one. I have created three joomla sites to date and just yesterday installed Joomla 1.5 RC3 to begin beta testing. Is there anything I may assist you with?  Maybe you need a tester for the documentation that is all ready written (with the fresh eyes of mine!) or I can jump in at any point you'd like.

Thank you,
-Kara

Thank you Chris,

I look forward to working with you and the rest of the team!

-K

p.s. I believe I'm one post away now! ..... 

If I could add one item on the list.  Drop-down submenus off the tool bar at the top.

I have been playing with Joomla for only 1 week now and I need to have sub-menus on my toolbar at the top, I know it can be done because I have downloaded templates with it but I can NOT find anywhere how to create them.  So for now I have one template that I downloaded that I am modifying to work and look the way I want.  I think it is both the wrong way to do it and much more time consuming in the long run to modify it but I could not find a way otherwise.

  It might be too advanced for your tutorial or I have been looking in all the wrong places.

Hi Chris,

Here are my comments. Overall it's looking really good.



I would place New Features in Joomla 1.5 templates at the top of this list. I think in general it helps to go broadview then specifics, and if you are upgrading from a 1.0 template, you will want to know what's new and why one should upgrade, before actually learning how to do it?

Upgrading a Joomla! 1.0.x template
New features introduced in Joomla! 1.5 templates
What is Legacy mode?
Upgrading your index.php file
Upgrading your templateDetails.xml file
Changes to CSS classes
Replacing patTemplate



I would create this list like this:

Customizing Default Joomla Templates
>Pro's and con's of table layout<
>Understanding the Milkyway template (what makes it special and unique from Beez and commercial templates?)<
>Understanding the Beez template (what makes it special and unique from Milkyway and commercial templates?)<
Customizing the Milkyway template
Customizing the Beez template
>Troubleshooting modified templates<
>What to avoid when modifying a template<



I think the Creating a basic templateDetails.xml file is needed, especially if the designer is going to create other positions or wants to relabel to suit his or her working style. How about this:

Creating a basic Joomla! template
Setting up a directory structure
>Verifying permissions<
How to edit the files
Creating a basic templateDetails.xml file
Creating a basic index.php file
Testing the template



More advanced Joomla! templates
Quirks mode and how to avoid it
Which DocType header to use
Setting up page width
About CSS page layouts
Source ordering
>Horizontal and vertical centering<
PHP essentials (eg. echo, if-then-else)
Adding images
>Changing image paths of default system images<
Declaring module positions
Finding module positions on any given page
Changing the site favicon



I'd make this clearer, something like:

Cascading Style Sheets (CSS)
Where to put CSS files
>Using multiple CSS files in Joomla<
>List of Joomla generated core CSS classes (with explanations)<
>Suggested CSS methods to introduce new declarations or alter generated ones<
Page class suffixes
Module class suffixes

I'd like to clarify this: Basically it seem there are users who may not understand CSS and how to cascade properly and from what I've looked at in the generated code, it seems to use stylesheets without cascading them. What I mean is that the declarations are specific rather than contextual. What isn't clear to me is whether this is out of necessity because of the code base, or because people are lazy or misunderstanding more elegant methods of using css?

This new list item will refer to a designer how to add class suffixes in the admin backend  as listed in Page class suffixes & Module class suffixes, but also recommend other methods. I think it would also be useful to explain what CANNOT be done in Joomla with style sheets, like add id's to particular list elements (something I'm wishing for). I think it is VERY useful to explicitly state these kinds of things, because often people trawl looking to do something and they can't find it. If we state the limitations in comparison to what people know, then it communicates. For example, Joomla isn't CSS-centric like Dreamweaver. Templates mean something different in Joomla than DW. What I mean is that there are no tools to manipulate CSS from the backend. One must edit the entire file. The other thing is that there are different discrete places to inject css declarations into the generated code. The foremost being the template and the next being different parameters in a module, component, or plugin, or even in global settings.

I do not mean that stating what cannot be done is a failing, but actually an acknowledgement that if a designer is going to use joomla, the approach is going to be far far different then the work methods designers typically are used to. If we address that, a lot of anxiety can be thwarted and not make designers feel like they are decoding the Rosetta Stone. :)

If enough designers speak up, of what they need of Joomla then that can be addressed at that point, but if we give a "state of the union" at least it helps people orient themselves and enable them to make better decisions.



I am completely in the dark why modules need to be counted. If someone could explain this to me, I'd appreciate it. Rather than encase HTML in PHP, why not just let the CMS generate the code and then use CSS to lay it all out?

Ideally, Joomla should spit out relatively unstructured divs with the appropriate HMTL inside them, with the placement of those divs layed out with CSS.

The holy grail at this point need not be whether the HTML looks the same in all browsers anymore (since if one is using webstandards methods to code templates, it will all work), but rather to optimize content for SE's. Meaning place your important content at the top of a page and then use CSS to place it where you want it on the page. That is, Joomla should be able to spit out content in any order and the CSS does all the work presenting it. Again, this is a holy grail, but I think a worthy one to stretch to.

I'm wondering if this counting of modules is a residue of creating layouts with table tags. If this is the case, I suppose then it's relevant, but CSS div layouts can do it all. I'd also like to propose a section on web standards:

Web Standards
What are web standards?
Why follow them?
Considering about future browsers and new devices
Considering about backwards compatibility
Web standards resources




I'd like to see a fragument added in Web Content Accessibility on Section 508. Of course, it's only relevant to those people creating sites in the States, but I think having a link and an explanation of what it is, serves all of the Joomla community, if only to be aware of disability issues. If there are other laws in effect in other countries about disability access, they should be posted here as well.

Web content accessibility
Introduction to web content accessibility
>Section 508 and other laws about disability access<
Accessibility standards
Validating against accessibility standards
Source ordering



Now this needs to be fleshed out far more than one list item ! :)

Is there a way of learning from the community, what are the most likely things people want to do with overrides and the best methods to do that?

I think there should be a definition for each component and module, how the code is structured and suggested ways of manipulating the code.  I'd also like to see there be something here that shows different ways others who have come before have created overrides.

That is, examples of a module or component with a before and after override. This will allow others to see how to do overrides properly and stimulate conversations on what can be done with overrides, where before one thought one had to write an entirely new extension. Does it make sense?



Does something need to be mentioned here about how translation works to give an overview and context of the inner workings? I propose this:

Template translations
>Overview of Joomla's translation engine<
Creating a language definition (INI) file
Adding a language file to the templateDetails.xml file
Embedding translatable strings in the template file



How about adding something about mootools?

Advanced topics
How are templates executed?
Customising the 403 and 404 error pages
Adding JavaScript
>What is Mootools<
>A few simple mootools implementations<
>Links to mootools tutorials<
>Joomla implementations of mootools in the community<
Enhancing template performance
Administrator (back-end) templates




How about adding the following to the Appendix? Most template designers know something about HTML and CSS, they have their resources. In this way the templates are centric to programmers who may not understand HTML and CSS nuances. I understand perhaps placing links in the Appendix about PHP and mySQL isn't directly about making templates, but if a template designer is looking for what PHP's foreach() function does and what its arguments are, then having some resources in the Appendix is not a bad thing.

Again this is thinking about user goals, and not features. Scenarios, not implementations.

Appendix
What jdoc:include types are available?
Standard module chrome styles
Default CSS classes
Configuration variables deprecated in Joomla! 1.5
Where can you learn about HTML?
Where can you learn about CSS?
>Where can you learn about Javascript?<
>Where can you learn about Mootools<
>Where can you learn more about PHP<
>Where can you learn more about mySQL?<
>Where can you learn more about server configuration<
>Where can you learn more about UNIX?<
Operators for use with the countModules function
Objects
Security do's and don't's
AJAX
Glossary

My last comment is that I'd like to see rich interlinking from the template wiki to other joomla wiki's so if there is encouragement when writing documentation for people to offer links to other related topics housed at other websites and wiki's this would make the source incredibly valuable. This may be obvious, but I'm not sure if anyone was explicitly stated that.

I hope this is helpful!

Best,

Wow!  Now that's what I call a contribution! 

I have implemented almost all of your suggestions, so I'll just comment on a few things....


All of the above, I think.


I don't think they need to be counted, but it is important to know whether there is at least one module present or not.  Since the code used to determine if there are modules present returns the number, well, that information might as well be returned to the template.  Who knows?  Someone might think of a use for it.


Well, my experience is that clients still want it to look (more or less) the same in all browsers.  The fly in the ointment of web standards is that we still need to make it look good in IE6.  Indeed, looking at the joomla.org domain I can tell you that of the 37% of visitors using Internet Explorer, 34% still use IE6.  That's a lot of visitors!  But okay, you did say it was the "holy grail". ;-)


I don't think so.  As I said above, I think it's just so easy to return a number instead of just true/false.


I think the problem with template overrides is that they are so new that most designers and developers have yet to come to grips with them.  I listen attentively to those who know more than me, but I still have much to learn.  The feedback from the Template Contest is that none of the contest entries handled this kind of stuff in the way that they probably should have done.  The plan is that we will generate documentation in the process of correcting these issues with the template contest winner.


The plan is to bring all the material in the "other Joomla! wikis", that is dev.joomla.org and developer.joomla.org/wiki, into docs.joomla.org, so there will probably only be one wiki going forward.  The reason is partly to make it easier for rich interlinking, but also to make it easier to produce modular documentation.  Essentially, we are creating a single, central database of documentation "chunks" that can be re-used in different contexts and for different audiences.

As for linking to external websites, that has to be done carefully as experience has shown that links go stale and create a maintenance headache and they can be abused for promotional purposes.  So yes, links are good, but they just need to treated cautiously.


It certainly is!  Thanks for the input.

How about registering on docs.joomla.org and joining us in writing the documentation?

Regards,
Chris.

OK Chris!

I've registered. But am not certain what to do once registered. Please advise me to the how to or where I should join in, or what have you?

Like I said, I am a bit snowed, but I will try to touch base and see what's happening in docs.joomla.org

best,

Hi madamep,

I'm just catching up on the backlog after the Doc Camp weekend so my apologies for the delay in responding.  I think you've found your own way in to docs.joomla.org in any case. 

Regards,
Chris.