# Coppermine Photo Gallery v1.5.x: Documentation and Manual

# Themes

Coppermine comes with a powerful engine that allows you to create your own theme, giving your gallery a unique look that matches the overall layout of your entire site. Other applications call them "skins" or "templates", well call them "themes".

There is a (constantly growing) number of user-contributed themes that can be previewed and downloaded from the Coppermine web site.

## Themes that come with Coppermine

The Coppermine package comes with some pre-made themes:

- Classic
  The default theme with white background and a horizontal menu
- Eyeball
  A theme with a dark background and a horizontal menu that expands for user interaction features
- Fruity
  A colorful theme with a vertical menu on the left
- Hardwired
  A theme with a dark background and a smallish font size that works well for narrow space and smaller resolutions. Comes with two horizontal menus
- IGames
  A dark theme with 3D-effects and a horizontal menu
- Mac OX X
  A theme with light background and an expanding horizontal menu that resembles the look of a Mac
- Project VII
  A theme with white background featuring a horizontal expanding menu
- Rainy Day
  A theme with dark background and rounded edges
- Sample
  The sample theme would look identical to the classic theme. It will not be displayed using the theme selector - it is just meant as a template to copy from when creating or modifying your own theme.
- Waterdrop
  A theme with a light background and a "conventional" horizontal menu

## Upgrading your custom theme

To upgrade an existing custom theme from cpg1.4.x to version 1.5.x, read the theme upgrade documentation.

If you are upgrading from cpg1.3.x to cpg1.5.x, you will have to perform your theme upgrade in two steps: first, you need to upgrade your custom theme from cpg1.3.x to cpg1.4.x and then on from cpg1.4.x to cpg1.5.x

You only have to upgrade your custom theme when upgrading between major versions (e.g. from cpg1.3.x to cpg1.4.x or from cpg1.4.x to cpg1.5.x), as from one major version to the next, the theming engine is subject to changes. When only upgrading from minor versions to the next (e.g. from cpg1.5.x to cpg1.5.y), you don't have to update your custom theme.

The core themes that come with Coppermine packages don't need to be updated, as they should be replaced during the upgrade and therefore will contain all needed changes. However: if you have based your custom theme on one of the core themes that come with coppermine (e.g. the classic theme), pay attention to possible changes. As suggested below, it's advisable to rename your custom theme to make sure that it doesn't accidentally get overwritten when upgrading.

## Content of a theme

Coppermine themes are stored in the "themes" directory, each consists of 3 primary files :

- "template.html" the main template in plain HTML.
- "style.css" the stylesheet associated with the template
- "theme.php" the PHP theme file

Additionally, there usually is a folder named "images" that resides within the theme folder (themes/theme_name/images/) that contains the images used by the particular theme (logos, bullets, backgrounds and other graphical resources needed).

## How the theme engine works

When a Coppermine page is being parsed, the core code will call theme functions. If those functions exist in your custom theme, they will be taken into account. If a particular function does not exist in your custom theme, the core function will be used. The core functions (the default theme behaviour if you want to put it that way) reside in includes/themes.inc.php. Therefore, you mustn't edit includes/themes.inc.php, under no circumstances, as all your changes will be lost when upgrading in the future. Everything that possibly could be accomplished by editing include/themes.inc.php can be accomplished by editing themes/yourtheme/theme.php as well - stuff defined in your custom theme will take precedence over the core theme functions.

## What's next?

There are step-by-step instructions provided in the section "Creating your custom theme" that you should read for details. Pay attention as well to the sections that deal with the "copyright-disclaimer in footer" and the section "Dynamic (PHP-driven) content".