Introduction to creating a Theme

"Theme" is the name for all the files that are responsible for the display of the overall layout. You can have several themes in you system for various function. For example you can let users decide on which layout they prefer or you can display the backend differently from the frontend.

Moreover the theme is the central folder for all your module template changes, your custom plugins and your custom classes. Whenever you change a module template store it in /themes/<theme name>/templates/modules/<module name>/ - thus your changes are save in case you update the module. If you make a change in any other folder but the theme folder, you are doing something wrong.

Overview

You should know that there are some different important files that belong to every theme. First of all: Themes are stored in the /themes/ folder and their name is the same as the folders name. So if you have a theme called "Bubblehead" you have a folder /themes/Bubblehead/

In this folder are several other folders:

• /themes/Bubblehead/images/ - directory containing theme images.
• /themes/Bubblehead/style/ - directory containing theme style sheets
• /themes/Bubblehead/plugins/ - directory containing theme specific template plugins
• /themes/Bubblehead/lang/ - directory containing theme language files
• /themes/Bubblehead/templates/ - directory containing templates that contain the markup of the theme

Within the templates folder the directory structure will, typically contain:

• /themes/Bubblehead/templates/blocks/ - directory containing block templates
• /themes/Bubblehead/templates/modules/ - directory containing page templates used to render pages with a specific page template assignment
• /themes/Bubblehead/templates/modules/<other directories> - directories containing template overrides for modules
• /themes/Bubblehead/templates/config/ - the heart of the theme. directory containing the ini files that define what templates are used to render what parts of all output, what theme variables exist, what palettes are available, etc.

Important Files

Every theme consists of at least 3 files

/themes/Bubblehead/version.php

The version.php in the main directory is the ID of a theme. There you find the basic information Postnuke needs to know - like the name, the author aso.
The content of this file looks like this:

You have to set a proper theme name - that is the name of your theme's folder. The displayname on the other hand is the name as it should appear for the admin. Most other entries are selfexplaining but you should know that it is here the you can set whether or not this is a theme that could be use for the administration only ($themeversion['admin']), that it is a normal user theme ($themeversion['user'] ) or that it is a systeme theme ($themeversion['system']) - system themes are themes that for example render you site as a RSS feed or that you can use as printer view.

/themes/Bubblehead/templates/master.htm

The next most important file is master.htm - This is the layout template itself. It's basically a normal HTML page only with no content. Instead you have calls for variables and plugins that fetch the contents for the system and display them in the right place.

/themes/Bubblehead/templates/config/pageconfigurations.ini

The 3rd most important file is Bubblehead/templates/config/pageconfigurations.ini - This file contains all the settings for Postnuke to know when to use which template or more precise - when to use which configuration.
This is a basic example:

It tells Postnuke to use the settings in the master.ini whenever a page is called. That is due to the fact that [master] is like a wildcard. If you want to use a different ini you can simply add more entries:

This file tells Postnuke to use the content of the admin.ini whenever admin functions are called. It tells Postnuke to also use the master.ini when the module Pagesetter is called but when the module is Pagesetter, the type is user, the function is viewpub and the tid is 1 it's supposed to use pgarticle.ini

Thus it's possible to use different .ini files for different functions - you could even use a special .ini for only one set of parameters.

But what are these other strange .ini-files? Most importantly they contain the name of the layout template to use. This is a common master.ini:

This file tells Postnuke to use the master.htm when something is called the the pageconfigurations.ini decides to redirect to this specific .ini. It also sets three types of blocks: left, right and center - they can each be connected to a template stored in /themes/Bubblehead/templates/blocks/ - So if you call

in your master.htm the system will pick /themes/Bubblehead/templates/blocks/leftblocks.htm to render the left blocks.

With this technique you can have as many different block zones and block types as you like, you can have a different layout for every part of your site and it's all portable as all the settings are stored in .ini files. Copy the theme to your server and it will all work as expected.

Technical Background

Postnuke's Templating System is based on Smarty∞ which allows the separation of application logic and display logic. Smarty has only a limited set of programming functions so that designers can't break the functionality of the system.

Although Smarty is known as a "Template Engine", it would be more accurately described as a "Template/Presentation Framework." That is, it provides the programmer and template designer with a wealth of tools to automate tasks commonly dealt with at the presentation layer of an application. I stress the word Framework because Smarty is not a simple tag-replacing template engine. Although it can be used for such a simple purpose, its focus is on quick and painless development and deployment of your application, while maintaining high-performance, scalability, security and future growth.
--Is Smarty right for me?∞