Creating your custom theme

Rename your theme first

To create a new theme, the best solution is to use an existing one as its copy template. To do that, make a copy of the folder of the theme you want to use as a basis. Then edit the "template.html", "style.css" and "theme.php" files and replace all occurences of "themes/old_theme_dir" with "themes/new_theme_dir" in order for the links to point to the correct place.
Avoid using spaces and special chars in your custom theme name - only use alphanumerals and the underscore (_).

Also keep in mind that despite this file being located in the "themes/your_theme_dir" directory, it must be coded as if it was in the main directory of the coppermine installation. For example, in order to display an image, you must use <img src="themes/theme_dir/images/image.gif" alt=""/> and not just <img src="images/image.gif" alt=""/>. The same principle applies for the "theme.php" file.

It is strongly recommended to rename your custom theme as suggested above, even if you only plan to accomplish minor changes to a default theme that coppermine comes with. The reason is quite simple: when upgrading at a later stage, you will not run into issues (e.g. accidentally overwrite your customized theme with an updated default theme).

Tipps & tricks

If you're not sure how to go about creating your own theme, you could also have a look at the download section of the coppermine homepage: there are many user-contributed themes available for download that can be previewed on the coppermine demo page.

While you're in the process of creating or testing a new theme, you might not want your theme to be displayed to visitors of your site, but you (as the coppermine admin) may want to still be able to preview your theme. To do that, simply add theme=your_theme_name to the url in your browser.

Using WYSIWYG-editors

It is strongly recommended not to use a WYSIWYG-editor at all to edit Coppermine files. The coppermine dev team is aware that it might seem easier for beginners to use those graphical editors. However, they have some major drawbacks:

• Some editors (mostly MS Frontpage) are notorious for "beautifying" the code in a manner that renders embedded PHP code invalid. Subsequently, if you use a WYSIWYG-editor to edit theme.php, the file may get corrupt (i.e. un-usable)
• Graphical editors tend to create deprecated, invalid, proprietary HTML. You have more control if you use a plain text editor instead.
• You don't learn anything. Sooner or later, you will want to do something your precious WYSIWYG-editor isn't capable to do. Now what? You have always used the editor to do your work - you don't understand HTML. When using a plain text editor, the learning curve may be steep, but it's much more entertaining.

Editing template.html

The file template.html is the core file of each theme: it can only contain HTML/CSS/JavaScript code (no PHP!) plus some placeholder tokens that will get replaced with content when the theme is being parsed (i.e. when the HTML output of a gallery page is being generated). Template.html determines the overall layout of your gallery pages. Use it to make your gallery match the overall look of your entire website.

Template tokens

When editing the "template.html" file do not remove the elements between {} - these are the placeholders used by the script. Think of those items in curly brackets as placeholders that will be replaced later with dynamic content when your template is being parsed. You can move the placeholder tokens around to obtain different layouts. However, there are some limitations - refer to the explanation of the core token {GALLERY}.

List of tokens in template.html

