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

Table of Contents

Editing theme.php

Every theme comes with the file theme.php. However, for most themes, the file is nearly empty. The reason for that is that only things that differ from Coppermine's default behaviour needs to be described in theme.php. Things that are suppossed to work "the usual Coppermine way" are being defined in the core code - your custom theme's theme.php contains the variables and function definitions that override the identical items in the default core.

The "theme.php" file contains all the HTML templates used by the script. You can edit them, as well. When making modifications to these templates, be careful that you do not alter the lines that start with <!-- BEGIN xxx --> and <!-- END xxx -->. These lines are often used to identify the start and end of specific code blocks that the script will use to display your gallery.

Item types

Basically, there can be three types of content in theme.php (from a PHP-coder's point of view). Don't worry though - you don't have to be a coder to be capable to change your theme

The sample theme - a template to copy from

Your Coppermine installation also includes a "sample" theme directory. The "sample" theme includes each of these files but does not show up in the user selectable list of themes in your Coppermine display. Sample's theme.php also holds a copy of every themeable function and template for your reference. If you opt to use the "sample" theme to begin creating your own theme, you should follow the theme.php instructions in the "theme upgrade documentation" and begin with a blank theme.php.

To clarify: you mustn't edit the sample theme (as it will not be displayed), but copy the sections you want to see changed from it into your custom theme. Do not copy the whole content from themes/sample/theme.php into your custom theme, as this will only clutter your custom theme and will make upgrading very hard in the future. Instead, only copy the sections you want to modify from themes/sample/theme.php into themes/yourtheme/theme.php.

This being said: you mustn't start your custom theme by copying the sample theme - start with a vanilla (i.e. empty!) theme.php instead. Only use themes/sample/theme.php to copy individual sections that you want to modify into your custom theme and then modify it.

Newbies often have issues to understand what a "section" is that they need to copy from the sample theme - if you don't know much about PHP, it's sometimes hard to understand where a function definition starts and where it ends. That's why we have "wrapped" the individual sections that contain more than one line into comment blocks that try to catch your attention: a section starts with the block

/******************************************************************************
** Section <<<section_name>>> - START
******************************************************************************/
and ends with 
/******************************************************************************
** Section <<<section_name>>> - END
******************************************************************************/

where the name of the section (section_name in above example) is identical both in the start-block as well as the end-block.

The place where you insert the section you copied from the sample theme in your custom theme doesn't matter as long as you take care not to paste it within another section, but before or after a section that exists in your custom theme. As a rule of thumb, you can savely paste a section into a new line before ?> in your custom theme (themes/yourtheme/theme.php)

Method

The method behind all theme.php editing is really quite easy - just follow these simple steps:

Scope

So, what can actually be accomplished by editing theme.php? Well, the sky is the limit: only your imagination can be limited, but the scope of possible edits in theme.php is endless. However, users usually ask for the same five or six features or changes all the time. That's why we have created a page with theme examples where the most common edits to theme.php are being explained - make sure to have read those examples thoroughly before starting another request on the coppermine support board where you might just be told that you should read the docs...

We're really trying to focus your attention to this block: please read the theme examples page after having read this page.

List of items in theme.php

Item Type Description Dependancies
define('THEME_HAS_PROGRESS_GRAPHICS',1); constant Coppermine displays a "loading"-icon when the upload form is being submit to indicate that there must be no user interaction while the script is busy uplading. When this constant is set, the script will fetch the "loading"-icon from the theme's images folder (themes/yourtheme/images/loader.gif). If the constant is not set, the default loader image will be used, taken from the generic images folder. When designing a theme of your own, make sure that the loader image actually exists when setting this constant. If defined, a file named loader.gif needs to reside in the theme's images folder.
define('THEME_HAS_RATING_GRAPHICS',1); constant The location for the ratings graphics. When the constant is set, the script will be directed to the theme's images folder, i.e. themes/yourtheme/images/and look for the rating images there. If not defined (default), the rating images will be taken from the images-folder that resides in Coppermine's root folder. Graphic resources in themes → Rating images
define('THEME_HAS_COMMENT_GRAPHICS',1); constant The location for the comment management graphics. When the constant is set, the script will be directed to the theme's images folder, subfolder 'icons', i.e. themes/yourtheme/images/icons/ and look for the comment management images there. If not defined (default), the comment management images will be taken from images/icons/. Graphic resources in themes → Comment management images
define('THEME_HAS_MENU_ICONS',16); constant The location for the menu icon graphics that are being displayed if the config option "Enable menu icons" has been turned on. When the constant is set, the script will be directed to the theme's images folder, subfolder 'icons', i.e. themes/yourtheme/images/icons/ and look for the menu icon images there. If not defined (default), the menu icon images will be taken from images/icons/. Unlike most other custom theme constants, the value you assign to the constant does matter in this case: set it to the size (in pixels) that your custom icons have. The custom icons (as well as the default icons) need to be square in shape.
If you decide to use your own set of menu icons for your custom theme, it's advisable to copy the folder images/icons/ into themes/yourtheme/images/ to have a set of defaults and then start modifying your custom menu items one by one.
(v1.6.08+)You can choose to substitue only some icons. Any icons not in your theme's icons folder will be taken from the core set of icons.
define('THEME_USES_ICON_FONT',1); constant This feature will allow a theme to substitute other html code for icons rather than an <img> icon. Meant for icon font usage, such as <i class="fa fa-trash"></i>, it can also be used for other valid html such as a simple <span>Edit Image</span> for text replacement of a stand-alone icon. Available in CPG version 1.6.08 and later. If defined, a file named icons.php needs to reside in the theme's images/icons folder. [Details]
define('THEME_HAS_NAVBAR_GRAPHICS',1); constant The location for the navbar graphics ("ecard", "slideshow", "previous"/"next"). When the constant is set, the script will be directed to the theme's images folder, i.e. themes/yourtheme/images/ and look for the navbar images there. If not defined (default), the navbar images will be taken from the images-folder that resides in Coppermine's root folder. Graphic resources in themes → Image Navigation bar
define('THEME_HAS_FILM_STRIP_GRAPHIC',1); constant The location for the film strip graphics. When the constant is set, the script will be directed to the theme's images folder, i.e. themes/yourtheme/images/ and look for the film strip images (tile.gif) there. If not defined (default), the film strip images will be taken from the images-folder that resides in Coppermine's root folder. If defined, a file named tile.gif needs to reside in the theme's images folder. [Details]
define('THEME_HAS_FILM_STRIP_GRAPHICS',1);
(Mind the trailing S that makes the only difference to the above constant THEME_HAS_FILM_STRIP_GRAPHIC)		 constant The location for the film strip graphics. When the constant is set, the script will be directed to the theme's images folder, i.e. themes/yourtheme/images/ and look for the film strip images (tile1.gif for the top tile and tile2.gif for the bottom tile) there. If not defined (default), the film strip images will be taken from the images-folder that resides in Coppermine's root folder. If defined, a file named tile1.gif and a file named tile2.gif need to reside in the theme's images folder. [Details]
define('THEME_HAS_NO_SYS_MENU_BUTTONS',1); constant When present the system won't attempt to replace {BUTTONS} in the SYS_MENU template
define('THEME_HAS_NO_SUB_MENU_BUTTONS',1); constant When present the system won't attempt to replace {BUTTONS} in the SUB_MENU template
function assemble_template_buttons($template_buttons,$buttons) function Creates buttons from a template using an array of tokens this function is used in this file it needs to be declared before being called.
function addbutton(&$menu,$href_lnk,$href_title,$href_tgt,$block_id,$spacer) function Creates an array of tokens to be used with function assemble_template_buttons this function is used in this file it needs to be declared before being called.
function pageheader($section, $meta = '') function Function for writing a pageheader. The first parameter $section should not be touched. The second parameter $meta can be used to add your custom dynamic meta tags. To add static meta tags, edit template.html
function pagefooter() function Function for writing a pagefooter
function theme_javascript_head() function Function for the JavaScript inside the <head>-section
function theme_credits() function Function for the credits-section
function starttable($width = '-1', $title = '', $title_colspan = '1') function Function to start a 'standard' table
function endtable() function End standard table function starttable()
function theme_main_menu($which) function
function theme_admin_mode_menu() function
function theme_display_message_block() function Function for the theme_display_message_block. The message block (not to be confused with the admin menu) will display message carried over from one page to the other and an RSS feed from the coppermine project page for the admin. It's advisable not to change it unless you really know what you're doing. This function composes the individual sections of the block.
function theme_display_cat_list($breadcrumb, &$cat_data, $statistics) function Function to display the category list on the index page. Contains part of the core logic and hardly ever needs editing.
function theme_display_breadcrumb($breadcrumb, &$cat_data) function Function to display the breadcrumb navigation trail (often refered to as "rootline menu") that displays to the visitor in which sub structure (gallery root → category → sub-category → album) he/she is in.
function theme_display_album_list(&$alb_list, $nbAlb, $cat, $page, $total_pages) function Function to display the album list on the index page. Contains part of the core logic and hardly ever needs editing.
function theme_display_album_list_cat(&$alb_list, $nbAlb, $cat, $page, $total_pages) function Function to display first level Albums of a category
function theme_display_thumbnails(&$thumb_list, $nbThumb, $album_name, $aid, $cat, $page, $total_pages, $sort_options, $display_tabs, $mode = 'thumb', $date='') function Function to display thumbnails both in album view as well as category view and meta albums
function theme_display_film_strip(&$thumb_list, $nbThumb, $album_name, $aid, $cat, $pos, $sort_options, $mode = 'thumb', $date='') function Display film strip Only taken into account if Show film strip is enabled in config.
function theme_no_img_to_display($album_name) function Function that composes the output if an album is empty or a particular item is inaccessible for whatever reason (doesn't exist or missing permissions)
function theme_display_image($nav_menu, $picture, $votes, $pic_info, $comments, $film_strip) function Core layout of the intermediate image display screen (displayimage.php).
function theme_html_picinfo(&$info) function Template to compose the individual lines of the pic info table underneath the intermediate image Pic info section needs to be expanded
function theme_html_picture() function Displays a picture or any other record that resides in coppermine's database for individual view.
function theme_html_img_nav_menu() function
function theme_html_rating_box() function
function theme_html_comments($pid) function Displays comments for a specific picture
function theme_slideshow() function
function theme_display_fullsize_pic() function Display the full size image
function theme_vanity() function
function theme_display_bar($actualValue = 0, maxValue = '100', maxBarSizeInPixels = '400', textColor = 'black', textShadowColor = '', textUnit = '', leftBar = 'red', rightBar = '') function Display a bar graph
function theme_page_title($section) function Creates the title tag for each page. For the sake of search engine friendliness, the dynamic part $section should come first
$template_sys_menu variable Template for sys_menu
$template_sub_menu variable Template for sub_menu
$template_sys_menu_spacer variable Delimiter between sys menu items (in many themes, :: is being used)
$template_sys_menu_button variable Edit this to add/change CSS classes for the sys-menu links.
Default content is
  <!-- BEGIN {BLOCK_ID} -->
        <a href="{HREF_TGT}" title="{HREF_TITLE}">{HREF_LNK}</a>
        {SPACER}
  <!-- END {BLOCK_ID} -->
$template_sub_menu_spacer variable Delimiter between sub menu items. By default, it's the same delimiter that is being used for the sys menu.
$template_sub_menu_button variable Edit this to add/change CSS classes for the menu-menu links. By default, the definition for the sys-menu is being taken into account.
$template_gallery_admin_menu variable HTML template for gallery admin menu
$template_user_admin_menu variable HTML template for user admin menu, i.e. the additional menu the non-admin user sees if he is logged in and allowed to have a personal gallery (permission for this is being assigned on the groups control panel).
$template_cat_list variable HTML template for the category list
$template_breadcrumb variable HTML template for the breadcrumb (i.e. the path that indicates where the visitor actually is in terms of the logical category/album structure)
$template_album_list variable HTML template for the album list
$template_film_strip variable HTML template for filmstrip display on the intermediate image page (displayimage.php)
$template_album_list_cat variable HTML template for the album list
$template_album_admin_menu variable HTML template for the ALBUM admin menu displayed in the album list, i.e. the menu items (buttons) that are being displayed next to each album thumbnail if the logged in user is the owner of that album. Usually, this is the case for the admin.
$template_thumb_view_title_row variable HTML template for title row of the thumbnail view (album title + sort options). This is the place to remove the sort options if you don't want them displayed.
$template_fav_thumb_view_title_row variable HTML template for title row of the fav thumbnail view (album title + download).
$template_thumbnail_view variable HTML template for thumbnails display function theme_display_thumbnails uses variable and defines placeholder tokens {THUMB}, {CAPTION}, {ADMIN_MENU} and {TABS}
$template_no_img_to_display variable HTML template for the thumbnail view when there is no picture to show. If your gallery requires visitors to log in to actually view the pictures, you may encourage them to do so by coming up with custom content within this theme section. Placeholder token {TEXT} being populated and variable used in function theme_no_img_to_display
$template_user_list_info_box variable HTML template for the USER info box in the user list view
$template_img_navbar variable HTML template for the image navigation bar: the navigation at the top of the intermediate image view that let's you go to the thumbnail view, expands/collapses the pic info section, starts the slideshow, contains links to ecard, allows you to report a file to the admin and displays the link to the previous and next image in the album the visitor is currently in.
$template_display_media variable HTML template for intermediate image display. This is the place where layout changes of the intermediate image in relation to the title and description should be added. function theme_html_picture populates the placeholder tokens {IMAGE}, {ADMIN_MENU}, {TITLE} and {CAPTION} and uses the variable
$template_image_rating variable HTML template for the image rating box
$template_image_comments variable HTML template for the display of comments
$template_add_your_comment variable HTML template for the input form for comments
$template_cpg_die variable HTML template used by the cpg_die function, used to display error messages of any kind to the visitor
$template_msg_box variable HTML template used by the msg_box function that displays messages to the visitor at the top of the screen (usually giving feedback for actions that the visitor has made on a previous screen).
$template_ecard variable HTML template for e-cards
$template_ecard_plaintext variable plain-text template for e-cards (as fallback for clients that can't display html-formatted mails)
$template_report variable HTML template for report
$template_report_plaintext variable plain-text template for reports (as fallback for clients that can't display html-formatted mails)
$template_report_comment variable HTML template for displaying a reported comment
$template_report_comment_email variable plain-text template for reports (as fallback for clients that can't display html-formatted mails)
$template_tab_display variable Template used for tabbed display
$template_vanity variable Template used for Vanity Footer
$template_sidebar variable HTML template for sidebar
$template_zipfile_plaintext variable plain-text template for optional readme text file to be added to archives when using the zip download of favorites

Examples

A list of modification examples that are often requested can be found in the section theme examples.

Summary

Understanding the process to edit theme.php is really important if you want to create a custom theme, so it's mandatory to be familar with what has been explained on this page:

To edit a particular functionality of a theme, take a look at themes/yourtheme/theme.php and search for the section that you want to see changed. If that section exists, edit it as you see fit. If that section does not exist in your custom theme, copy the corresponding section (and only that section) from themes/sample/theme.php into a new line before ?> of the file themes/yourtheme/theme.php. Then start editing the code you just pasted in.