How to find out which template is responsible for what output

If you're having trouble figuring out which template is being used to generate
what output, a handy trick is to go to Themes -> Modify Config and enable
"Show template filenames in HTML comments".

When you navigate through your site, you'll get the filename of each
template that's used in HTML comments, so you can View HTML Source
on any page and see where each piece of the page comes from.
[don't forget to remove the option once you've finished your design :-)]

In general, you'll have the following types of templates :

1) page template - located in themes/<yourtheme>/pages/, this template
gives the overall layout of the page.

Examples :
- default.xt : the default page template
- admin.xt : the page template used for any admin functions
- <module>.xt : the page template to be used for a particular module (if
you want to override the default page template for that module)
- <whatever>.xt : a page template specified via module settings etc.
(for instance each publication type in articles can have its own page 
template, if you specify one in Articles -> Modify Config)

2) block layout templates - located in themes/<yourtheme>/blocks/, this
template specifies the common layout to be used by blocks, i.e. how
its title and content will be displayed.

You can specify the template to use for each block group, so that
each block in that group will use the same template, or you can
assign a specific template for an individual block as well.

Note that this template does not say how the *content* of the
block itself will be generated - it only gives the overall layout.

Examples :
- default.xt : the default template for blocks
- right.xt : a default layout for blocks on the right, as specified for the
blockgroup "right" in Blocks -> View Groups
- top.xt : another layout for blocks on the top
- <whatever>.xt : another layout for a specific block group or block

3) module function templates - located in 
themes/<yourtheme>/modules/<module>/, those templates specify how the
output of a particular module function should be displayed.

Examples :
- user-<function>.xt : template for the user function <function>
- admin-<function>.xt : template for the admin function <function>
- user-<function>-<template>.xt : specific sub-template used in
  the user function <function> (e.g. each pubtype in articles will
  use its own user-display-<pubtype>.xt and user-summary-<pubtype>.xt
  template)

If a theme doesn't have a particular template for a module function,
Xaraya will look for a default template in modules/<module>/xartemplates/.
Those templates will be called user-<function>.xd, admin-<function>.xd
and so on... (Note the .xd extension here, instead of the .xt extension).

In the default themes, most module function templates will *not* have
a specific template for each theme. If you want to add one, *copy* the
file modules/<module>/xartemplates/user-<function>.xd to
themes/<yourtheme>/modules/<module>/user-<function>.xt and
adapt as you wish.

4) block content templates - located in
themes/<yourtheme>/modules/<module>/blocks/ those templates
will specify how the *content* of a particular block should be generated.

Examples :
- base/blocks/sidemenu.xt : theme-specific template for the base menu block

Again, if there is no theme-specific template for a block, Xaraya will
look for a default one in modules/<module>/xartemplates/blocks/<block>.xd

Some blocks may use several templates, e.g. one for the block configuration
and one or more for the block display. You should check the templates in the 
modules/<module>/xartemplates/blocks/ directory to see which ones are
in use.

5) included templates - located in */includes/ (either theme-specific or the
default in the modules/<module>/xartemplates/includes/ directory), those
are included as part of other templates, e.g. to provide some common 
navigation, menu or whatever for different templates.

6) other templates - since templates can be included via code as well, there
might be some other templates used depending on the module or block code.
If you're wondering where a template comes from, the best way is to enable
that option "Show template filenames..." mentioned above and/or browse
through the modules/<module>/xartemplates/ and themes/<yourtheme>/
directories.

For more information on templates, see RFC 10 - Blocklayout Specification.

HTH,

Mike.