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

Table of Contents

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}, which is not actually a placeholder, but rather a separator between the content served by the pageheader and pagefooter functions.

Important

There are some tokens that are optional, i.e. you can safely remove them from template.html if you don't need the feature (s) the placeholders correspond to.

Be careful not to delete the {JAVASCRIPT}-token - this javascript is necessary for the full-size pop-ups and other functions related to JavaScript. If you remove it, you probably won't notice the difference in the first place, but you definitely mustn't remove it or your gallery will act up.

Take a look at the column "Needed?" in the list of tokens in template.html - the ones labelled as "optional" can safely be removed without any issues (except that the corresponding feature will of course not work any longer).
A good example is the token {GAL_DESCRIPTION} - it will basically just output whatever you entered as gallery description on the config page. If you don't need the description to show on each and every coppermine-driven page, then just remove the corresponding token from template.html.

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.
The language selector list will look like this:
Choose your language:
Of course (unlike this example) it will actually do something when a new selection is made: the gallery language will change.
Back in cpg1.4.x, the token used to reside in all themes that came with coppermine out of the box and there used to be an option in coppermine's config to determine wether you wanted the language selector to appear or not. With cpg1.5.x the selector has been dropped from the themes and the option from the config panel, so you explicitely have to add the token to your template.html file to see the selector. By default, Coppermine does not display the language selector. The reason for the decision of the coppermine dev team to drop the selector out of the box is the fact that Coppermine's built-in mechanisms to detect a visitor's prefered language works so well that there is hardly ever a need to offer a language selector to your visitors. Only in the rare cases when you're convinced that your visitor's browser language probably is not the language they would prefer to see your gallery in should you provide a language selector.
This is for example the case for Luxembourg: the Grand Duchy of Luxembourg is a small country in Europe with three official languages:
  • French
  • German
  • Luxembourgish
With less then half a million inhabitants (and probably far less people actuall speaking Luxembourgish each day) the major browser creators don't provide a browser with Luxembourgish as prefered language. Subsequently, if your gallery catters for a Luxembourgian audience, it might make sense to add a language selector by editing themes/yourtheme/template.html and adding somewhere (preferably near the top of the screen) that allows your visitors to actually see the gallery's navigation in Luxembourgish (provided that there is a language file in Luxembourgish of course).
none optional -
{LANGUAGE_SELECT_LIST} Language selector (list)
Will display a dropdown list of languages available for the end user to choose.
The language selector list will look like this:
Of course (unlike this example) it will actually do something when a new selection is made: the gallery language will change.
It's merely a matter of taste if you use the language selector with flags or the one that displays a dropdown list of available languages, so basically what has been said above about {LANGUAGE_SELECT_FLAGS} applies to {LANGUAGE_SELECT_LIST} as well.
none optional
{THEME_SELECT_LIST} Theme selector (list)
Will display a dropdown list of themes available for the end user to choose.
none optional
{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. Therefore, 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 valid, 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 none
{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