Customising themes

From kiwitrees 3.0.1 there are new simpler ways to modify the themes that control the look and feel of kiwitrees.

In previous versions you have always been able to modify the theme files to change specific elements of the display. But that is always risky as at each upgrade your changes would be over-written. At the very least you would need to re-do your changes, and at worst you might not have a record of what they were!

For those reasons the best advice was always to create a completely new theme by copying an existing theme folder, changing its name (both the folder and other references in the file ‘theme.php’, then modifying the files to suit your needs. When an upgrade is installed your personal theme is not touched. You would however still need to know the differences between your theme and the one you copied, so you can then adjust yours to match changes in the standard version. This is still the best way to proceed if the changes you want are significant.

But now a third option is available which makes small changes to a standard theme easier to do, is not touched during an upgrade, and makes checking for new changes painless.

All that is required to modify a theme is to add one or more new files, named mystyle.css, mytheme.php, myfooter.php, or myheader.php, as indicated in the image at the top of this page. For most requirements just creating a mystyle.css file with a few style changes will be all that is required.

Detailed Requirements

Naming

1. Your custom style sheet MUST be named mystyle.css and your custom theme.php file MUST be named mytheme.php.
2. Your custom header and footer files can have any name as you will reference them in your mytheme.php (see below).

Customising the style sheet

click to enlarge

1. This file only needs to contain the css that you want to add or modify. This file is loaded after the standard style sheet so will over-rule any css from the standard files.
2. Note that this method cannot be used to change css that is embedded in core kiwitrees system files (technically “inline css”) as the css “cascading” rules mean those styles are always the dominant ones. Those would require either core file hacks or JavaScript to change them, and are therefore not covered by this FAQ. In general kiwitrees does not use inline css but there may be a few examples from earlier still remaining.
3. The example shown here (right) simply changes the basic font style and colour for the site, plus a small change to the padding in buttons. The first line is just an optional comment.

Customising theme.php

click to enlarge

1. This file contains some variables that you might want to change, such as chart dimensions, statistics map colours, and a few generic icons.
2. This file only needs to contain the items  that you want to add or modify. This file is loaded after the standard file so will over-rule any settings from it.
3. If you want to create your own header.php or footer.php you must reference these in this mytheme.php file as shown in the example here.
4. The example (right) includes some required and some optional parts:
   • It must be a ‘.php’ file; and the first line must be ‘<?php’
   • The second line is an optional comment.
   • The four lines starting with ‘if (!defined(……‘ are required. Do not leave them out. The theme will work without but will not be adequately protected from malicious access.
   • The next two lines define your replacement header and footer files. They are NOT required unless you do want different files to the standard ones (see below).

Custom header and / or footer files

1. These can be given any name you choose, providing you refer to the same names in the references added to your mytheme.php file (see above).
2. These files must be complete replacements for the standard versions. You cannot just include selected parts you want to change.
3. Take a copy of the original file, rename and change it to suit your needs. Technical knowledge of PHP and kiwitrees code is required for this.
4. If you do want to make small changes they are best done using the ‘Custom JavaScript’ module. For more details see this FAQ page.

General comments

1. Editing and creation of any of these files must be done in a text editor that can:
   • Save the file in UTF8 coding
   • Does not add a ‘byte order mark’ (BOM) to the file.
   • These requirements mean don’t use a basic (e.g. MS Notepad) text editor.