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.
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
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.
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)
The method behind all theme.php editing is really quite easy - just follow these simple steps:
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...
| 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_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. |
|
| 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 |
A list of modification examples that are often requested can be found in the section theme examples.
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: