Template Tutorial - Let's Get Started!!!

[ericlitman]

Something I'll add to the outline:

instance variables/objects available within templates:
- in top-level pages
- in template overrides for com_content
- what I can expect to be set where, and how to get at the things I need (e.g. via class methods) when what I need isn't already set

An overview within the developer section with a detailed reference in the appendix would be ideal.

[Chris Davenport]

instance variables/objects available within templates:
- in top-level pages
- in template overrides for com_content
- what I can expect to be set where, and how to get at the things I need (e.g. via class methods) when what I need isn't already set

An overview within the developer section with a detailed reference in the appendix would be ideal.

Hi ericlitman,

Yes, I think that would be very useful, although a complete list would be difficult as almost the entire API is available from within the template.  It might be better to list just the objects and variables that a template designer is most likely to need.  Perhaps you could get us started with such a list?

Regards,
Chris.

[holsum]

Reading through the posts it looks as if you are just starting to put together tutorials regarding Joomla1.5 templates.

Is there any documentation on handling "if" statements in the templates.  I have utilized them extensively in my Joomla.1.xxx templates to create very smart interactive templates.

thanks,
-holsum

[RedEye]

just look at the default template, there are some if statements you can insperated on for i.e

Code: Select all

<?php if($this->countModules('left')) : ?>
<jdoc:include type="modules" name="left" style="rounded" />
<?php endif; ?>

or a if else

Code: Select all

<?php if($this->countModules('left')) : ?>
<div id="maincolumn">
<?php else: ?>
<div id="maincolumn_full">
<?php endif; ?>

hope it helps you

[Chris Davenport]

The conditional statement syntax has not changed between 1.0.x and 1.5 as it is PHP syntax that has nothing to do with Joomla!  But your question raises the thought that many template designers may not be familiar with PHP coding and so we ought to include some basic pointers to stuff like this in the template tutorial.

Regards,
Chris.

[tekcronic]

I would agree with covering some of the basic PHP coding practices as part of the template tutorial but would also say that ideas that could further enhance the templates using PHP with links to proper information on how this can be achieved with PHP.  Though I think more importantly is an explanation of what not to do because of security issues that may occur from improper PHP use in the templates.

[Chris Davenport]

Hi tekcronic,

Yes, I agree completely.  Could you start a list of topics that you think need to be covered?

Thanks,
Chris.

[tekcronic]

As templates seems to sound like a simple item to create I would both agree and disagree, because as I see it there are 2 basics methods of creating a template.  One is from the ground up and the other being my preference is modify existing templates (I get lazy but work twice as hard because I so dramatically change the templates sometimes I should start from the ground, but why reinvent the wheel?  ).

As for modifying an existing template there are many mistakes that could be made as one may not fully grasp the original concepts and see only the end result thus when editing occurs the designer may find that they get the results they think they want while breaking one or more other features of a template that may at first go unnoticed.

To that nature I think "Best Practices" should be covered at some point for both the original designers and editors.

Topics for Template Designers and Editors:

Basics:

A list of required markup languages used for the most basic template. (HTML and CSS)
Direct Links to sites that accurately teaches these skills (like w3schools.com, my favorite)
Minimum Required PHP lines for a template.
suggested list of tools (minimal options for the absolute beginner)
provide a basic template with as little markup as possible.
guide on how to structure a template in a single column with no graphics
Information on how to license your work.


Intermediate:

information about Web Content Accessibility
reasons to learn Accessibility NOW
how to modify single column to create 2-column and 3-column Layouts (reminder of Accessibility)
make template compatible with older browsers (reminder of Accessibility)
add images (reminder of Accessibility)
reasons to use css images vs css color and how to.
adding modules and components

Advanced:

