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:

• Curve
  
  A theme with a light background and a cascaded horizontal menu that expands using CSS only. The new default theme for cpg1.5.x that has been inspired by the new theme for SMF 2.0.

  This theme currently uses workarounds to display correctly in Internet Explorer 6 and 7.
  To remove IE6 support,
  - delete <!-- Begin IE6 support --> ... <!-- End IE6 support --> from template.html
  - delete the file csshover3.htc from the theme folder.
  To remove support for IE7,
  - delete <!-- Begin IE7 support --> ... <!-- End IE7 support --> from template.html
  - remove all lines with /* IE7 */ from style.css,
  - uncomment the line /* min-height: 95px; */ in style.css.

• Eyeball
  
  A theme with a dark background and a horizontal menu that expands for user interaction features
• 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
• Rainy Day
  
  A theme with dark background and rounded edges
• Sample
  The sample theme would look identical to the water_drop 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

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 :

• "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".