Customising Pixaria with themes

Pixaria Gallery includes support for customising the look and feel of the script with interface themes.

What are themes?

Themes are directories of images, HTML templates and JavaScript files located in the 'resources/themes/' directory of your installation. HTML template support is provided by the inclusion of the Smarty template engine in Pixaria Gallery. All HTML pages and e-mail messages are based on Smarty templates which makes it easy to modify your installation by creating your own versions of built in template files.

The structure of a theme directory is as follows:

What do themes allow me to change?

Theme support in Pixaria only allows you to customise the front end of the Pixaria Gallery software. The back-end themes, located in '/resources/templates_admin/', should NOT be edited as this is very likely to break the script!

Where are theme files stored?

Theme support differs from PopPhoto Studio, and many other PHP scripts, because the script template system is based on default templates (located in 'resources/templates_default') which are always used unless the user has provided any custom HTML template files in a custom theme directory.

As an example, the default theme that comes with Pixaria (which is called Advance) doesn't include any template files. This means that the script defaults to using the built in 'default' template files instead.

The reason for this approach is so that a working theme directory only needs to contain template files that you want to be different from the defaults. Thus if you only want to change the site's CSS files, you will only need to include CSS template files in the template. This makes upgrading easier because you always know which of your custom theme templates are different from the defaults.

How do I make a custom theme?

To make a custom theme, all you need to do is to make a copy of either the default 'Advance' or 'Evolve' themes (give the directory a new name e.g. 'mytheme') and then select it from the drop down menu in the appearance control panel.

You can then customise any of the front end pages by simply making a copy of the relevant template file from the 'templates_default' directory and putting it into the corresponding location in your customised theme directory.

For example, to make a customised version of the default template file 'index.tpl', make a copy of index.tpl, put it into your custom theme directory 'mytheme/templates/index.tpl'. If Smarty caching is turned on you will need to flush the template cache before you can see changes to your custom theme.

Another example might be to change an e-mail message, for example, the message sent to the admin when someone logs into the site. To do this, make a copy of the template file 'resources/templates_defult/email.templates/login.notify.tpl' and put it into '/resources/themes/mytheme/email.templates/login.notify.tpl'.

How do I edit template files

Theme template files in Pixaria (files with names inding in .tpl) are plain text files containing either HTML or CSS (Cascading Style Sheet code) interspersed with Smarty tags which are enclosed in curly braces {}.

If you want to create your own theme template files then you will need to use a text editor that won't change or alter the code in such a way that it breaks the template. I recommend using either BBEdit, Coda or Dreamweaver.

I can't see changes to my templates

This is likely because template caching is turned on on your installation. Pixaria caches template files to speed up the performance of the script which means that if caching is on and you change a template, you won't be able to see those changes when you try to view them.

Caching can be turned off in the admin control panel or if you just want to clear out the cache for a quick change, you can do this by clicking the link 'Flush Smarty Cache' at the bottom of the admin navigation.

More information about Smarty

Smarty is a very powerful and easy to use template engine designed for both programmers and non programmers. Full details of how to use Smarty can be found on the Smarty homepage.

The documentation is excellent and provides lots of examples of how to use useful concepts like sections and loops.

Building future proof, standards based templates

From Pixaria version 1.2, templates should conform to a set of rules and layout guidelines in order to maximise accessibility and XHTML compliance. More information can be found on this in the documentation entry on layout specifications.

Go back to contents

Created: Wednesday, May 10, 2006
Last edited: Monday, May 7, 2007