Composr Tutorial: Theme Lifecycle

Written by Chris Graham (ocProducts)

If you've developed a theme, you'll need to keep it updated as new Composr versions come out.
Where possible we try and automate this, but automation is imperfect.

This tutorial will explain how theme overrides get made, the consequences of overrides, and how to keep them in sync.

Table of contents

Composr Tutorial: Theme Lifecycle

The start of an override

Imagine you have a new empty theme. Nothing is overridden in it, it is just an empty shell built on top of the default theme.

A note about override chains

All themes inherit any non-overridden files direct from the default theme (there is no system for chaining themes together into a complex inheritance system). It is possible for files to be overridden within the default theme, if you need an override to apply to many themes but don't want to individually override it into each theme. It is also possible to do some really fancy tricks with Tempcode, to simulate chained themes, if you've got a programmer-mindset. For the purpose of simplicity in this tutorial we'll assume nothing is overridden within the default theme.

Now, you go and edit the global.css within your theme. At this point global.css has been overridden within your theme, and you have diverged from the global.css shipped with Composr and upgraded between releases. The override was necessary to make your customisations, but simultaneously you have become responsible for maintaining your own version of it.

It is useful to understand what is happening when you make an override, in terms of the files.

The default theme's global.css is at themes/default/css/global.css.
Let's imagine your theme is called example. The CSS would be overridden to themes/example/css_custom/global.css when you make your initial changes.

Additionally, at this point of initial override, the original themes/default/css/global.css (i.e. without any of your changes) is copied to themes/example/css_custom/global.css.editfrom. This file is useful as a future point of reference, and we'll come back to it.

If you create your theme using the Theme Wizard, the process is similar, but happening automatically. The Theme Wizard overrides any CSS file that defines colours, which includes global.css.

This override process is exactly the same for templates (including JavaScript templates), and CSS files.

The template cache

Composr never actually directly serves CSS files to the visitor web browsers. First the CSS files are compiled with Tempcode, and then they are minified. The Tempcode process allows Composr to properly tie-in theme images, language string references, colour references, and to separately compile out the mobile and desktop versions of the CSS, among other things.

Templates are obviously not served direct to the visitor web browser either.

In both cases compiled/cached files are stored in the themes/example/templates_cached/EN directory (assuming English).

It is important that you never try and directly edit files under the template cache as they will be overridden arbitrarily in the future.

Further edits

Each subsequent change you make to an overridden file will save a backup.

Continuing our global.css example, editing it would create themes/example/css_custom/global.css.(current-unix-timestamp) as a backup.
The current-unix-timestamp is just a number (the number of seconds since 1980). Higher numbers represent more recent backups.

After an upgrade

We will make sporadic changes to the default theme files between releases, typically to fix bugs, or workaround issues in particular web browsers.
However, as discussed these may not automatically turn up in your own overrides – so necessary bug fixes may be missing from your own theme.
We work to improve our automated theme upgrade process, so hopefully this will get better over time, but it's a complex matter and will never be perfect.

It is often better to go through the process by hand, or to go over by hand to perfect what the automatic results haven't done quite right.

This is where the auto-created .editfrom files are useful…

First install a diff tool on your own desktop machine such as WinMerge. Beyond Compare (cross platform, commercial), DiffMerge on Mac, and Kompare on Linux are similar.

Then download the themes directory from your server, to your own desktop machine.

Comparing these files:

themes/example/css_custom/global.css.editfrom
themes/default/css/global.css

…would show all changes made in the default theme since you first made your override (i.e. official changes).

Comparing these files:

themes/example/css_custom/global.css.editfrom
themes/example/css_custom/global.css

…would show all the changes you directly made within your own theme (i.e. your changes).

Comparing these files:

themes/default/css/global.css
themes/example/css_custom/global.css

…would show all the differences between the default theme and your own theme (i.e. the changes you directly made, any the changes made in the default theme since you first made your override).

Therefore using a diff tool you can locate what changes you need to make back into your custom theme, then upload your updated file(s).

It is easier to do this on your desktop than trying to do it all directly through a web server / Composr's normal theme-editing user interface.

Here is some documentation for Winmerge that explains how to use these kinds of tools (they're all very similar) a bit better:
Quick start - WinMerge 2.16 Manual

Our Themeing compatibility changes tool

On the Composr website you will find a tool for showing all the changes made across Composr releases. This is very useful as an alternative to you using the .editfrom files within your own diff tool.

Feedback

Please rate this tutorial:

Have a suggestion? Report an issue on the tracker.