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. If you're not familiar with this, read up The sample theme - a template to copy from; this entire page assumes that you have read and understood that section.

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

Additional menu items

This section explains how to add more menu items to your custom menu. If you only need one extra menu item (not two or three of them), your best option is to use the config options "Custom menu link name"/"Custom menu link URL", as that method doesn't require you to edit files and is therefore less complicated. If you're happy to have just one extra menu item, there's no need to read on on this page - instead, follow the links above that explain the config options. If you're writing a plugin of your own and not a custom theme, you should read up "Adding a Button to Coppermine", as the method to add a menu item using a plugin differs from the method to add a menu items when designing a theme of your own.
You're still reading on, so this means you need more custom menu items or you need more granular control over your menu items.
The way Coppermine creates menu items in cpg1.5.x is in a sort-of in-between-state: both the classic way that Coppermine menu items were created in previous versions before cpg1.5.x is supported as well as more advanced methods that allow dynamic, expanding menus. That's why the method to add new menu items differs depending on what type of menu creation technique your custom theme is using, i.e. on what core theme it is based upon. There are plans to change this again in future versions, but for now, we'll have to live with what is there.
The sections underneath seem to be very long, but don't be afraid: you don't have to read and understand all of it, but only the stuff that applies for your theme, as this section actually is separated into different sub-sections that explain how menus work for different types of themes.
To be enable you to understand what we'll be talking about below, you need to understand that there are the following menus types in Coppermine:

Entire menu structure defined in one block

A typical example for the entire menu structure defined in one variable block is the theme "Hardwired". To figure out wether your custom theme is using the same technique, open themes/yourtheme/theme.php with a plain-text editor and find the line that starts with $template_sys_menu = for the sys menu and/or $template_sub_menu = for the sub menu. Determine what menu you want to edit - in this example, we'll be talking about the sys menu, but everything that will be said here will apply for the sub menu as well.
Inside the sys menu, take a look at the content of the definition: if your custom theme falls into the category "Entire menu structure defined in one block", then you should find one or more lines of code inside the sys menu that corresponds to each menu item that currently exists in your custom menu when looking at your gallery's output. For the hardwired theme, the code looks like this: , but it could just as well look like this for another theme: (which is what we'll use in this example for brevity).
As you can see, each menu item is wrapped into a comment construct like
<!-- BEGIN menu_item_name -->
and
<!-- END menu_item_name -->
Although this looks like straightforward HTML comments that won't display in the browser, they are there for a reason: with them, Coppermine determines if a particular menu item should be processed. The Coppermine script itself (which is written in PHP and therefore isn't "blind" as far as HTML comments are concerned) is searching for those comment blocks (with the keywords being BEGIN and END followed by the menu item name, which is a keyword as well in this process). Inside each code block that corresponds to a menu item you can see placeholder tokens as well in curly braces that will be replaced with actual content when the menu is actually processed - more on that later.
With this being said: if you plan to remove a particular menu item, only remove the the HTML markup between the comments, but leave the comments around them intact; if you plan to remove the home button for example (which is something you wouldn't want to do in "real life"), find
<!-- BEGIN home -->
                            <li>
                                    <a href="{HOME_TGT}" title="{HOME_TITLE}">{HOME_LNK}</a>
                            </li>
<!-- END home -->
and replace with
<!-- BEGIN home -->
<!-- END home -->
To actually add a menu item of your own, you will have to add a custom block of code into the right spot, i.e. you have to place it correctly as far as nesting is concerned: it needs to reside between two existing menu item and not inside them. In other words, the code for your custom menu item needs to reside after a comment line that ends a menu item record (e.g. <!-- END contact -->) and before another code line that starts the next menu item record (e.g. <!-- BEGIN my_gallery -->). In our example, we want to add a link to the menu that points to our forum. The menu item is meant to show up between the contact form link and the next menu item. To accomplish this, find
    <!-- END contact -->
and add after it (into a line of it's own)
    <!-- BEGIN custom_forum_link -->
                            <li>
                                    <a href="../forum/" title="go to the forum">Forum</a>
                            </li>
    <!-- END custom_forum_link -->
Save your changes and upload them from your local copy to your webserver if applicable - you should see the changes immediately. If you're happy with what you got, you can stop reading on - you just figured out how to add a custom menu item to your theme.
If you want more features (i.e. if the link is not meant to show up no matter what, but only if a certain condition applies, e.g. if the visitor is logged in) or if you want to fully internationalize the link to catter for visitors from different countried with different languages, read on - we'll try to explain how to accomplish all that.
In order to understand what is going on, we'll have to take another look "under the hood" of Coppermine to see how it works: the "regular" menu items contain (as suggested above) placeholder tokens that get populated somewhere else.
tbc...