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

Table of Contents

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:

The themes "Classic", "Fruity", "Igames", "Mac OX X" and "Project VII" that existed in cpg1.4.x have been removed from the cpg1.5.x package. They are available as separate downloads instead - refer to the section user-contributed themes for details.

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 :

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. If you're looking for examples how to modify your custom theme, you should read the page "Theme examples" thoroughly, as it contains solutions ready for copy'n paste that allow you to modify your custom theme dramatically, especially as far as additional content is concerned. Pay attention as well to the sections that deal with the "copyright-disclaimer in footer" and the section "Dynamic (PHP-driven) content".