Themes vs. Templates

We will attempt to provide a general description of the way XOOPS uses theme files and template files to render a site.

Why are we all confused?

In my opinion, the main source of confusion for people stems from the gap between these two things:

1. How people think it SHOULD work
2. How it actually works


Number 2 is a given and will probably not change anytime soon (those of you following on the development of Xoops 2.x know that the approach to templates & themes has changed several times and is now rather stable).

Number 1 however, varies greatly! This is mostly due to the fact that we all come from different backgrounds; Some come from phpNuke, PostNuke, and the likes. Some others, from systems like Typo3? and other 'full suites'. And then, some of you come from plain php development, where everything is done by hand, from scratch.

The second problem is the terms used in Xoops 2.x. Templates should be called "Module/Block Templates", so that they will not be confused with Theme templates, which are a different thing altogether (As indeed is shown below).


The big picture

When you first try to play with templates and themes, you notice an obvious thing:

* Every Template set consists of many files! (Last time I checked, somewhere around 36 templates for a basic system, without any modules installed)
* A theme has a relatively much lower number of files (The default theme has less than 10 files!)


Some of you are probably already saying 'ah!' at this stage.
To those who aren't yet, I will give a short example.

A theme block that displays a list of the last 10 people who registered will always display 3 things: A title at the top of the block, nickname of the person who registered, and the date they registered. Now let's not forget that we want to separate 'design' from 'content', right?

For this, we would create two files for this single block:

1. A template that defines the structure of this block, which basically is a table of nicknames + dates, line after line, until 10 rows are generated.
2. A file that takes the information generated in the previous step, and sticks it into some 'design'. This probably means putting the title of the block at the top, and beneath that, putting the list generated.


So in this example, number 1 is the block template, and number 2 is the theme. The block template is inserted *into* the theme's block code.

At this point the conclusion should be quite clear:
Templates (Block/Module templates) control the way data is displayed, while theme templates control how the data will look (most probably by assigning the various elements a class name, which would then be defined in the CSS).


And more details

Using the terms used in Xoops 2.x:
A "Template" is a piece of html code that uses pre-set variables (provided by a specific module) to expose data to the site.
A "Theme" is a special template (or set of templates) that controls the style and graphics of a Xoops site, by taking the result of the first template (Data template), and sticking it where it's supposed to be according to the Theme. This means, again, that we have two templates: A Data Template, and a Theme Template.

The Data Template is never used directly, but rather always displayed with the help of a Theme Template.

This means that unless you are going to make changes in the way modules display their data in blocks, You will only want to play with the theme templates, and not with the data templates. I personally feel that Xoops 2.x could have used slightly friendlier names, to eliminate the confusion for potential theme developers.

Additional explanations from the xoops.org forums:

from Ackbarr: Templates control the layout of a module's content, whereas themes control the overall appearance of the site.

from Herko: To be more exact then ackbarr, the theme is uploaded manually to the theme folder in your xoops root dir. To change the styles and look of your whole site, download the standard theme, and edit it offline to fit your taste. Then upload the theme files to the themes folder (naming the folderlike: themes/humbrietheme/theme.html etc.).

Templates can be edited through the template manager in your system admin menu. Clone the default template set, and edit the cloned set to fit the look and feel of your site's taste. The tempates can be edited per module.

If you are trying to edit the theme.html in your themes folder and nothing seems to be changed, be sure that you set "Update module template .html files from themes/your theme/templates directory?" to "YES" in General Settings!!