Token	Description	Default position	Needed?	Dependancies
{LANG_DIR}	Language direction Possible values are LTR and RTL. Should not be changed or modified at all.	pageheader	mandatory	Filled by Coppermine, depending on the orientation of the language the end user has chosen
{CHARSET}	Character set Determines the character set used - filling the HTML tag <meta http-equiv="Content-Type" content="text/html; charset={CHARSET}" />. Do not change unless you really know what you're doing.	pageheader	mandatory	Filled by Coppermine, depending on the encoding the admin has chosen in config.
{TITLE}	Page Title The page title that is mainly taken into account by search engines. The human visitor sees the title tag in the browser window.	pageheader	mandatory	Title tag is being composed in the individual coppermine core file (e.g. displayimage.php, thumbnails.php etc.), handed over to the pageheader function.
{META}	Meta tags Meta tags that depend on the dynamic content of a page are being inserted here. Currently, Coppermine uses the keywords meta tag (<meta name="keywords" content="DYNAMIC CONTENT HERE" />) and the refresh meta tag (<meta http-equiv="refresh" content="5; URL=REDIRECTION_PAGE" />). If you want to add other meta tags (e.g. author meta data like <meta name="author" content="Firstname Lastname" />), do not replace the token, but add your custom meta tags below the {META}-token.	pageheader	mandatory	Populated dynamically by the script, e.g. for meta keywords based on file keywords or for redirection for status change screens.
{JAVASCRIPT}	JavaScript This token has been added in cpg1.5.x It will be replaced with <script type="text/javascript" src="scripts.js"></script> (which is mandatory to have for Coppermine to work properly). You mustn't remove this tag, but you can add your custom JavaScript code beneath it (in a new line).	pageheader	mandatory	n/a
{CUSTOM_HEADER}	Custom Header If the corresponding option has been set in config, this token will be replaced with the output that your custom header generates. If you don't use the custom header feature, you can remove the {CUSTOM_HEADER}-token from your template, but it's advisable to leave it in place if you decide to use the feature later.	pageheader	optional	Path to custom header include set up in config
{GAL_NAME}	Gallery name Will be replaced with the gallery name you set up in config when the template is being parsed. You might want to remove this token, especially if you already have a banner in your theme that displays your gallery name.	pageheader	optional	Gallery name set in config
{GAL_DESCRIPTION}	Gallery description Will be replaced with the gallery description you set up in config when the template is being parsed. You might want to remove this token, especially if you already have a banner in your theme that displays your gallery name.	pageheader	optional	Gallery description set in config
{SYS_MENU}	System menu Determines the position of the first level menu the end user will see on your page (the one that contains the login/logout link). Even if you want to get rid of the menu or parts of it, do not remove the {SYS_MENU} token itself, but remove the menu items you don't want displayed by editing theme.php instead.	pageheader	mandatory	Login/Logout link: Status of user (admin/registered user/guest). Upload-link: Permission of current user to upload (determined in groups panel). Register-link: Allow new user registrations enabled/disabled in config. FAQ-link: Display FAQ enabled/disabled in config.
{SUB_MENU}	Sub menu Determines the position of the second level menu the end user will see on your page (the one that contains the links "Album list" / "Last uploads" / "Last comments" / "Most viewed" / "Top rated" / "My Favorites" / "By Date" / "Search"). Even if you want to get rid of the menu or parts of it, do not remove the {SUB_MENU} token itself, but remove the menu items you don't want displayed by editing theme.php instead.	pageheader	mandatory	n/a
{LANGUAGE_SELECT_FLAGS}	Language selector (flags) Will display a row of flags representing the languages available for the end user to choose if corresponding config setting is enabled.	none	optional	Display language flags enabled/disabled in config.
{LANGUAGE_SELECT_LIST}	Language selector (list) Will display a dropdown list of languages available for the end user to choose if corresponding config setting is enabled.	none	optional	Display language list enabled/disabled in config.
{THEME_SELECT_LIST}	Theme selector (list) Will display a dropdown list of themes available for the end user to choose if corresponding config setting is enabled.	none	optional	Display theme list enabled/disabled in config.
{ADMIN_MENU}	Admin menu Displays the admin menu.	pageheader	mandatory	Admin must be logged in. Admin controls mustn't be hidden.
{MESSAGE_BLOCK}	Message block	pageheader	mandatory
{GALLERY}	Gallery Special token that will later be replaced with the actual Coppermine output. In the above introduction to the template tokens we said that you can move around the tokens inside the template.html file. However, you have to understand that the {GALLERY}-token is a special placeholder: think of it more as a separator than an actual placeholder token. When the template is being parsed, the {GALLERY}-token will be replaced with the actual core component of the gallery. Other placeholders tokens in curly braces that come before the {GALLERY} token are being handled by the pageheader function; placeholder tokens that come after the {GALLERY}-token are being handled by the pagefooter function. Therefor, you have to keep in mind that you can freely move tokens around in template.html as long as you don't reverse the position of the token you move and the {GALLERY}-token.	n/a	mandatory
{CUSTOM_FOOTER}	Custom Footer If the corresponding option has been set in config, this token will be replaced with the output that your custom footer generates. If you don't use the custom footer feature, you can remove the {CUSTOM_FOOTER}-token from your template, but it's advisable to leave it in place if you decide to use the feature later.	pagefooter	optional	Path to custom footer include set up in config
{VANITY}	Vanity block If your custom theme is defined as valid theme and you have enabled the corresponding option in config, the {VANITY}-placeholder will be replaced with mini-banners that link to PHP.net, mysql.com and the HTML and CSS validators of the W3C.	pagefooter	optional	Display the vanity block on themes that are defined as XHTML and CSS compliant enabled in config. Theme defined XHTML and CSS compliant in theme.php
{CREDITS}	Credits Will display the "Powered by Coppermine" tag on your page. If the token is being removed, the copyright-disclaimer will be displayed as part of the {GALLERY}-block. If you want to edit (or even delete) the "Powered by Coppermine" tag, read Copyright-disclaimer in footer	pagefooter	optional	Credits section defined in theme.php
{SOCIAL_BOOKMARKS}	Social bookmarks Will display the social bookmark icons if the correspdonding option in the config is enabled for at least one social bookmark service.	none	optional	Config page > Display social bookmarks icons

