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

# Converting cpg1.4.x themes to cpg1.5.x

To make your custom made theme from cpg1.4.x work with cpg1.5.x, you will need to make some changes. Remember to back up your original files, so you can go back to a working version in case something goes wrong with the modifications.

The files to be edited would be in the particular folder of the theme in the themes folder. For example, the files for the "classic" theme could be found in themes/classic

- Edit style.css
- Edit template.html
- Edit theme.php
- Validation

## Edit style.css

For all changes below, edit themes/your_custom_theme/style.css

### Define pseudo-classes :link, :visited, :focus, :active

Before applying this fix, make sure that your stylesheet doesn't contain definitions for the pseudo-classes already. If it doesn't contain those classes

Find:

    a:hover {

Add before it (in a new line):

    a:link {
            color: #0033CC;
            text-decoration: none;
    }

    a:visited {
            color: #0033CC;
            text-decoration: none;
    }

    a:focus {
            color: #0033CC;
            text-decoration: none;
    }

    a:active {
            color: #0033CC;
            text-decoration: none;
    }

and edit the colors and format as you see fit.

### Bold table headers

Find:

    .tableh1 {

and add after it:

            font-weight:bold;

Find:

    .tableh1_compact {

and add after it:

            font-weight:bold;

Find:

    .tableh2_compact {

and add after it:

            font-weight:bold;

Find:

    .alblink a {

and add before it (into a new line):

    .alblink {
            font-weight:bold;
    }

Find:

    .catlink {

and add after it:

            font-weight:bold;

### Edit class «navmenu»

Find:

    .navmenu a {
            position: relative;

and replace with:

    .navmenu a {

### Fix background repetition for «admin_menu»

Find:

    .admin_menu {

and add after it:

    background-repeat:repeat-x;

### Add classes «admin_float» & «admin_menu_wrapper»

Find:

    #admin_menu_anim {

and add before it (into a new line):

    .admin_float {
            float:left;
            margin-left: 1px;
            margin-right: 1px;
            margin-top: 1px;
            margin-bottom: 1px;
    }

    .admin_menu_wrapper {
            width:100%;
    }

### Add pseudo-classes for image links

Find:

    .image {

and add before it (into a new line):

    /* pseudo-classes for image links */
    a:link .image{
            border-style:solid;
            border-width:1px;
            border-color:#000000;
            margin:2px;
    }

    a:visited .image{
            border-style:solid;
            border-width:1px;
            border-color:#840084;
            margin:2px;
    }

    a:focus .image{
            border-style:solid;
            border-width:1px;
            border-color:#000000;
            margin:2px;
    }

    a:hover .image{
            border-style:solid;
            border-width:1px;
            border-color:#0033CC;
            margin:2px;
    }

    a:active .image{
            border-style:solid;
            border-width:1px;
            border-color:#000000;
            margin:2px;
    }

Edit the colors and attributes as you see fit. This is supposed to show which thumbnails have already been clicked. The important bit being the attributes of the pseudo-class :visited; they have to differ from the other pseudo-classes.

### Add the classes «pic_title», «pic_caption»

Find:

    #vanity a {

and add before it (into a new line):

    .pic_title {
            color: #000000;
            font-size: 120%;
            font-family: Arial, Helvetica, sans-serif;
            font-weight:bold;
            text-align : center;
            padding-top:0px;
            padding-bottom:0px;
            margin-top:0px;
            margin-bottom:0px;
            line-height:1.0em;
    }

    .pic_caption {
            color: #000000;
            font-size: 100%;
            font-family: Arial, Helvetica, sans-serif;
            font-weight:bold;
            text-align : center;
            padding-top:0px;
            padding-bottom:0px;
            margin-top:0px;
            margin-bottom:0px;
            line-height:1.0em;
    }

### Add the classes «cpg_message_info», «cpg_message_success», «cpg_message_warning», «cpg_message_error», «cpg_message_validation»

Find:

    #vanity a {

and add before it (into a new line):

    .cpg_message_info, .cpg_message_success, .cpg_message_warning, .cpg_message_error, .cpg_message_validation {
        border: 1px solid;
        margin: 10px 0px;
        padding:15px 10px 15px 50px;
        background-repeat: no-repeat;
        background-position: 10px center;
    }
    .cpg_message_info {
        color: #00529B;
        background-color: #BDE5F8;
        background-image: url('../../images/message/info.png');
    }
    .cpg_message_success {
        color: #4F8A10;
        background-color: #DFF2BF;
        background-image: url('../../images/message/ok.png');
    }
    .cpg_message_warning {
        color: #9F6000;
        background-color: #FEEFB3;
        background-image: url('../../images/message/warning.png');
    }
    .cpg_message_error {
        color: #D8000C;
        background-color: #FFBABA;
        background-image: url('../../images/message/stop.png');
    }
    .cpg_message_validation {
        color: #D63301;
        background-color: #FFCCBA;
        background-image: url('../../images/message/error.png');
    }

### Add the «greybox»-class to your stylesheet

In cpg1.5.x, the jquery plugin Greybox Redux is used to display the help-popups embedeed into the page. You need to add the corresponding CSS color definition into your stylesheet.

Add at the end of your stylesheet (into a new line):

    #GB_window {
      background-color: #FFFFFF;
      border: 5px solid #AAAAAA;
    }

In the definition for `#GB_window`, change the background attribute to match your theme's background color. Change the border attribute to match your theme's border color.
If you're not sure what the background color of your theme is or what border color to use, take a look at your theme's color definitions for the class `maintable`.

The other styles of the greybox are being defined in `css/coppermine.css`. The definitions in that file should be left alone - don't edit that file unless you really know what you're doing.

### Remove the vanity styles

The styles for the vanity icons has been moved into the overall CSS file (located at `css/coppermine.css`).

Find

    #v_php {float:left;background-image:url(../../images/powered-php.gif);}
    #v_php:hover {background-image:url(../../images/h_powered-php.gif);}
    #v_mysql {float:left;background-image:url(../../images/powered-mysql.gif);}
    #v_mysql:hover  {background-image:url(../../images/h_powered-mysql.gif);}
    #v_xhtml {float:right;background-image:url(../../images/valid-xhtml10.gif);}
    #v_xhtml:hover {background-image:url(../../images/h_valid-xhtml10.gif);}
    #v_css {float:right;background-image:url(../../images/valid-css.gif);}
    #v_css:hover{background-image:url(../../images/h_valid-css.gif);}

and delete from your custom stylesheet.

### Remove the class «comment_button»

The class "comment_button" didn't differ much from the class "button" and has been removed. It won't hurt to leave the class definition in your custom stylesheet, it just won't have any impact. If you like to clean your stylesheet, remove all references to the class.

### Remove the class «tableh1_compact»

The class "tableh1_compact" didn't differ much from the class "tableh1" and has been removed, as it was hardly ever used for the purpose it was originally intended. It won't hurt to leave the class definition in your custom stylesheet, it just won't have any impact. If you like to clean your stylesheet, remove all references to the class.

### Remove the class «tableh2_compact»

The class "tableh2_compact" didn't differ much from the class "tableh2" and has been removed, as it was hardly ever used for the purpose it was originally intended. It won't hurt to leave the class definition in your custom stylesheet, it just won't have any impact. If you like to clean your stylesheet, remove all references to the class.

### Remove the class «tableb_compact»

The class "tableb_compact" didn't differ much from the class "tableb" and has been removed, as it was hardly ever used for the purpose it was originally intended. It won't hurt to leave the class definition in your custom stylesheet, it just won't have any impact. If you like to clean your stylesheet, remove all references to the class.

## Edit template.html

There have been only minor changes to this file. Open `themes/your_theme/template.html` with a plain text editor and edit as suggested below:

### Replace the call for script.js

Find:

    <script type="text/javascript" src="scripts.js"></script>

and replace with:

    {JAVASCRIPT}

Failing to apply this change to your custom theme will make your theme work no longer (see details on the `{JAVASCRIPT}`-placeholder-token).

### Add the call for the global stylesheet

To reduce the weight of an individual style sheet, the global CSS definitions that are the same for all Coppermine themes have been moved from `themes/yourtheme/style.css` into a global CSS file located at `css/coppermine.css`. The new stylesheet `css/coppermine.css` should not be edited at all. To upgrade your custom theme designed for cpg1.4.x for the new cpg1.5.x, you need to add the call to the new stylesheet to your theme's template.html:

Find:

    <link rel="stylesheet" href="themes/YOUR_THEME/style.css" type="text/css">

and add before it into a new line:

    <link rel="stylesheet" href="css/coppermine.css" type="text/css" />

### Add {MESSAGE_BLOCK} token

Insert

    {MESSAGE_BLOCK}

anywhere before the `{GALLERY}`-token, preferably right after the menu section. This new placeholder will display messages both to the admin as well as the end user. It should be visible in the upper part of the screen without the need to scroll down, see details on the `{MESSAGE_BLOCK}`-placeholder-token.

### Add {CREDITS} token

Insert

    {CREDITS}

anywhere after the `{GALLERY}`-token, preferably at the very end of the file, above the `</body>`-tag. This new placeholder can display the copyright notice of your gallery and (ideally) the Coppermine disclaimer.
If you don't insert that token, there will be no error message and the default Credits will be displayed, see details on the `{CREDITS}`-placeholder-token.

### Add {SOCIAL_BOOKMARKS} token

Insert the placeholder tag `{SOCIAL_BOOKMARKS}` anywhere you want the social bookmarks see displayed (they will only display if you enable the corresponding config option). For theme designers who plan to publish their theme it's recommended to add that token no matter what. If you design your custom theme only for your personal use and don't plan to publish your custom theme to others, you're free to ommit this token if you don't need to display social bookmarks. For details, see List of tokens in template.html → {SOCIAL_BOOKMARKS}.

### Remove {VANITY} token

In older versions of Coppermine, all themes used to contain the placeholder token `{VANITY}`. This token used to be replaced with a reference to the w3c validation pages and php.net and mysql.com only if the theme was defined as standards compliant and only if the corresponding option in coppermine's config used to be checked (by default, the option used to be unchecked). This has changed in cpg1.5.x: if your custom theme's template.html contains the token `{VANITY}`, the corresponding output will be displayed no matter what, as the option in coppermine's config has been dropped as well as the definition inside the theme.

Therefore, if you use a theme that was designed for cpg1.4.x, the vanity display will show after the upgrade to cpg1.5.x even if you had the display turned off before. If this bothers you, just remove the template placeholder token `{VANITY}` (→ details).

### Remove {LANGUAGE_SELECT_FLAGS} token

In older versions of Coppermine, all themes used to contain the placeholder token `{LANGUAGE_SELECT_FLAGS}`. This token used to be replaced with a list of flags representing the available languages and only if the corresponding option in coppermine's config used to be checked (by default, the option used to be unchecked). This has changed in cpg1.5.x: if your custom theme's template.html contains the token `{LANGUAGE_SELECT_FLAGS}`, the corresponding output will be displayed no matter what, as the option in coppermine's config has been dropped.

Therefore, if you use a theme that was designed for cpg1.4.x, the language selector by flag will show after the upgrade to cpg1.5.x even if you had the display turned off before. If this bothers you, just remove the template placeholder token `{LANGUAGE_SELECT_FLAGS}`.

### Remove {LANGUAGE_SELECT_LIST} token

In older versions of Coppermine, all themes used to contain the placeholder token `{LANGUAGE_SELECT_LIST}`. This token used to be replaced with a list of the available languages and only if the corresponding option in coppermine's config used to be checked (by default, the option used to be unchecked). This has changed in cpg1.5.x: if your custom theme's template.html contains the token `{LANGUAGE_SELECT_LIST}`, the corresponding output will be displayed no matter what, as the option in coppermine's config has been dropped.

Therefore, if you use a theme that was designed for cpg1.4.x, the language selector by list will show after the upgrade to cpg1.5.x even if you had the display turned off before. If this bothers you, just remove the template placeholder token `{LANGUAGE_SELECT_LIST}`.

### Remove {THEME_SELECT_LIST} token

In older versions of Coppermine, all themes used to contain the placeholder token `{THEME_SELECT_LIST}`. This token used to be replaced with a list of the available themes and only if the corresponding option in coppermine's config used to be checked (by default, the option used to be unchecked). This has changed in cpg1.5.x: if your custom theme's template.html contains the token `{THEME_SELECT_LIST}`, the corresponding output will be displayed no matter what, as the option in coppermine's config has been dropped.

Therefore, if you use a theme that was designed for cpg1.4.x, the theme selector will show after the upgrade to cpg1.5.x even if you had the display turned off before. If this bothers you, just remove the template placeholder token `{THEME_SELECT_LIST}`.

## Edit theme.php

Many notable things have happened that will influence your modifications to your theme.php.

As this section is in progress most, we'll have to finish it later - TBC

- ...

## Validation Methodology

Now that you have a functioning "style.css", "template.html" and "theme.php" you should verify that it is generating valid output.

- Suggestions to help you bring the theme you are editing up to XHTML 1.0 Transitional HTML
  - All ampersands (&) that form part of a URL are to be coded '`&amp;`'. There are quite a few of these in the functions of theme.php.
  - All images to have the 'alt' attribute, and be closed '`/>`'.
  - All meta tags should be closed '`/>`'
  - All `<hr>` and `<br>` tags should be closed `<hr />``<br />`
  - All background images/colors to be changed to CSS or style attributes. This depends on the layout.
  - Any existing tags or attributes in uppercase (such as onClick) to be changed to lowercase.
- Save all your open files and upload them to your webserver; test-drive both as admin and as "regular" user.
- Use the following methodology to confirm that your theme generates valid XHTML 1.0 Transitional HTML.
  Each of the following pages needs to be validated as an anonymous user, registered user, and in admin mode:
  - index.php
  - thumbnails.php
  - displayimage.php
  - search.php
  - emailed HTML E-card.
  To find help to validate your custom theme, review the section Developer documentation → Tools recommended by the devs → Web development