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

Table of Contents

Theme examples

This page contains a summary of modification examples that frequently are being requested on the Coppermine support board. The wording differs as well as the extra items that users want to add. Most users are looking for information how to add adverts (like Google's adsense) in particular places.

We assume that you have read and understood the basics about themes in Coppermine: by now, you should know that

This page will only explain what sections of theme.php need editing to accomplish particular extra features. You need to read up how to copy those sections first.

Summary

Additional content

This section is meant to how to add additional content to particular places of Coppermine's output. Most users want to display adverts as additional content, like Google's adsense or Adbrite (as seen on Yahoo and ebay).

As examples, we will only add a short sentence like "your custom content" or similar. You can replace that of course with any HTML/JavaScript as you see fit. This documentation will not cover how to actually add the HTM markup for those ad-programs nor will it explain how that works. There are much better places on the web to get an impression how those advert technlogies work and how to implement the basics.

Additional content on the thumbnail page

Modifications that will have an impact on the display of the thumbnail pages.

Extra row between thumbnail rows

This modification will modify the separator between the table rows that compose the thumbnail screen: a row will be added where you can add textual content or a horizontal banner ad.

Edit themes/yourtheme/theme.php using a plain-text editor, find $template_thumbnail_view and modify as suggested below. If $template_thumbnail_view doesn't exist in your custom theme, copy that section from the sample theme first.
Inside the variable definition for $template_thumbnail_view, find
<!-- BEGIN row_separator -->
            </tr>
            <tr>
    <!-- END row_separator -->
and replace with
<!-- BEGIN row_separator -->
            </tr>
            <tr>
                <td colspan="{$CONFIG['thumbcols']}">
                    your custom content
                </td>
            </tr>
            <tr>
    <!-- END row_separator -->

Extra table cell on each thumbnail page

This is a more advanced mod that will require more editing. What it does though is more subtle: it doesn't add an entire row or column to the thumbnail page, but replaces one of the thumbnails on each thumbnail page with a cell with your custom content (e.g. your advert).

Edit themes/yourtheme/theme.php using a plain-text editor, find $template_thumbnail_view and modify as suggested below. If $template_thumbnail_view doesn't exist in your custom theme, copy that section from the sample theme first.
In the variable definition for $template_thumbnail_view, find
<!-- END spacer -->
and add after it (into a new line of it's own)
<!-- BEGIN advert -->
            <td valign="top" class="thumbnails" width ="{CELL_WIDTH}" align="center">
                    <table width="100%" cellpadding="0" cellspacing="0">
                            <tr>
                                    <td align="center">
    									Your custom content here
                                    </td>
                            </tr>
                    </table>
            </td>
    <!-- END advert -->
Next, you'll need to edit the function definition for the function named theme_display_thumbnails. In themes/yourtheme/theme.php, find function theme_display_thumbnails and modify as suggested below. If that particular section doesn't exist in your custom theme, copy the function definition from the sample theme. To accomplish that, copy everything starting at (and including)
/******************************************************************************
    ** Section <<<theme_display_thumbnails>>> - START
    ******************************************************************************/
untill (and including)
/******************************************************************************
    ** Section <<<theme_display_thumbnails>>> - END
    ******************************************************************************/
into a new line before ?> of themes/yourtheme/theme.php
In that function definition, find
    static $spacer = '';
and add into a new line after it
    static $advert = '';

Next, find
        $spacer = template_extract_block($template_thumbnail_view, 'spacer');
and add after it into a new line
        $advert = template_extract_block($template_thumbnail_view, 'advert');

After that, find
    $thumbcols = $CONFIG['thumbcols'];
and add after that into a new line
    $thumbrows = $CONFIG['thumbrows'];

Now, find
    foreach($thumb_list as $thumb) {
and add before it in a line of it's own
    // Start modification "random table cell ad"
        $number_of_thumbs = count($thumb_list);
        $advert_position = rand(0,$number_of_thumbs-1);

Scroll down and find
        echo template_eval($thumb_cell, $params);
and replace that line with
        // Add the advert cell 
            if (defined('DISPLAY_ADS_FOR_META_ALBUMS') || is_numeric($aid) == TRUE) {
            	$display_advert = 1;
            } else {
            	$display_advert = 0;
            }
            if ($i == $advert_position && $mode == 'thumb' && $display_advert == 1) {
    	        if ($number_of_thumbs < $thumbcols * $thumbrows) { // We have room to display
    	                                                           // the extra advert cell
    	        	//print_r($thumb_list);
    	        	$thumb_list[($number_of_thumbs+1)] = $thumb;
    	        	echo template_eval($advert, $params);
    		    } else { // We do not have room for the extra advert cell, 
    		             // so we'll have to replace one (i.e. drop the 
    		             // content of the thumb that should usually reside 
    		             // here without the ad)
    		    	echo template_eval($advert, $params);
    		    }
            } else {
            	echo template_eval($thumb_cell, $params);
            }

You have to make sure to apply this mod thoroughly. It's advisable to back up your custom theme.php first in case anything should go wrong, so that you can safely go back just in case.


Additional content on the intermediate-image pages (displayimage.php)

The output of displayimage.php - the page that shows the intermediate-sized image embedded into your site's layout is the page that your visitors will pay most attention to, as you managed to attract their attention on previous pages, so they decided to click on a thumbnail that sent them to the intermediate imaghe view. On this page, you can display adverts easily and you will almost certainly get a good click-through-rate, but you need to pay attention: the site already contains a lot of information - cluttering it more with even more content can be dangerous, as the visitor might feel overwhelmed and leave.

Directly next to the intermediate image

The instructions apply for all extra content that should be applied above, below or next to (at the right or left) of your actual intermediate image that is embedded into the page. Keep in mind though that the place at the right or left may already be small, depending on the screen resolution of your visitor and the size of your intermediate image, so it's advisable to add your extra content at the top or bottom rather.

Edit themes/yourtheme/theme.php, find the variable definition for $template_display_media and edit as suggested below. If that definition doesn't exist in your custom theme, copy it first from the sample theme, then edit accordingly.
The section that needs changing is the table that wraps the template token {IMAGE}, so you need to edit
           <tr>
                <td align="center" class="display_media" nowrap="nowrap">
                        <table cellspacing="2" cellpadding="0" >
                                <tr>
                                        <td align="center" style="{SLIDESHOW_STYLE}">
                                                {IMAGE}
                                        </td>
                                </tr>
                        </table>
                </td>
            </tr>
Just modify the inner table as you see fit. To add some content at the bottom, you would have to change those lines to
           <tr>
                <td align="center" class="display_media" nowrap="nowrap">
                        <table cellspacing="2" cellpadding="0" >
                                <tr>
                                        <td align="center" style="{SLIDESHOW_STYLE}">
                                                {IMAGE}
                                        </td>
                                        <td align="center" style="{SLIDESHOW_STYLE}">
                                                Your custom content
                                        </td>
                                </tr>
                        </table>
                </td>
            </tr>

Directly next to the film strip

The instructions apply for all extra content that should be applied above or below of your film strip that is displayed on the page if the corresponding option "Show film strip" is enabled in Coppermine's config.

Edit themes/yourtheme/theme.php, find the function definition for theme_display_film_strip and edit as suggested below. If that definition doesn't exist in your custom theme, copy it first from the sample theme, then edit accordingly.
The section that needs changing is at the end where the template is finally evaluated. Find
    echo '<div id="filmstrip">';
    starttable($CONFIG['picture_table_width']);
    echo template_eval($template, $params);
    endtable();
    echo '</div>';
To output extra content right above the film strip, you would need to change that code snippet to
    echo '<div id="filmstrip">';
    echo <<< EOT
    Your custom content
EOT;
    starttable($CONFIG['picture_table_width']);
    echo template_eval($template, $params);
    endtable();
    echo '</div>';

Additional content on the full-size pop-up

The pop-up that shows up if you click on the intermediate image can contain additional content (e.g. adverts) as well. However, you need to make up your mind if there will be enough space on the screen of your site visitors to ad even more content. In other words: only display additional content on the full-size pop-up if your full-size images have a resolution that is smaller than your visitor's minimum monitor resolution. Since you can't tell for sure what size they will have, you can still consider 800 x 600 pixels to be the minimum. Remember as well that with smartphones and other mobile devices that have internet acccess recently you can't even be sure that there will be resolutions that are even smaller.

If you must have an advert on the fullsize pop-up, make sure to use a text advert only and not a banner. This being said as a warning, here's how to add custom content to the full-size pop-up:

Edit themes/yourtheme/theme.php, find
// Display the full size image
function theme_display_fullsize_pic()
and edit that function definition as suggested below. If this piece of code doesn't exist in your custom theme, copy the function definition from the sample theme, starting at
/******************************************************************************
** Section <<<theme_display_fullsize_pic>>> - START
******************************************************************************/
and ending with
/******************************************************************************
** Section <<<theme_display_fullsize_pic>>> - END
******************************************************************************/
To add the Adsense code or any other custom content, add it as you see fit in the HTML section of above mentioned code, e.g. right after the closing tag of the div container.
In this particular case, you'll have to circumvent another issue: the window size of the full-size pic is being calculated based on the dimensions of the pic. Therefore, if you add content to the window, you'll have to make sure that the dimensions of the window increase by the space the advert "eats up". The dimensions of the window are being calculated in the function function theme_html_picture(). The same method used above applies: search your custom theme (themes/yourtheme/theme.php) for that function definition. If it exists there, edit it as suggested below. If it doesn't, copy the function defintion from themes/sample/theme.php into a new line before ?> of themes/yourtheme/theme.php.
The piece of code that actually needs editing is
            $winsizeX = $CURRENT_PIC_DATA['pwidth'] + $CONFIG['fullsize_padding_x'];  //the +'s are the mysterious FF and IE paddings
            $winsizeY = $CURRENT_PIC_DATA['pheight'] + $CONFIG['fullsize_padding_y']; //the +'s are the mysterious FF and IE paddings
Edit it as you see fit - you will have to increase the variable's value by the amount of space (in pixels) that your ads need. As an example: if you decide to add your adsense code at the top of the full-size pop-up and it eats up 200 pixels, change
            $winsizeX = $CURRENT_PIC_DATA['pwidth'] + $CONFIG['fullsize_padding_x'];  //the +'s are the mysterious FF and IE paddings
            $winsizeY = $CURRENT_PIC_DATA['pheight'] + $CONFIG['fullsize_padding_y']; //the +'s are the mysterious FF and IE paddings
to
            $winsizeX = $CURRENT_PIC_DATA['pwidth'] + $CONFIG['fullsize_padding_x'];  //the +'s are the mysterious FF and IE paddings
            $winsizeY = $CURRENT_PIC_DATA['pheight'] + $CONFIG['fullsize_padding_y'] + 200; //the +'s are the mysterious FF and IE paddings