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.
- Create a copy
Browse the local coppermine gallery copy on your client, navigate to the themes folder (your_coppermine_folder/themes/), right-click on the folder name that represents the theme you want to base your custom theme on (in this example, we will use the classic theme, so we will use your_coppermine_folder/themes/classic/), select "copy" from the context menu. Then paste the content of the clipboard into the themes folder; a folder (named "Copy of classic" or similar) will turn up.
- Rename the folder
Right-click on the newly created folder (your_coppermine_folder/themes/Copy of classic/) and select " rename" from the context menu. Choose a unique theme name - in this example, we will use "my_theme" (resulting in the folder to be renamed to your_coppermine_folder/themes/my_theme/).
Keep in mind that we will upload the theme to your webserver later - you will have to make sure to properly use capitalization: on Windows-driven clients, capitalization does not matter, so there is no difference between "my_theme" and "My_theme". Most webservers are Linux-driven though, where capitalization does matter (there is a difference between "my_theme" and "My_theme"). To be safe it is recommended to use lower case to stay out of harms way.
- Edit the files to reflect the theme name
Use a plain text editor (in this example, we will use notepad.exe), open your_coppermine_folder/themes/my_theme/template.html. Find "themes/classic" and replace with "themes/my_theme" (may exist in the file several times, so make sure to replace all occurrences of "themes/classic" with "themes/my_theme"). Save your changes. Then do the same thing for the files theme.php and style.css.
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.
- http://yoursite.tld/coppermine/index.php?theme=your_theme_name will show the coppermine index page, using your theme
- http://yoursite.tld/coppermine/thumbnails.php?album=1&theme=your_theme_name will show the thumbnail view of album 1, using your theme
- http://yoursite.tld/coppermine/?theme=xxx will reset your view back to the theme you chose as your default theme in coppermine config
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.
If you're not sure what editor to use, take a look at the list of editors on the page tools recommended by the devs.
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.
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.
Alternatively, just replace the favicon that ships with the theme you use with your custom favicon file.
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.
Advanced Steps
There are some advanced steps that you should follow - they are being described in the sections