Be careful not to delete the {JAVASCRIPT}-token - this javascript is necessary for the full-size pop-ups and other functions related to JavaScript.

Favicon

Coppermine comes with a favicon file that resides in the gallery root folder. There is reference to it in all themes that come with coppermine out of the box. You're welcome to use a favicon file of your own and change the reference to it in your custom theme. To accomplish this, edit themes/your_custom_theme/template.html, find <link rel="shortcut icon" href="favicon.ico" /> and edit as you see fit.

Modifying colors & design

To modify the colors, fonts, font sizes, etc... used by the script, you should edit the "style.css" stylesheet whenever possible. For example, if you want to increase or decrease the size of the fonts you can simply modify the line with : table { font-size: 12px; }. Most of the font sizes used by the script are defined as a percentage of this size.

Editing theme.php

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

• Definitions of constants
  Think of constants as general switches that can be set once while the script is run

  Example:
  define('THEME_IS_XHTML10_TRANSITIONAL',1);

• Definition of variables
  Variables can be manipulated (i.e. changed) during runtime. The vast majority of items that can reside in theme.php are variables. Variable names always start with a $-sign.

  Example:
  $template_sys_menu = <<<EOT
            {BUTTONS}
  EOT;

• Definition of functions
  Functions are the most powerfull mechanisms that can reside in theme.php, as they allow great flexibility and are re-usable. They start with the word function, followed by the function name and the parameters in brackets and a curly bracket that actually determines the start of the function. The function definition usually contains several lines of code and ends with a closing curly bracket.

  Example:
  function endtable()
  {
      echo <<<EOT
  </table>
  <!-- End standard table -->
  
  EOT;
  }

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.	-
define('THEME_HAS_SIDEBAR_GRAPHICS',1);	constant	The location for the sidebar graphics that compose the tree menu. When the constant is set, the script will be directed to the theme's images folder, subfolder 'sidebar', i.e. themes/yourtheme/images/sidebar/ and look for the sidebar images there. If not defined (default), the sidebar images will be taken from images/sidebar/
define('THEME_IS_XHTML10_TRANSITIONAL',1);	constant	If theme is defined as XHTML10_TRANSITIONAL the VANITY footer will be enabled if the theme has a {VANITY} token in its template.html. Don't enable this if you have modified the code! By setting this constant you claim that your custom theme is valid. To actually enable or disable the display of the vanity footer, enable or disable "Display the vanity block on themes that are defined as XHTML and CSS compliant" in Coppermine's config.	-
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.
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.
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.
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 theme_display_breadcrumb($breadcrumb, &$cat_data)	function
function theme_display_album_list(&$alb_list, $nbAlb, $cat, $page, $total_pages)	function
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 theme_display_film_strip(&$thumb_list, $nbThumb, $album_name, $aid, $cat, $pos, $sort_options, $mode = 'thumb', $date='')	function	Display film strip
function theme_no_img_to_display($album_name)	function
function theme_display_image($nav_menu, $picture, $votes, $pic_info, $comments, $film_strip)	function
function theme_html_picinfo(&$info)	function
function theme_html_picture()	function	Displays a picture
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