links for OO programing (again I'd say w3schools.com)
Tools to make creating templates easier
What is AJAX
common/possible security mistakes with AJAX in template
how to use scripting to create AJAX effects  (reminder of Accessibility)
Some common AJAX requests.

I think allot more should be covered but hey I am needing to play on my ps3 for a bit oh and something about sleep.

[fakhrul]

I would like to join developer's documentation team. but I can not get any way to express my desire. i can not send PM to Chris Davenport. I am a Computer Science graduate and having coding experience in PHP, javascript, html, css etc. I have no  skill in graphics .

Regards
Fakhrul

[Chris Davenport]

@tekcronic.  I've merged your suggestions into a kind of master list that I've been building up.  I'll publish it shortly so we can get down to some serious work. 

@Fakhrul.  Thanks for volunteering.  I've sent you a PM.

Chris.

[nyarnon]

Can anybody point me to the template tutorial for Joomla 1.5. Somehow there seems a mixup with a tutorial thread on how to write tutorials? Maybe it would be a good suggestion to change the subject here?

[Zaphrod]

Can anybody point me to the template tutorial for Joomla 1.5. Somehow there seems a mix up with a tutorial thread on how to write tutorials? Maybe it would be a good suggestion to change the subject here?

I think the Idea here is that the template tutorial will evolve over time so at the moment this thread is all there it. You might want to check out [url=http://"http://www.compassdesigns.net/tutorials/joomla-tutorials/joomla-1.5-template-tutorial.html"]Compass Design's Joomla 1.5 Template Tutorial[/url]. It is an excerpt from their upcoming eBook and is pretty informative.

[Chris Davenport]

Right now we don't have an official template tutorial for Joomla! 1.5.  This thread is about our attempts to create a new community-written series of tutorials.  Anyone is welcome to come and help us out in writing these new tutorials.  If you'd like to volunteer then either send me a PM or email me at chris (dot) davenport (at) joomla (dot) org.

Regards,
Chris.

[Chris Davenport]

Template Tutorial Update

We appear to have slowed down a bit, but actually quite a lot has happened over the past couple of weeks, mostly behind the scenes.  So here's a quick update.

Firstly, I've been building up a list of topics that I think should be covered and trying to organise them into some sort of order.  Thanks to everyone who has made suggestions on this thread and elsewhere.  I've started a new thread so you can suggest any additions or amendments to it there: http://forum.joomla.org/index.php/topic,215505.0.html

Secondly, I've been looking at what tools we can use to help us write and assemble the tutorials.  I've looked at DITA and the DITA Storm editor, but I think that the quickest and easiest way for us to get started is to use MediaWiki which supports modular documentation in a quite natural way.

Now it just so happens that we already have a small team working on setting up a shiny new Joomla! developers website which will eventually replace the old dev.joomla.org site and we have a MediaWiki installation set up and ready to go there.  I've transferred the few bits of documentation we already have to this new wiki and tested the modular documentation features.  I have to say that it is pretty user-friendly and seamless.

The next step is to invite all volunteers to take on parts of the work.  Can everyone please look through the list and select one or more topics that you would like to tackle.  We also need people to take on the task of creating and managing screenshots and other graphics, so if your forte is not writing then don't feel left out.  Let me know what you would like to take on by either sending me a PM or, particularly for those who can't yet send PM's, send me an email to [email protected] and I will arrange for you to have write access to the wiki.

New developers website is here: http://developer.joomla.org (early days yet).

Regards,
Chris.

[usulix]

I sent you an email, Chris, as you suggested.

I chose a few areas, but I am open to different ones.

I was unable to find any leakage regarding when someone thinks 1.5 may go final.

Did I just not look hard enough or is it still an unknown?

GG

[Chris Davenport]

Hi usulix,

Thanks for volunteering.  I've set you up on the wiki.  Release date for 1.5 Stable is indeed unknown at the moment as it depends on the number of bugs remaining in the code and the time it takes to fix them.  But RC3 is expected pretty soon now.

@everyone.  I have enabled file uploads on the wiki so you can add images to wiki pages now.

Regards,
Chris.

[Crash]

Hi all!

May I suggest the term 'fascicle' for a piece of documentation?
Donald E. Knuth uses it for the bits and pieces of his ongoing writing of The Art Of Computer Programming and according to Merriam-Webster, fascicle is 'one of the divisions of a book published in parts'. Fits perfectly imho. Just my €0.02.

[madamep]

Hi Chris (and everyone else),

I was reading your posts from August and I had an idea for the what to call the small document modules.

How about "fraguments"? 

Just a thought!

Cheers,

[Chris Davenport]

Thanks for the suggestions on naming, but let's not get hung up on terminology, let's get writing!!!

Some of the tasks in the Google Highly Open Participation Contest are aimed at trying to fill some of the gaps, but there's still plenty left to do.

Outline is here: http://www.developer.joomla.org/wiki/Ou ... _Tutorials

Regards,
Chris.

[frost]

I'm working on a tutorial of the backend for my clients. Feel free to use some info from it on he tutorials on joomla.
http://www.splendidesign.co.uk/index.ph ... 5-backend/
I'm in the middle of it, so there will be some changes in the next few days.
What do you think?

[wizeman]

I found this: http://www.joomlashack.com/index.php?op ... &Itemid=16

May be of help for those of us who can't wait for a tutorial

[epleste]

Oops 'There are two pages you fool' ,  :-[I'll read them both before asking such questions ever ever again - sorry

Can I delete this now?

Silly question maybe but where do I find the wiki so I can see what has already been done?

Thanks

[Chris Davenport]

Not a silly question at all.  It's here: developer.joomla.org/wiki

PM me if you'd like to join the fun and I'll set you up with write access. 

Regards,
Chris.

[LukeDouglas]

Joomla Team,

First off, thanks for all the hours you have dedicated to such a nice CMS application.  After evaluating, 11 other CMS systems, I am converting the majority of my websites to the Joomla system.

Is Joomla perfect?  Well, no one is perfect and so Joomla is not perfect but it's the best CMS system I have used.

Now to the documentation.  As someone with a background in application development for over 25 years and currently operates a website design/hosting service, I've seen a lot of applications and millions of line of code.  Yes, I did say millions.  For the 2000 year changeover, I had one application alone with over 3 million lines of code to evaluate (pre-OOP). Headaches..headaches.  Let's face it, developers can create some very nice pieces of code but documentation is usually an afterthought and, most of the time, it's pretty bad.

Your efforts to develop proper documentation is noteworthy but, you knew there was a but, I believe you need to recruit someone with an academic background in documentation to provide oversight and create a working format/structure.  Why?  Because they are trained in 'documentation'.  I have worked on sites where we brought in trained professionals to do this and, in every case, it was the right thing to do.

I may be naive but I have to believe that with the extensive use of Joomla all over the world that there has to be a couple of documentation experts who will dedicate their time to this worthy effort.  They can provide an overall structure, a fixed navigation outline as well as required format for individual pages and reference links.  All you have to do is to put out the 'call' for assistance on the Joomla website.

Just my two cents.

Luke

[Chris Davenport]

Hi Luke,

First off, thanks for all the hours you have dedicated to such a nice CMS application.  After evaluating, 11 other CMS systems, I am converting the majority of my websites to the Joomla system.

Is Joomla perfect?  Well, no one is perfect and so Joomla is not perfect but it's the best CMS system I have used.

Your efforts to develop proper documentation is noteworthy but, you knew there was a but, I believe you need to recruit someone with an academic background in documentation to provide oversight and create a working format/structure.  Why?  Because they are trained in 'documentation'.  I have worked on sites where we brought in trained professionals to do this and, in every case, it was the right thing to do.

I may be naive but I have to believe that with the extensive use of Joomla all over the world that there has to be a couple of documentation experts who will dedicate their time to this worthy effort.  They can provide an overall structure, a fixed navigation outline as well as required format for individual pages and reference links.  All you have to do is to put out the 'call' for assistance on the Joomla website.

We have made a number of calls for assistance over the years but so far no professional documentors have come forward, so instead we amateurs just learn stuff as we go.  "someone with an academic background in documentation" - do such people exist?  If you know of any university which has specialists in software documentation I would love to try to make contact.  I don't know of any Computer Science department that has a unit specialising in documentation research although there are so many universities it would be easy to miss one.    Maybe outside of CS?  Don't know.  If you have any leads I will gladly follow them up.

Thanks,
Chris.

[madamep]

Hi Luke,

Time for me to jump in!

I'm about to embark in a graduate program here in New Mexico called Organizational Learning and Instructional Technology, so yes, the programs do exist. I'm sure documentation is a smaller component of Instructional Technology.

My own passion is in Interaction Design, but I have offered to help, and am waiting to be contacted. I looked at what documentation attempts have been made so far, and maybe I haven't looked closely enough (so I don't want to seem as though I'm dismissing what's been done thus far), but it seemed that the Documentation team has already decided on a path, and I didn't want to jump in.

I'm not a documentation professional myself, but I like to think of myself as a user advocate, and I can say in my own experience, learning Joomla has been like reaching round my head to scratch my nose.

But I also want to say that I understand that it takes time for things to change, and it's easy to be an armchair quarterback, as they say in the States. But there are a lot of issues I have as a forward leaning want to be poweruser of Joomla.

A lot of Joomla's documentation I've read is based upon an implementation model, rather than user goals. But I do remember there being a lot of work on a FAQ, so I may just be too early to the party, as all the caterers and decorators are still setting up.

I would love to make a contribution, but don't want to crash the party. So yes, there are such things, and we do want to contribute, but perhaps it's that we don't understand the lingo that's being used, or it's hard to see the process you are setting up. I'm not clear, and to be honest, I've been away from this for at least a month or two, so I'm not sure how things are right now as I write this.

Best,

madame philosophe

[Chris Davenport]

Hi madame philosophe,

My own passion is in Interaction Design, but I have offered to help, and am waiting to be contacted. I looked at what documentation attempts have been made so far, and maybe I haven't looked closely enough (so I don't want to seem as though I'm dismissing what's been done thus far), but it seemed that the Documentation team has already decided on a path, and I didn't want to jump in.

We may have decided on a path, but that doesn't necessarily mean it's the right path.    Don't be afraid to suggest ideas or even come up with a better plan!

A lot if Joomla's documentation I've read is based upon an implementation model, rather than user goals. But I do remember there being a lot of work on a FAQ, so I may just be too early to the party, as all the caterers and decorators are still setting up.

You're right to say that most of the documentation is not task-orientated and this is something we're very much aware of.  It is something I want to address in the near future.

I would love to make a contribution, but don't want to crash the party. So yes, there are such things, and we do want to contribute, but perhaps it's that we don't understand the lingo that's being used, or it's hard to see the process you are setting up. I'm not clear, and to be honest, I've been away from this for at least a month or two, so I'm not sure how things are right now as I write this.

This party welcomes all comers so don't be afraid to come on in. 

If there's some lingo you don't understand then you're perfectly placed to tell us about it so we can create some documentation aimed at putting that right.  If one person asks a question on a forum like this we can be certain that at least a dozen others have the same question but were not bold enough to ask it.

Regards,
Chris.

[Chris Davenport]

Mod note; I've split the discussion on personas into a separate thread: http://forum.joomla.org/index.php/topic,252556.0.html

Chris.

[Squintz]

I can't seem to locate any previous tutorials on templates on this site even though some have mentioned they exist. Where can I go to learn about templates now so that I can eventually assist in this project?

[madamep]

Try:
http://www.compassdesigns.net/tutorials ... tutorials/

This is a good one to start with. Not exhaustive, but will get you into it.

Best,