Coppermine Photo Gallery v1.4.1: Documentation and Manual

About Coppermine

Coppermine Photo Gallery is a picture gallery script. Users can upload pictures with a web browser (thumbnails are created on the fly), rate pictures, add comments and send e-cards. The admins can manage the galleries and batch add pictures that have been uploaded on the server by FTP. Support for multimedia files has been added recently.

Images are stored in albums and albums can be grouped by categories. The script supports multiple users and each user can possibly have its own set of albums.

The script also supports multiple languages and has a theme system. It uses PHP, a MySQL database and the GD library (version 1.x or 2.x) or ImageMagick to make the thumbnails. An install script makes the installation fast and simple.

Table of contents

• 0. Beta (Testing) version
• 1. What is required
• 2. Installation and setup
• 2.1 How To Install The Script
• 2.2 Getting Started
• 2.3 Using Windows XP Web Publishing Wizard with Coppermine
• 2.4 Creating or upgrading your own themes
• 2.5 Safe mode issues
• 2.6 Using SMTP to send emails
• 3. Upgrading
• 3.1 Upgrading from version 1.0
• 3.2 Upgrading from releases of version 1.1
• 3.3 Upgrading from cpg1.2.0rc2 or cpg1.2.0final to version cpg1.2.1
• 3.4 Upgrading from cpg1.2.0 (or better) to version cpg1.4.1
• 3.5 The version check tool
  • 3.5.1 What it does
  • 3.5.2 Options
  • 3.5.3 Version comparison
• 4. Configuration & Administration
• 4.1 Categories, albums and files
• 4.2 Admin mode & User mode
• 4.3 The group control panel
• 4.4 The user control panel
• 4.4.1 Page controls
• 4.4.2 Searching for user(s)
• 4.4.3 Creating new users
• 4.5 The category control panel
• 4.6 The album manager
  • 4.6.1 Creating albums
  • 4.6.2 Renaming albums
  • 4.6.3 Changing the album order
  • 4.6.4 Deleting albums
• 4.7 Modifying album/files
• 4.8 Album properties
• 4.8.1 Reset album properties
• 4.9 Editing files
• 4.9.1 Editing videos
• 4.9.2 Custom thumbnails
• 4.10 Using bbcode to insert links and format in descriptions
• 4.11 Uploading pics by FTP / Batch-Add Pictures
• 4.12 The gallery configuration page
• 4.12.1 General settings
• 4.12.2 Language, Themes & Charset settings
• 4.12.3 Album list view
• 4.12.4 Thumbnail view
• 4.12.5 Image view
• 4.12.6 Comment settings
• 4.12.7 File and thumbnail settings
• 4.12.8 Files and thumbnails advanced settings
• 4.12.9 User settings
• 4.12.10 Movie Playback Settings
• 4.12.11 Custom fields for user profile
• 4.12.12 Custom fields for image description
• 4.12.13 Cookie settings
• 4.12.14 Email settings
• 4.12.15 Logging & statistics
• 4.12.16 Miscellaneous settings
• 5. Integrating the script with your bulletin board
  • 5.1 Available bridge files
  • 5.2 Pre-requistes
    • 5.2.1 Authentification by cookie
    • 5.2.2 Standalone version first
    • 5.2.3 Coppermine users, groups and pics uploaded by users are lost when integrating
    • 5.2.4 Backup
    • 5.2.5 Keep Coppermine and bbs tables in the same database
  • 5.3 Integration steps
    • 5.3.1 Using the bridge manager
      • 5.3.1.1 choose application to bridge coppermine with
      • 5.3.1.2 path(s) used by your BBS app
      • 5.3.1.3 database connection
      • 5.3.1.4 database tables
      • 5.3.1.5 BBS groups
      • 5.3.1.6 BBS-specific settings
      • 5.3.1.7 enable/disable BBS integration
    • 5.3.2 Recover from failed bridging
    • 5.3.3 Manual integration
      • 5.3.3.1 Check your bbs settings
      • 5.3.3.2 Edit your bridge file
      • 5.3.3.3 Enable bbs integration
    • 5.3.4 Special steps depending on the bbs you use
      • 5.3.4.1 For phpBB only
      • 5.3.4.2 For PunBB only
    • 5.3.5 Upload the modified files
    • 5.3.6 Synchronsising the bbs groups with Coppermine's groups
• 6. Translating Coppermine into other languages
• 7. Known Issues
• 8. Credits
• 8.1 Coppermine team
• 8.2 Contributors
• 8.3 Code used in Coppermine
• 8.4 License (Copyright & disclaimer)

0. Beta (Testing) version

Dear Tester,
 
Thank you for taking the time to test Coppermine Photo Gallery. Please be rough on the program so that we can track down and eliminate bugs from our public release of version 1.4.
Please understand that this is still beta software that is meant to be used for testing purposes and not for production, so there is no support for cpg1.4.1 yet.

While testing CPG 1.4, please make certain to note any odd behavior you encounter. This could include typographical errors, misleading instructions, or any other out-right error. If you encounter a major error, please switch the debug mode to "on" in the configuration panel and copy the text in the debug window. This will greatly aid the development team in hunting down the problem.

Areas to be particularly mindful of:

• Please test every facet of CPG, from the installation on to every feature available (and in as many themes and languages as possible).
• If you have the ability to test GD, GD2 and ImageMagick, please test all of them.
• Please attempt to use multiple types of graphics such as JPEG, PNG and GIF (for ImageMagick and GD 2.0.28+ users).

Please report your test results to the testing board, but before starting a new thread make sure that the potential bug you're going to report hasn't been posted before.

The report format should include:

• Server OS
• Web Server Software
• GD, GD2 or ImageMagick Test
• PHP Version
• BB Integration (if any)
• Themes fully tested (by fully tested, we mean as many different features as
• possible using that theme)
• Major Errors
• Client OS and Browser
• Fresh install or upgrade (if yes, from which version of cpg)

Your test results will not merely be used to fix problems but will also be used to tout the compatibility of CPG with multiple browsers and OS's. That is why this information is important EVEN IF YOU FIND NOTHING WRONG.

Thanks for your participation and your time in making CPG the premiere open-source photo gallery!

Coppermine Development Team

Back to top

1. What is required

• A web server that supports PHP (the script should work with any version >= 4.1.0)
• A MySQL database
  You need at least version 3.23.23 or better (4.x recommended). Your mySQL user needs permissions to perform CREATE, ALTER, SELECT, UPDATE, DELETE (most user have this permissions when webhosted; if you don't have them, you won't be able to use any pre-made scripts at all).
• PHP (version 4.1.0 or better), either compiled with the support for the GD library or permission to use the exec() function for the ImageMagick "convert" utility in order to make thumbnails and reduced size images.

Back to top

2. Installation and Setup

2.1 How to install the script

• Unpack the archive preserving the directory structure
  (you can rename the coppermine folder, but not the files or folders within).
• Upload all files onto your webserver (make sure to use the correct ftp mode)
• CHMOD the folders albums and include to 755 (or 777, depending on your server config) - this step is really important, don't skip it!
  There are a lot of tutorials for beginners how to use chmod available: search chmod tutorials with google. If you're on a windows server, you'll have to set permissions accordingly as well (usually the webserver runs under the user name "IUSR_hostname" - you'll have to set rwx-permissions for this user).
• Run the install script on your server (http://your_server/coppermine_dir/install.php) and follow the instructions

Back to top

2.2 Getting started

Log in with the admin username and password you set up during install, click on the "admin mode" link if it is visible, go to the Config page and start to configure your gallery. Note that even if you are a member of the administrator group, you need to be in "admin mode" to configure your gallery.

There are some settings in config that can't be changed later (if there are already files in the database) - make sure to set them up correctly in the first place. Although you'll surely want to start using coppermine immediately it is advisable to configure those settings (marked with an asterisk "*") properly at the very beginning.

Use the "Album Manager" ("Albums" link in the admin menu) in to create and order your albums. You'll need at least one album your files can go into.

Use the anonymous group to define what non-regsitered users can and can't do (in the groups panel).

Use the properties of an album to modify its description and permissions.

In order for a user to be allowed to upload a file in album two conditions must be met:

• The user must be part of a group that can upload files.
• There must be at least one album where "Visitors can upload files" has been set to "Yes",
  OR
  The user has created an album in the 'user galleries', if allowed.

The same applies to picture rating and comment posting.

If you have installed the script succesfully but are having trouble getting it working properly you can enable the "debug mode" on the Config page. In this mode, the script outputs most of the warning/error messages produced by PHP in addition to some debug information. This can provide valuable information to understand what is wrong.

Back to top

2.3 Using Windows XP Web Publishing Wizard with Coppermine

If you are using Windows XP, you can use its built-in web publishing wizard to upload your photos to your gallery.

Once you have properly installed the script on your server, call the xp_publish.php file from your web browser (http://your_site.com/coppermine_dir/xp_publish.php).

The script displays some information on how to do the installation on the client side and how to use the Wizard. Basically you will need to download a small file created by the script that needs to be loaded into your Windows registry.

[cpg1.1.1 or better required]

Back to top

2.4 Creating or upgrading your own themes

To upgrade an existing custom theme, to version 1.3.x, read theme.htm

Coppermine themes are stored in the "themes" directory, they consist of 3 files :

• "template.html" the main template in plain HTML.
• "style.css" the stylesheet associated with the template
• "theme.php" the PHP theme file

To create a new template, the best solution is to use an existing one as a basis. To do that, make a copy of the folder of the theme you want to use as a basis. Then edit the "template.html" 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.

When editing the "template.html" file do not remove the elements between {} these are the placeholders used by the script. Also keep in mind that despite this file being located in the "themes/your_theme_dir" directory, it must be build like if it was in the main directory of the script. Practically to load an image, you must use <img src="themes/theme_dir/images/image.gif" alt=""/> and not <img src="images/image.gif" alt=""/>. The same apply for the "theme.php" file.

Also, make sure not to delete the line <script type="text/javascript" src="scripts.js"></script> that is needed for the full-size pop-ups and other stuff related to JavaScript.

If you are using an HTML editor to make your template, the best solution is that you copy the "template.html" file into the main directory of the script and edit it there. If the script find a file named "template.html" in the main directory it will load it instead of the one of the theme directory. Once you have finished your editings, move the file back to the directory of your theme.

To modify the colors, fonts, font sizes, etc... used by the script, edit the "style.css" stylesheet. 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.

The "theme.php" file contains all the HTML templates used by the script. You can also edit them. When making modifications to these templates, don't touch the lines with <!-- BEGIN xxx --> and <!-- END xxx -->.

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

While you're in the process of creating a new theme, you might not want to show the theme to the visitors of your page, but you (as coppermine admin) want to 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

Back to top

2.5 Safe mode issues

A significant number of webhost on the Internet run PHP in safe mode. Coppermine runs without any problem in safe mode and with the "open basedir restriction" active, provided safe mode is properly configured. Unfortunately on many hosts, safe mode is not configured properly.

If your webhost is running PHP in safe mode but is misconfigured, you may need to do the following :

• With a FTP program, change the mode of Coppermine's "include" directory on your server to 0777.
• Do the same for the "albums" and "userpics" directories.
• Check that at the beginning the the "include/config.inc.php" file, you have a line with : "define('SILLY_SAFE_MODE', 1);"

Back to top

2.6 Using SMTP to send emails

By default the script uses the PHP built-in mail function to send emails. In some cases, the PHP built-in function can't be used.

If in order to send emails with PHP you need to supply a hostname, a username and a password, you need to edit the config section "Email settings" and put the correct values there. If you don't need a username and password to connect to your SMTP server, just leave them blank. If you don't know what settings to enter, contact your webhost.

Back to top

3. Upgrading

3.1 Upgrading from version 1.0

If you already have installed version 1.0 and you want to transfer your albums to version 1.2 proceed in the following way:

• First, make a backup (dump) of your database.
• Install version 1.3.2 normally in a directory different from the one where you installed v 1.0. Note that in order to use the upgrade script, tables for version 1.0 and 1.3.2 must be stored in the same database.
• Copy the "albums" directory of version 1.0 into the directory where you installed version 1.3.2
• The upgrade script assumes that you used the "CPG_" prefix for tables (default value) when you installed version 1.0, if this is not the case, edit upgrade-1.0-to-1.2.php and edit the $prefix10 variable.
• Login to your 1.3.2 Gallery, enter the admin mode
• Call the upgrade script, http://yousitename/coppermine_dir/upgrade-1.0-to-1.2.php
• The upgrade from 1.0 to 1.3.2 is a two-step process. You must click the link which comes up on the bottom of the page to complete the upgrade!.
• Delete upgrade-1.0-to-1.2.php from your server.
• If you get an error, go to Coppermine 1.3.2 config page, enable debug mode, try to call the upgrade script again and check what errors you get.

This upgrade process leaves your v1.0 gallery untouched

Back to top

3.2 Upgrading from releases of version 1.1

• First, make a backup (dump) of your database.
• Backup your include/config.inc.php file, your anycontent.php file and your "albums" directoy.
• Unpack the archive
• If the file install.php exists in the root directory, delete it.
• Upload all of the new files and directories
• CHMOD the albums directory and all subfolders once more to 755 or 777 (depending on your server config)
• Call the upgrade script http://yousitename/coppermine_dir/update.php
• Your upgrade should be complete.

Back to top

3.3 Upgrading from cpg1.2.0rc2 or cpg1.2.0final to version cpg1.2.1

• First, make a backup (dump) of your database.
• Backup your include/config.inc.php file, your anycontent.php file and your "albums" directoy.
• Unpack the archive
• If the file install.php exists in the root directory, delete it.
• Except for the "albums" directory, upload all of the new files and directories making sure not to overwrite the include/config.inc.php file, your anycontent.php file or the albums directory.
• create a folder called "edit" within your "albums" directory - this folder will be used by coppermine as a temporary folder, do not ftp-upload files there. Make sure the new "edit"-folder is CHMODed the same way your albums-directory is (755 or 777, depending on your server's config)
• No database update necessary, you're ready to roll

Back to top

3.4 Upgrading from cpg1.2.x or cpg1.3.x to version cpg1.4.1

• First, make a backup (dump) of your database.
• Backup your include/config.inc.php file, your anycontent.php file and your "albums" directoy.
• Unpack the archive
• If the file install.php exists in the root directory, delete it.
• Except for the "albums" directory, upload all of the new files and directories making sure not to overwrite the include/config.inc.php file, your anycontent.php file or the albums directory.
• If you have not already done so, create a folder called "edit" within your "albums" directory - this folder will be used by coppermine as a temporary folder, do not ftp-upload files there. Make sure the new "edit"-folder is CHMODed the same way your albums-directory is (755 or 777, depending on your server's config)
• Run the file "update.php" in the coppermine directory once in your browser (e.g. http://yourdomain.tld/coppermine/update.php). This will update your coppermine install by making all necessary changes in the database.
• If you have made a custom theme, apply the changes that were introduced in the themes structure to your custom-made theme - refer to the theme-upgrade guide.
• You can not use language files from older versions of Coppermine - make sure to only have the language files that come with this package inside your lang folder (delete or rename all files from older versions within the lang folder)

Please note: as there have been changes both in the coppermine files and the database from cpg1.3.0beta to cpg1.3.0 (final), users of the beta will have to apply all steps mentioned above: both the files have to be replaced and the update.php script has to be run once.

Back to top

3.5 The version check tool

Since cpg1.3.2 Coppermine comes with an additional version checking tool to help you solve issues with upgrade easily. Unless others parts of coppermine that will only work for the version it has been written for, the versioncheck tool can be used with all versions starting from cpg1.2.1. To launch the versioncheck, simply add versioncheck.php to your browser's address bar after being logged into coppermine as admin (example: http://yourdomain.tld/your_coppermine_folder/versioncheck.php).

3.5.1 What it does

The script "versioncheck" is meant for users who have updated their coppermine install. This script goes through the files on your webserver and tries to determine if your local file versions on the webserver are the same as the ones from the repository at http://coppermine.sourceforge.net, this way displaying the files you were meant to update as well.
It will show everything in red that needs to be fixed. Entries in yellow need looking into. Entries in green (or your theme's default font color) are OK and should be left alone. When an entry is red or yellow, a help icon will appear next to it. Click it to find out more. Hovering with your mouse over an item will display additional information as well (tooltip).

The versioncheck screen has several sections:

• Section 1 explains what the versioncheck tool can be used for
• Section 2 ("Options") displays the options you can chose
• Section 3 will display a warning if coppermine was not able to connect to the online repository (where the most recent version data is being stored). The script will default to a local copy of the repository file. If connection to the online repository was succesfull, there will of course be no error message (no section 3).
• Section 4 will show what version of coppermine you actually use. The versioncheck script draws this piece of information from the file include/init.inc.php - if you haven't replaced your copy of this file with the new version during upgrade, your old (outdated) version will appear in this section.
• Section 5 will show the core of versioncheck's file: the version comparison. The script will loop through all files that are suppossed to exist (based on repository data) and compare them to the files you actually have on your webserver.
• Section 6 will display a summary of the files and folders checked

3.5.2 Options

The options screen let's you configure the versioncheck, or rather what is being displayed. The options aren't saved anywhere, so you will have to adjust them each time you run versioncheck. The default options should be OK for most users - only change them if you have good reasons to do so.

• show optional folders/files
  Uncheck this to hide files that are tagged as "optional" (display mandatory files only)
• show mandatory files
  Uncheck this to hide files that are tagged as "mandatory" (Note disabling both optional and mandatory files will of course result in no files being displayed at all)
• show additional information
  Toggles wether informaton about the installed coppermine version and the repository connection status are being displayed. Uncheck if your're making screenshots to save space and reduce dimensions.
• show file versions
  Toggles wether additional version information of a file that belongs to the release version you're using should be displayed. When viewing the source code of a coppermine file, the file version is the number that looks like this: Id: index.htm,v 1.66 2004/08/26 04:42:19 gaugau Exp (in this example the file version is 1.66)
• show folders/files with errors only
  Toggles display of files that don't have errors. Enable this option if you want to make a screenshot and ask for support on the coppermine forum.
• coppermine is installed in the webroot
  Experimental: if all your files are being displayed as "non-existant", you probably have installed coppermine in your webroot, or you are using subdomains. Check this option only if you are experiencing problems. This option hasn't been tested thoroughly yet, there's no guarantee it will work on your setup.
• try connecting to the online repository
  Toggles wether versioncheck should try to connect to the online repository (checked by default). Only uncheck this option if you're sure you can not access the online repository because of your server setup and you want to reduce the time the script needs to execute a bit.
• show folder permissions
  Toggles the option to show/hide the read/write permissions of a folder.
• don't display web cvs link / display web cvs link to stable branch / display web cvs link to devel branch
  Toggles wether to show an additional column that contains a link to the web cvs. Only recommended if your cpg version is OK (green), but your file version appears to be outdated. You can then connect to the web cvs to get a more recent version of your file. Only recommended if you know what you're doing (or you have been told to do so from a supporter from the coppermine support board).
• show condensed ouput (for easier screenshots)
  When checked, this options reduces the width of the version comparison columns. This will allow you to create screenshots with reduced dimensions and size.

3.5.3 Version comparison

There is a lot of information on a small space available. Here's an example of a possible output and what the output means:

• Column "icon" shows if the entry is a folder or a file. Clicking on the icon takes you to the page, e.g. clicking on util.php will take you to the "admin tools page" (although not all coppermine files can be opened directly by running them in the browser).
  In above example, rows "A" to "E" are folders, rows "F" to "K" are files.
• Column "folder/file" holds the relative path from your coppermine root to the folder/file in question.
  If an entry is in your default font color, it exists (in above example, all rows but "G" and "H").
  If the entry is in yellow (row "G"), the corresponding folder/file doesn't exist on your webserver, but it is only considered to be optional (e.g. a language file that comes with the coppermine package that you don't want to use can be deleted from the webserver. It will then be shown in yellow, as it's only optional to have it). It's up to you if you need it.
  If the entry is in red (row "H"), the folder/file in question doesn't exist on your webserver, but it is mandatory to have it. You should upload the file from your coppermine package to your webserver. Only leave it as-is if you really know what you're doing.
• The column "writable" shows information if the folder in question is writable, and wether this is correct. The write permissions for files are not being displayed, as this would slow down the script very much. Usually, there are icons that show the writable status of your folder (if you have the icon resources on your webspace). Optionally, a plain text message in brackets might be visible (if you don't have the icon resources).
  • A white pencil with a green "x" indicates that the folder is not writable and is isn't suppossed to be writable - everything is OK then (row "A")
  • A green pencil indicates that the folder is writable and it is suppossed to be writable as well - everything is OK then (row "D"
  • A white pencil with a red "x" indicates that the folder is not writable, although it should be (row "C"). You should change write permissions (CHMOD) for this folder and everything within it, usually using your FTP software.
  • A red pencil indicates that the folder is writable, but it shouldn't be (row "E"). Having files writable could be a security risk. If possible, you should change permissions for this folder and everything within it to read/execute only.
• A question mark in a yellow box (help icon) indicates that there is additional information available. Click on the icon to see a pop-up window with this information.
• The column "cpg version" displays what coppermine package your file on your webserver is from, and what version it should be from. The data is being extracted from the header of the file, that's why folders are shown as "n/a" - they have no header information containing their coppermine version (rows "A" to "E").
  Files that contain header information are being displayed with your file version and the cpg version of the file in the repository, saparated with a slash. It's possible that a file version may differ from the version of your whole package - this doesn't matter as long as both your version and the repository versions match (the are displayed in green) - in above example: rows "F", "J" and "K".
  Of course version numbers from files that don't exist can't be extracted, that's why rows "G" and "H" have a dash as cpg version. If your cpg version is lower than the repository version, your version is being displayed in red: if this is the case, you probably haven't uploaded the proper file from your coppermine package to your webserver (replacing the file that exists on your webserver) - you should do so now (row "I").
  If your local version is being displayed in yellow, you're using a file that belongs to a higher coppermine version than the rest of your files - you probably downloaded a file from the devel branch: remember that using devel files go unsupported, do so on your own risk (if you know what you're doing). If most or all of your files are being displayed in yellow, you probably have upgraded some files, but you forgot to upgrade the file "include/init.inc.php" (that holds the version info for your install). Make sure to upload all files from the package to your server.
• The column "file version" holds the individual file's version that get's increased during development of a new coppermine version (each time a developer modifies a certain file, the version number increases by one). As folders can't contain such version numbers, they are again labelled as "n/a" (rows "A" to "E"); the same applies to files that don't exist, that's why their file version is displayed as dash (rows "G" and "H"). Also the file version is irrelevant when comparing files from different coppermine packages, that's why row "I" has a dash as well.
  The coloring scheme is similar to the cpg version system: green means "everything is OK", red means "you're using an outdated version" and yellow means "you're using a newer version than you're actually suppossed to.
  The difference between the cpg version and the file version columns is the way you should obtain the file that is suppossed to replace the existing one on your server: a red entry in the cpg version column means the file on your server hasn't been replaced with the file from the coppermine package; a red entry in the file version column (row "J") usually means that there have been updates to a certain file after the release of the package - you should either check if there is a newer package available or get the most recent file from the CVS (enable the web cvs link column in the versioncheck options).
• The column "web cvs" (off by default) links to the corresponding file in the CVS. You're recommended to use this only if there appears to be a newer version in the cvs than your coppermine package has and you know what you're doing.

Back to top

4. Configuration & Administration

4.1 Categories, albums and files

The Coppermine Photo Gallery (CPG) works in the following way:

• Files are stored in albums
• Albums are organised in categories
• Categories can be nested (subcategories)

If you don't have many albums, you don't need to use categories. In that case you don't create any category and all your albums will appear on the main page of the script.

There is a special category named "User galleries". This category can't be deleted. If a user belongs to a group where "can have a personal gallery" is set to YES, he will have the right to create his own albums and his gallery will be a sub-category of "User galleries".

The administrator can create albums in any category. Regular users can only create albums in "User galleries/Their_username".

Back to top

4.2 Admin mode & User mode

When you are logged in as an admin, the script has two modes of operation : Admin mode & User mode. You switch between Admin & User mode by clicking on the corresponding link in the menu bar at the top of the screen.

When you are in admin mode, you can administer your gallery and the following menu bar appears :

When you are in user mode you are just a regular user and can't access the admin pages.

The items in the admin menu should be pretty self-explanatory:

• Upload approval
  See all pics that await approval by the admin (depending on the settings in the "groups" control panel)
• Config
  Configure the overall look of your gallery and the settings using the "Config" button in the admin menu (note: you can not access the configuration by manually entering the url of the config file)
• Albums
  Create/edit/delete albums
• Categories
  Create/edit/delete categories
• Users
  Create/edit/delete users
• Groups
  Create/edit/delete groups
• Ban Users
  Ban users based on hostname or IP address. Make sure not to ban yourself! Use this feature with extreme care, since most users don't have static IP addresses, this feature should only be used if you really know what you're doing.
  [cpg1.3.0 or better required]
• Display Ecards
  View the ecards sent by users.
  You will have to enable ecard-logging in the config first (by default, logging is disabled). When enabled, all ecards that are being sent are as well written into the database, where the coppermine admin can view them.
  
  You can sort the log by clicking on the arrow icons next to each heading, and you can delete single or multiple log entries (deleting the log entries will not disable the ecard recipient to view the ecard).
  Before switching this option on, make sure that logging is legal in your country. It is also advisable to notify your users that all ecards are being logged (preferrably on the registration screen).
  [cpg1.3.0 or better required]
• Review Comments
  edit/delete user's comments
• Batch add files
  Batch-add files to the coppermine database that have been uploaded by FTP.
• Admin Tools (Resize Pictures)
  Collection of utilities to;
  
  Rebuild or resize intermediate pictures and thumbnails.
  
  
  Use this if you have changed the settings for thumbnail or intermediate images in config, or if you have to replace corrupt versions.
  Select the radio button for this action, then choose to rebuild the thumbnails, intermediates, or both.
  This uses a lot of server resources, so if you have timeout problems, try doing it in smaller batches.
  
  Delete full-size pictures.
  
  Use this to save space on your webspace.
  When selected, Coppermine checks to see if an intermediate copy exists, and if it does, it deletes the original sized picture, then re-names the intermediate. If no intermediate exists, Coppermine leaves the original in place.
  
  Delete orphaned comments.
  
  Sometimes, when pictures have been deleted, any comments associated with them remain in the database. Use this to remove them from the database entirely.
  
  Rename file titles.
  
  Use this to re-name the title of all files in an album, using info from the filename.
  
  Delete file titles.
  
  Use this to clear the file titles from one or more albums.
  
  View your server php info.
  
  If you are having problems, it is sometimes caused by server setup. Clicking this link will provide you with all your php and mySQL settings, as well as on the GD library (if installed). This may be needed by the support team, if you are unable to sort problems yourself.
  It is not possible for visitors to your site to browse to this information, so if asked for it, copy and paste it to the support board.
  
  Run a database update (update.php).
  
  After an update/upgrade, it is usually necessary to run update.php. This can be done by typing the address directly into your browser, or by clicking this link.


• My profile
  Edit your own user profile

There's an admin mode and user mode for "regular" users as well - the user admin has these options:

• Create / order my albums
  similar to album manager in admin mode, the user can create albums within his user gallery
• Modify my albums
  The user can edit album title and description (similar to "album properties" for the admin, but the user can't move his albums to other categories)
• My profile
  The user can edit his profile (changing passwords, edit location, interests, home page and occupation properties, view quota usage). If you're using bbs integration, the "My profile" link will send the user to the bbs's profile page.

Back to top

4.3 The group control panel

This is where you define what members of a group can and can't do.

The disk quota applies only for groups where "Personal gallery" has been set to "Allowed". Both files uploaded by a user in his personal gallery as well as files uploaded to public galleries are included in the quota.

Use the anonymous group to define what non-registered users can and can't do. Quota and "Personal gallery" are meaningless for anonymous users.

Permissions control what the user is allowed to do in the gallery (Rating/Sending Ecards/Posting Comments).

Bear in mind that if a user is a member of a group where "Rating", "Comments" or "Public albums upload" is set "YES", he will have the right to perform these operations only in albums where they are allowed, ie. uploading files will only be possible in albums where "Visitors can upload files" has been set to YES.

If "Personal gallery" is set to Allowed, the members of the group will have their own gallery in the "User galleries" category where they will be able to create their own albums.

If "Approval" is set to NO, files uploaded by members of the group in albums created in their own gallery won't need to be approved by the admin. If "Approval" is set to YES, the users in the particular group will be able to upload, however the uploaded files will only be shown if the admin has approved them.

The group control panel enables you to control the upload experience of any group.

Upload method lets you select the type of upload form a group may use. Four form types are currently available.

• Single file uploads only - The group may not use advanced uploading features. They may upload one file at a time. To enable single file uploads only, set File upload boxes to "1", URI upload boxes to "0" and No. of boxes to "fixed"
• Multiple file uploads only - The group may upload multiple files at one time. To enable multiple file uploads, set File upload boxes to any number higher than "1", URI upload boxes to "0" - it's up to you to let users configure the No. of boxes, but it's recommended to set it to "fixed" to avoid confusion.
• URI uploads only - The group may only upload files using URIs. Acceptable URIs must begin with 'http://' or 'ftp://'. To enable URI uploads only, set File upload boxes to "0", URI upload boxes to "1" or higher.
• File-URI - The group may upload files using file upload boxes and URIs. To enable both file and URI uploads, set File upload boxes to "1" or higher, URI upload boxes to "1" or higher

No. of boxes set to "variable" allows the user to select the number of upload boxes for an upload. Usually, you will leave this option set to "fixed", as it presents the user with an additional step in the upload wizard that is not necessary.

File upload boxes controls the number of file upload boxes presented to the user. If the user may customize the number of boxes (No. of boxes set to "variable"), this setting serves a maximum limit for the number of boxes he may request. Otherwise, this setting determines the number of boxes that will appear on the upload form.

URI upload boxes is the same type of control as File upload boxes, but it controls the presentation of URI upload boxes.

Back to top

4.4 The user control panel

The user control panel can be found when clicking "users" from the admin menu. It is the place where you create and manage your users.
If you have enabled integration (bridging) Coppermine with another application (e.g. your favorite BBS app), Coppermine will use the member table of the application you bridged with (your BBS), so the built-in Coppermine user management will be disabled in favor of the user management that comes with the bridged application.
As a result, you will not have this user control panel; clicking the "users" link will send you to your bridge application's user management instead.

4.4.1 Page controls

• You can sort the user management display by either clicking the arrow icons () next to each column header or by choosing the sort order from the dropdown at the top right.
• If you have more than 25 user, a page tab will apear at the bottom right of the screen, allowing you to go to other pages of your member list
• Clicking on a user's name will display the profile page of the individual user (read only)
• The edit icon () will send you to the user's profile in edit mode - you can change the password, email account and other user-related settings there
• If a user has uploaded any files, a link "recent uploads" will show up next to his name that will do show the files uploaded by that particular user
• The group column will display the primary member group the user is in
• The column "Registered on" will show the date the user account has been created
• The "Last visit" column will show the last login of the user.
  Note: if the user has ticked the checkbox "Remember me" on the login screen, he will not have to login every time he visits the gallery.
• The "Files" column displays how many files the user has uploaded so far (including those that wait for admin approval)
• The "Space used" column shows how much of the space that is assigned to the user has already been used. The total space the user is allowed to have ("Space Quota") depends on the user's group - you set it in the groups panel.
• You can change some settings for several users at once by clicking the checkbox in front of the user row (use the checkbox at the very top or bottom of the page to select/unselect all users on the page) and then chosing an action to perform from the dropdown box "With selected" at the bottom left of the page. The actions to chose from are "Delete", "Deactivate", "Activate", "Reset password", "Change primary membergroup" and "Add secondary membergroup". The user currently logged on (you as gallery admin) has no checkbox to avoid accidental deletion or deactivation of your own admin account.

4.4.2 Searching for user(s)

You can use the wildcards * (any string) and ? (any single character) or even %expression%.
Example: searching for j* will return both Jack and Jill

4.4.3 Creating new users

To create a new user, simply click on the button "Create new user" at the bottom of the page and fill in the form that will come up.

Back to top

4.5 The categories control panel

This is where you can edit your categories.

• The button allows you to edit the title, description and parent category of an existing cetegory.
• The button allows you to delete a category. Deleting a category does not delete the albums and files it contains. They are simply moved to the "Root" category.
• The and buttons allow you to order your categories.
• The "Move into" dropdown lists allow you to change the parent of a specific category.

"User galleries" is a special category. It is not visible unless you have some users that have created their own gallery. It can't be deleted but you can edit its title and description by using the button.

You can specify to have coppermine sort all categories alphabetically (instead of a customized order) by setting "Sort categories alphabetically" to "Yes". This setting is available both in coppermine config and the category manager. If you enable alphabetical sorting, the up and down arrows that normally let you move the categories will disappear.

Back to top

4.6 The Album Manager

Coppermine stores files inside of albums, so you'll need at least one album your pictures/files can go to. Albums can be stored in categories (but they don't need a category, they can as well go into the coppermine "root").
When you click on "albums" in the admin menu, you will see the Album Manager.

4.6.1 Creating albums

• Choose a category from the dropdown list "Select category" where your album should go to (or choose "* No category *" if the album should go into the coppermine "root"). If you haven't created a category yet, go to the categories control panel first, but you can later move the album as well using the album properties page.
• Click on the button "New" - your new album will appear on the list, by default labelled "New album"
• Click on the text input filed at the bottom of the screen, highlighting the default name "New album"
• Type the album name you want to assign
• (repeat steps 2 to 4 to add more than one album)
• click "Apply modifications" to submit your changes to the database (if you don't, all changes will be lost)
• Confirm the alert box with "OK" (Are you sure you want to make these modifications ?)

4.6.2 Renaming albums

• Choose a category from the dropdown list
• Click on the album you want to change
• Click on the text input filed at the bottom of the screen, highlighting the album name
• Type the album name you want to assign
• click "Apply modifications"
• Confirm the alert box with "OK" (Are you sure you want to make these modifications ?)

4.6.3 Changing the album order

• Choose a category from the dropdown list
• Click on the album you want to move up or down in the list
• Use the arrow buttons to move the album up or down
• click "Apply modifications"
• Confirm the alert box with "OK" (Are you sure you want to make these modifications ?)

4.3.4 Deleting albums

• Choose a category from the dropdown list
• Click on the album you want to delete
• Click the "Delete" button
• Confirm the alert box with "OK" (Are you sure you want to delete this album ? All files and comments it contains will be lost !)
• click "Apply modifications"
• Confirm the alert box with "OK" (Are you sure you want to make these modifications ?)

Back to top

4.7 Modifying albums/files

When you are in admin mode there is a menu displayed next to each album

Delete allows you to delete the album and all files it contains.

Properties allows you to modify the name, description and permissions of the album

Edit pics allows you to modify the title/caption/keywords etc... of the files in the album

Back to top

4.8 Album properties

The "Album category" drop down list allows you to move an album between categories. If you set this to "* No category *" then the album will be displayed on your main page.

Use bbcode to add links and some formating to the description.

The thumbnail is the picture that will represent the album in the album list.

If you have set "Users can can have private albums" to YES on the config page, you can define who can view the files of this album.

When "visitors can upload file" is set to YES, it is possible to upload files in this album.

Note that a visitor will have the right to upload files into an album where this option is set to YES only if he is a member of a group for which "Can upload pictures" is set to YES. Non registered users are members of the "Anonymous" group.

The same rules as above apply for "Visitors can post comments" and "Visitors can rate files".

4.8.1 Reset album properties

You can reset the views and ratings in the album and even delete all pics at once in the sub-section "Reset album" by ticking the checkboxes and then submitting the form. To avoid accidental resets, you have to tick the checkbox "I'm sure" before you can actually submit the changes (the button will be greyed out if you don't).
Use these options with care: the deleting of files is irreversible, as well as the reset of views and ratings (you can only restore views and ratings by manually editing coppermine's database entries with third-party tools like phpMyAdmin - not recommended).

Back to top

4.9 Editing files

This is where you can modify the title description, keywords and custom fields (if they are used) of a file.

Use the album drop down menu to move the file to another album.

Back to top

4.9.1 Editing videos

This is where you can modify the title description, keywords and custom fields (if they are used) of a video.

Use the album drop down menu to move the video to another album.

Use the height and width fields to set the size of the video.

Video uploads are available for cpg1.3.0 (or better) as part of the distribution and for cpg1.2.1 as separate modification.

[cpg1.3.0 or better required]

Back to top

4.9.2 Custom Thumbnails

Order of thumbnails:
Thumbnails are selected by level (user-defined, theme-defined, global) then by type (file-specific, extension-specific, media-specific) in order. User-defined thumbnails are stored in the folder where the file is located. Theme-defined thumbnails are stored in the themes 'images' folder. Global thumbnails are stored within the 'images' folder of the Coppermine root. Thumbnails can be either a 'gif', 'png', or 'jpg'.

Types of thumbnails:
File-specific thumbnails must have the same base name as the file. Using the example in the screenshot, its thumbnails could be 'thumb_thailand_waterfall.gif', 'thumb_thailand_waterfall.png', or 'thumb_thailand_waterfall.jpg', chosen in that order.

Extension-specific thumbnails are named after the extension of the file. (Examples: 'thumb_wmv.jpg', 'thumb_wav.jpg'.)

The base name for media-specific thumbnails are 'thumb_movie', 'thumb_document', and 'thumb_audio'. Images use file-specific thumbnails by default.

Uploading:
There are 2 ways to upload custom thumbnails:

1. Have an image already uploaded then upload a video via the upload page. (or vice versa) The video will share the thumbnail of the image.

2. FTP upload both the video and (thumbnail or image) then batch-add. If you FTP upload the thumbnail, the thumbnail will be shown instead of the default Coppermine thumbnail on the batch-add page. If you upload an image it will look like the screenshot. However, when the two files are added, the thumbnail of the image will be used by the video.

Final result.

Note: If methods 1 is used and the image is deleted, the thumbnail will be deleted also, and the default Coppermine thumbnails will be used.
If a previous video has be uploaded via FTP, the thumbnail must be uploaded via FTP to the same folder.

Video uploads are available for cpg1.3.0 (or better) as part of the distribution and for cpg1.2.1 as separate modification. Custom thumbnails aren't supported in versions prior to 1.3.0. Using these instructions, a custom thumbnail can be applied to any file, not just videos.

FAQS:

• Quote
  
  I have a video named 'movie.wmv', when I upload a thumbnail for it 'thumb_movie.jpg' it replaces multiple videos!!!!
  Duhh. 'thumb_movie.jpg' is a media-specific thumbnail. Rename the video and the thumbnail to something other than just 'movie'.
• Quote
  
  I can't find my user's folder!
  From within Coppermine, browse to the user's album. Look in the url of your browser and you should see the folder's name. (See screenshot for an example.)
  
  Your users can upload their own thumbnails by using this trick: Create an album. Change the permissions on it so no one can view it except him. Then upload the fullsize images of the thumbnails to this folder. Files outside this album will be able to use the thumbnails of these images. (See above for naming.)
• Quote
  
  How do I stop my users from creating their own custom thumbnails?
  Right now, you can't.

[cpg1.3.0 or better required]

Back to top

4.10 Using bbcode to insert links and format in descriptions

Coppermine understands the following bbCodes (the same bbCodes that are used by phpBB and many other BBS apps) in image and album description

• [b]Bold[/b] => Bold
• [i]Italic[/i] => Italic
• [url=http://yoursite.com/]Url Text[/url] => Url Text
• [email]user@domain.com[/email] => user@domain.com
• [color=red]some text[/color] => some text
• [img]http://coppermine.sf.net/demo/images/red.gif[/img] =>

Back to top

4.11 Uploading pics by FTP / Batch-Add Pictures

It's recommended that the coppermine admin uses ftp to upload many pics in one go. Use your ftp software to create sub-folders within your_coppermine_directory/albums/, where your ftp uploads can go to. It's a good idea to have a folder structure within the albums folder that reflects your coppermine categories and albums, but it's not mandatory.
Important: do not create folders or upload to the userpics- nor the edit-folder by ftp: these folders are used by coppermine internally and mustn't be used for any other purpose! Folder names mustn't contain dots and it's even recommended not to use any special chars - only use a-z, numbers and maybe - or _. Make sure to upload in binary or auto-mode.

Once you have uploaded your photos by ftp, click on the Batch Add Pictures button. The batch-add is done in three steps:

• find the directory under which you have uploaded your photos. Select this directory by clicking on it.
  
• select the photos you wish to upload (by ticking them, the new pics are pre-selected, those that already are in your coppermine database are not selected) and the album you wish to insert them into. Click "Insert Selected Pictures" to start the batch-add process.
  
• CPG will then display the results of the batch-add (allow some time untill all results are being shown).
  If the OK, DP, PB 'signs' does not appear click on the broken file to see any error message produced by PHP.
  If your browser times out, hit the reload button.
  • OK : means that the file was succesfully added
  • DP : means that the file is a duplicate and is already in the database
  • PB : means that the file could not be added, check your configuration and the permission of directories where the files are located
  • NA : means that you haven't selected an album the files should go to, hit 'back' and select an album. If you don't have an album create one first

Giving FTP-access to other users is a serious security threat, that's why batch-add is only available for the coppermine gallery admin.

Once files have been added to coppermine's database, make sure not to rename or delete them by ftp - use coppermine's admin menu to remove files instead, since this way they will be removed both from the file system and the database.

Back to top

4.12 The gallery configuration page

This is the place where you configure the most important parts of your coppermine gallery. Some settings have an impact on the files you upload - changing the options once you have a large number of files in your gallery can be difficult, that's why you should make up your mind on those settings right after initial coppermine install, before you actually upload any pics or show the gallery to the public.

4.12.1 General settings

Gallery name

This is the name of your gallery. It will appear in the title of your page and is shown on some templates.

Gallery description

This is a short description of your gallery. This description is shown on some templates below the name of your gallery.

Gallery administrator email

All emails sent by the gallery are sent with this email address. Make sure to enter a valid email address.

URL of your coppermine gallery folder

This is the URL where a user will be directed when he will click on the "See more pictures" link in an e-card. This must be the URL for your gallery (just the path to your coppermine folder, e.g. http://yourdomain.tld/coppermine/). Don't specify a certain file (like index.php) in this field.
In older versions of Coppermine, this field used to be labelled "Target address for the 'See more pictures' link in e-cards", but since this url is used in other places of coppermine as well the label was changed.

URL of your home page

This is the URL where a user will be directed when he clicks on the "Home" button in the main menu.

You can use "/" for the root of your domain, "index.php" for your gallery, or any valid URL.

[cpg1.4.0 or better required]

Name of your custom link

This is the name that will appear in the menu for your custom link. Leave empty if you do not use.

[cpg1.4.0 or better required]

URL of your custom link

This is the URL where a user will be directed when he clicks on the "Custom link name" button in the main menu.

You can use any valid URL.

It is important you leave this blank if you want no custom link.

[cpg1.4.0 or better required]

Gallery is offline

If you have to do maintenance work to do on your gallery, switch it to offline mode. Only members of the admin group will be able to log in, all other users will only see "Gallery is offline". Remember to switch this option off once your maintenance work is done.

[cpg1.3.0 or better required]

Allow ZIP-download of favorites

When enabled, the user can download the files put into the favorites in a zip-file from the "My favorites" page. This option requires zlib to be installed on your server (run phpinfo to check if this library exists on your server).

[cpg1.3.0 or better required]

Timezone difference relative to GMT

Specify the time zone difference between your local time and the time zone your webserver is in. This value will be used to adjust time stamps in ecards and other places.

[cpg1.4.0 or better required]

Enable help-icons

Enable display of the help icons in various places within coppermine admin pages. When enabled, make sure you have uploaded the docs folder into your coppermine folder on your webserver.
If you choose to set this to "Yes: everyone", logged in users will see the help icon in some places as well, e.g. when creating a user gallery.
As the help text is based on the documentation that comes with coppermine, it is available in English only. If the native language of your users is not English, it is advisable to set this option to "Yes: admin only" to avoid confusion among your users.

[cpg1.4.0 or better required]

Show the vanity block on themes that are defined as XHTML and CSS compliant

When enabled and using a theme that has been defined as XHTML and CSS compliant, the vanity block will be shown. The vanity block contains the logos and links for HTML and CSS compliance at w3.org, as well as pointers to the PHP, and MySQL projects.

[cpg1.4.1 or better required]

Back to top

4.12.2 Language, Themes & Charset settings

Language

This is the default language for your gallery. All language files are stored in the lang directory on your server.

The language files with an "-utf8" suffix are unicode encoded files. If you select an -utf8 file as the default language and you set "Character encoding" to "Unicode (utf-8)" then the script will auto detect the preferred language of the visitor based on what is configured in his browser. If the corresponding language is available it will be used else the default language file will be used.

When the script auto detect the preferred language, it stores the result in a cookie on the visitor's computer. To reset this cookie (and so force the script to do another auto detection) call it with something like: http://yoursite.com/coppermine_dir/index.php?lang=xxx

Once you have added some comments or files to your gallery, you should not change the character set of your gallery. If you do so, non-ASCII character may not be shown correctly.

Fallback to English if translated phrase not found?

Enable this option if you're using other languages than english. If a certain phrase doesn't exist within your language file, coppermine will show the english phrase instead.
This feature has been introduced to allow the usage of older language files, as during the development of new coppermine versions only the english language file is being updated. To make up for translations being submitted later, you can use this option. Most translations affect the admin part of coppermine only, so mostly the admin will see some phrases in english instead of his language that don't exist in his language file. Currently this fallback option only works for 95% of all phrases, so there still might be some missing translations.

[cpg1.4.0 or better required]

Theme

Use this line to select the theme of your gallery. Themes are stored in sub-directories of the themes directory.

Display language list

Enable this option if you want your users to be able to select their own language with a dropdown list (you can specify to display only the list itself or a label saying "Choose your language:" in front of the list). Edit your template file (/themes/yourtheme/template.html) to specify where the language dropdown list should appear on your gallery (look for {LANGUAGE_SELECT_LIST}).

[cpg1.3.0 or better required]

Display language flags

Enable this option if you want your users to be able to select their own language by clicking on a flag representing their language (you can specify to display only the flags themselves or a label saying "Choose your language:" in front of the flags). Edit your template file (/themes/yourtheme/template.html) to specify where the language dropdown list should appear on your gallery (look for {LANGUAGE_SELECT_FLAGS}).

[cpg1.3.0 or better required]

Display "reset" in language selection

This option only applies if you enabled language selection at all - it will show a "default"-icon or list entry to let the users go back to the original language of your gallery.

[cpg1.3.0 or better required]

Display theme list

Enable this option if you want your users to be able to select another theme with a dropdown list (you can specify to display only the list itself or a label saying "Choose your theme:" in front of the list). Edit your template file (/themes/yourtheme/template.html) to specify where the theme dropdown list should appear on your gallery (look for {THEME_SELECT_LIST}).
This option only makes sense if you have at least one other theme in your /themes/ folder than your default theme. It's recommended to only offer this option if there's an additional benefit for the user (for example a theme with less graphics in it that loads faster for users on a dial-up connection, or a theme with reduced color pallettes and good contrast).

[cpg1.3.0 or better required]

Display "reset" in theme selection

This option only applies if you enabled theme selection at all - it will show a "default" list entry to let the users go back to the original theme of your gallery.

[cpg1.3.0 or better required]

Display FAQ

This option adds "FAQ" to the menu bar when enabled. If a user clicks on it, it will display a list of "Frequently asked question" on how to use coppermine. To change the content of the FAQ, edit the file /your_coppermine_folder/lang/yourlanguage.php (e.g. english.php) and look for

// ------------------------------------------------------------------------- //
// File faq.php
// ------------------------------------------------------------------------- //

[cpg1.3.0 or better required]

Display bbcode help

When enabled, this will display the bulletin board codes that are allowed to use in description fields next to the field.

[cpg1.3.0 or better required]

Character encoding

This should normally be set to "Default (language file)" or "Unicode (utf-8)". See the discussion in the "language" section of this page.

Back to top

4.12.3 Album list view

Width of the main table (pixels or %)

This is the width of tables used on your main page or when you are viewing thumbnails of an album. You can enter a width in pixels or specify it in percents. The default value is 100%.

Number of levels of categories to display

The default value is 2. With this value the script will display the current categories plus one level of sub-categories.

Number of albums to display

This is the number of albums to display on a page. If the current category contains more albums, the album list will spread over multiple pages.

Number of columns for the album list

Self explanatory. The default value is 2.

Size of thumbnails in pixels

This is the size of the thumbnails that are displayed for each album. 50 means that the thumbnail will fit inside a square of 50x50 pixels.

If the size you specify there is larger than "Pictures and thumbnails settings/Max width or height of a thumbnail", the thumbnail will be stretched.

The content of the main page

This option allows you to change the content of the main page displayed by the script.

The default value is "catlist/alblist/random,2/lastup,2"

You can use the following "codes"

• 'breadcrumb': navigation inside the gallery (e.g. "home > category > subcategory > album")
• 'catlist': category list
• 'alblist': album list
• 'random': random files (leaving random files "on" for huge galleries with more than 10,000 pics might result in performance problems; switch random "off" in this case)
• 'lastup': last uploads
• 'topn': most viewed
• 'toprated': top rated
• 'lastcom': last comments
• 'lasthits': last viewed
• 'anycontent': inserts php-generated content that has to reside within the file 'anycontent.php' into the index page. Can be used to include banner-rotation scripts or similar.
• 'lastalb': last created albums

Unless you really know what you are doing you should always keep catlist and alblist in "the content of the main page", as they are the most basic parts of the index page.

The ,2 means 2 rows of thumbnails.

Show first level album thumbnails in categories

Use this setting to choose between showing or not showing thumbnails from the first album in the categories.

Sort categories alphabetically (instead of custom sort order)

You can specify to have coppermine sort all categories alphabetically (instead of a customized order) by setting "Sort categories alphabetically" to "Yes". This setting is available both in coppermine config an the category manager. If you enable alphabetical sorting, the up and down arrows that normally let you move the categories will disappear.

[cpg1.4.0 or better required]

Back to top

4.12.4 Thumbnail view

Number of columns on thumbnail page

Default value is 4 this means that each row will show 4 thumbnails.

Number of rows on thumbnail page

Default value is 3.

Maximum number of tabs to display

When the thumbnails spread over multiple pages, tabs are displayed at the bottom of the page. This value define how many tabs will be displayed.

Display file caption (in addition to title) below the thumbnail

Toggles whether the file caption is displayed below each thumbnail while user is in (regular) thumbnail view.

[cpg1.3.0 or better required]

Display number of views below the thumbnail

Toggles whether the number of views is displayed below each thumbnail while user is in thumbnail view.

[cpg1.3.0 or better required]

Display number of comments below the thumbnail

Toggles the display of the number of comments for below each thumbnail.

[cpg1.3.0 or better required]

Display uploader name below the thumbnail

Toggles the display of the name of non-admin uploaders below each thumbnail.

[cpg1.4.0 or better required]

Display names of admin uploaders below the thumbnail

Toggles the display of admin uploader names below each thumbnail for users that have the administrators group set as thier default group.

[cpg1.4.0 or better required]

Display the file name below the thumbnail

Toggles the display of the file name below each thumbnail.

[cpg1.4.0 or better required]

Display album description

Toggles the display of the album description below each album thumbnail.

Default sort order for files

This option determines if you wish to have the file caption displayed below each thumbnail while user is in thumbnail view.

Minimum number of votes for a file to appear in the 'top-rated' list

Back to top

4.12.5 Image view

Width of the table for picture display (pixels or %)

The width of the table used to display the intermediate picture.

Examples:
600 = The table around the pic will be 600 pixels wide (unless the pic has larger dimensions).
100% = use the available space (depending on the horizontal dimension of the pic).

File information are visible by default

Define whether or not file information (those that appear when you click on the (i) button) should be visible by default.

Max length for an image description

Maximum number of characters that an image description may contain.

Show film strip

Toggles display of a "film strip" showing thumbnails of prior and following photos in the album.

[cpg1.2.0 or better required]

Display file name under film strip thumbnail

Toggles the display of the file name below each thumbnail in the film strip.

[cpg1.4.0 or better required]

Number of items in film strip

Set the number of thumbnails to display in film strip.

[cpg1.2.0 or better required]

Slideshow interval in milliseconds

This sets the time each pic is being displayed (transition interval) when a users views a slideshow (the next pic is being loaded/cached while the current one is being displayed). This setting has to be in milliseconds (1 second = 1000 milliseconds).
Remember that setting this to a very low value might not make sense for all users, especially those on dialup connections or if you have large files.

Back to top

4.12.6 Comment settings

Filter bad words in comments

Remove "bad words" from comments. The "bad words" list is in the language file. So far only the English language file has one.

Allow smiles in comments

Toggle the use of smilies in comments.

Allow several consecutive comments on one file from the same user

This setting toggles flood protection of the comments. When set to YES, a user can post another comment, even though he already posted a previous one. Recommended setting: NO.

Max number of characters in a word

This is intended to prevent that someone break the layout of the gallery by posting a long comment without space. With the default value, words with more than 38 characters are censored.

Max number of lines in a comment

Prevent a comment for containing too many new line char.

Maximum length of a comment

Maximum number of characters that a comment may contain.

Notify admin of comments by email

Toggle if you want to receive an email each time a comment is being posted. Warning: only enable this option on sites with very low traffic, or you will get flodded with notification emails.

Sort order of comments

Changes the appearance (sort order) of comments made on a single file.
Ascending: latest comment at the bottom, oldest comment at the top
Descending: latest comment at the top, oldest comment at the bottom

Prefix for anonymous comments authors

If you allowed anonymous comments, this prefix will be used for comments left by unregistered users .

Back to top

4.12.7 Picture and thumbnail settings

Quality for JPEG files

The quality used for JPEG compression when the script resizes an image. Value can range from 0 (worst) to 100 (best). This value can be set to 75 when using ImageMagick.
You shouldn't change this setting unless you know what you're doing, as the other thumbnail and intermediate pic options (dimensions) have a much greater impact on filesize than this compression level.

Max dimension of a thumbnail

Sets the maximum size in pixels for the specified dimension for thumbnails.

Use dimension ( width or height or Max aspect for thumbnail )

Sets the dimension for which the maximum pixel size should apply to.

Create intermediate pictures

By default, whenever you upload a file, the script creates a thumbnail of the file (file name with a thumb_ prefix) plus an intermediate version (file name with a normal_ prefix). If you set this option to NO, the intermediate file is not created.

Max width or height of an intermediate picture/video

The intermediate pictures are those that appears when you click on a thumbnail. The default value is 400, it means that the intermediate picture will fit inside a square of 400x400 pixels.

Max size for uploaded files (KB)

Any file with a file size larger than this value will be rejected by the script. Setting this option to a higher value than actually supported by your webserver will only result in "funny" webserver error messages instead of "regular" coppermine error messages - it's recommended to set this value at least a bit lower or equal to the max file size your server can actually handle. The actual size your server can handle is hard to determine for Coppermine (or any PHP script) - when in doubt, you should contact your webhost.

Max width or height for uploaded pictures (pixels)

Limit the dimensions of the pictures that are uploaded. Resizing large pictures requires a lot of memory and consumes CPU. There are usually limitations in place on your webserver - you can't set this Coppermine setting to a higher value than actually supported by your webserver.

Auto resize images that are larger than max width or height

During the upload process, if images are larger than the maximum width or height allowed they will automatically resize to the maximum allowed size.

Note: How the image is resized (width/height/max aspect) is set in the admin option "Use dimension (width or height or Max aspect for thumbnail)"

There are three options:

• No - Disabled
• Yes: Everyone - Enabled for all users, including the Admin during batch-add process.
• Yes: User only - Enabled only for regular users

[cpg1.4.0 or better required]

Back to top

4.12.8 Files and thumbnails advanced settings

Albums can be private

If set to YES then your gallery can contain albums that can be visible only by users that belong to a certain group.

If a user is a member of a group that can have its own gallery and this option is turned on then this user will have the permission to hide some of their albums to other users.

This option does not set wether users can have user galleries at all, nor does it set up who's allowed to upload at all (those settings are available in the groups manager). You should only set this option to NO if you really know what you're doing (by default, it is set to YES).

Note: if you switch from 'yes' to 'no' any current private albums will become public!

Show private album Icon to unlogged user

Toggles the display of the private album icon to unlogged users.
Set to 'NO', the album is hidden from unauthorised users.
Set to 'YES', the album name, description and statistics are shown, but not the thumbnails or files.

Characters forbidden in filenames

When the filename of a file that is uploaded contains one of these characters, it will be replaced with an underscore.

Don't change this unless you know exactly what you are doing.

Allowed image types

"ALL" will result in all allowed image file types that your image library (GD or ImageMagick) is capable of handling to be allowed. If you want to restrict the allowed file types to certain types only, enter a coma-separated list of extensions, e.g. jpg,bmp,tif

[cpg1.3.0 or better required]

Allowed movie types

"ALL" will result in all allowed movie file types to be uploaded. If you want to restrict the allowed file types to certain extensions only, enter a coma-separated list of extensions, e.g. wmv,avi,mov.
Note that being able to display a movie requires the cpg-user to have the codecs needed to display the movie installed and configured properly on their computer, e.g. if you allow the file type mov, the user who is going to watch the movie will need to have Apple's Quick-Time plug-in installed. Also note that avi is just a container for different codecs - this means that a computer which is capable of playing movie1.avi may not be capable of playing movie2.avi if those files have been encoded with different codecs.

[cpg1.3.0 or better required]

Allowed audio types

"ALL" will result in all allowed audio file types to be uploaded. If you want to restrict the allowed file types to certain extensions only, enter a coma-separated list of extensions, e.g. wav,mp3,wma.
Note that being able to listen to an audio file requires the cpg-user to have the codecs needed installed and configured properly on their computer, e.g. if you allow the file type mp3, the user who is going to listen to the file will need to have an mp3-player installed.

[cpg1.3.0 or better required]

Allowed document types

"ALL" will result in all allowed document file types to be uploaded. If you want to restrict the allowed file types to certain extensions only, enter a coma-separated list of extensions, e.g. txt,pdf.
Note that being able to browse a document file requires the cpg-user to have a software installed and configured properly on their computer that is capable of displaying the document type uploaded, e.g. if you allow the file type xls, the user who is going browse the file will need to have an application installed that can display MS-Excel sheets. Be carefull with some document types (especially if you allow users to be capable of uploading documents without admin approval), as they may contain macro viruses.

[cpg1.3.0 or better required]

Method for resizing images

Set this to the type of image library you have on your server (must be either GD1, GD2 or ImageMagick).

If you are using GD 1.x and the colors of your thumbnails or intermediate image are wrong then you probably have GD2 on your server - switch this option to GD 2.x

Most recent distributions of PHP come packaged with GD - if you're not sure what you have, set this option to GD2 and look your settings up in phpinfo.

Path to ImageMagick 'convert' utility (example /usr/bin/X11/)

If you are using ImageMagick convert utility to resize you picture, you must enter the name of the directory where the convert program is located there. Don't forget the trailing "/".

If your server is running under Windows, use / and not \ to separate components of the path (eg. use C:/ImageMagick/ and not C:\ImageMagick\). This path must not contain any space so under Windows don't put ImageMagick in the "Program files" directory.

ImageMagick will hardly work if PHP on your server is running in SAFE mode and it is a real challenge to get it running under Windows. Consider using GD in these cases and don't waste your time asking for support in the forum. There are too many things that can prevent ImageMagick to work correctly and without a physical access to your server it is hard to guess what is wrong.

Allowed image types (only valid for ImageMagick)

This is the list of image types that the script will accept when using ImageMagick. Image type detection is performed by reading the header of the file and not by looking at its file extension.

Command line options for ImageMagick

Here you can add options that will be appended to the command line when executing ImageMagick. Read the ImageMagick Convert manual to see what is available.

Read EXIF data in JPEG files

With this option turned on, the script will read the EXIF data stored by digicams in JPEG files. For cpg1.x to cpg1.2.1, this option will work only if PHP was compiled with the EXIF extension. Coppermine 1.3.0 (or better) comes with built-in EXIF support even if the webserver itself doesn't have EXIF support, as it uses a separate EXIF class.

[cpg1.3.0 or better required]

Read IPTC data in JPEG files

With this option turned on, the script will read the IPTC data stored by digicams in picture files.

[cpg1.3.0 or better required]

The album directory

This is the base directory for your "Image Store". The path is relative to the main directory of the script.

You can use ../ in the path to move-up one level in the directory tree.

You can not use an absolute path there ("/var/my_images/" will not work) and the album directory must be visible by your web server.

This setting mustn't be changed if you already have files in your database. If you do, all reference to your existing files will break.

The directory for user files

This is the directory where files uploaded with the web interface are stored. This directory is a subdirectory of the album directory.

The same remarks as above apply.

When you upload files by FTP, store them in a subdirectory of the "album directory" and not inside the "directory for user files".

This setting mustn't be changed if you already have files in your database. If you do, all reference to your existing files will break.

The prefix for intermediate pictures

This prefix is added to the file name of created pictures.

These setting mustn't be changed if you already have files in your database. If you do, all reference to your existing files will break.

The prefix for thumbnails

This prefix is added to the file name of created intermediate thumbnails.

These setting mustn't be changed if you already have files in your database. If you do, all reference to your existing files will break.

Default mode for directories

If during the installation, the installer complained about directory not having the right permissions set this to 0777 else you won't be able to delete the directories created by the script with your FTP client the day you will decide to uninstall the script.

Note: setting this option doesn't actually CHMOD your files or folders right now; instead it's being taken into account when coppermine creates new folders for user uploads (within the userpics directory). If you experience problems during initial Coppermine setup related to permissions, this option is not what you have been looking for or should change.

Default mode for files

If during the installation, the installer complained about directories not having the right permissions set this to 0666.

Note: setting this option doesn't actually CHMOD your files or folders right now; instead it's being taken into account when coppermine actually uploads pics to the webspace or creates intermediate sized pics and thumbnails. If you experience problems during initial Coppermine setup related to permissions, this option is not what you have been looking for or should change.

Back to top

4.12.9 Movie Playback Settings

Autostart

If set to YES, movies will instantly start playing when loaded (doesn't affect flash files though).

Back to top

4.12.10 User settings

Allow new user registrations

Define whether new users can self-register or not. If you set this to NO, only the admin can create new users and the "register" link won't be displayed in the navigation.

Allow unlogged users (guest or anonymous) access

When set to "No", unlogged users (i.e. guests or anonymous users) can not acces anything of your gallery except the login screen (and the registration screen if you allow registrations). You have to be aware that completely disabling anonymous access will decrease your site's popularity. Only use this if you need your gallery to be absolutely private. It's recommended to leave anonymous access enabled and use the more granular permissions by groups and albums instead.

[cpg1.4.0 or better required]

User registration requires email verification

If set to YES an email will be sent to the user that will contain a code to activate his account. If set to NO, user accounts become immediately active.

Notify admin of user registration by email

If set to YES an email will be sent to the gallery admin when a new user registers.

[cpg1.3.0 or better required]

Allow two users to have the same email address

Allow or prevent two users from registering with the same email address. Recommended setting is NO. This option is considered as deprecated and will possibly removed in future versions of coppermine.

Notify admin of user upload awaiting approval

When enabled, the gallery admin receives an email notification of all pics that wait for his approval (depends on the approval settings in "groups"). The email is sent to the address specified in "General settings".
This option is only recommended with low or medium traffic (if users only upload every now and then).

[cpg1.3.0 or better required]

Allow logged in users to view memberlist

When enabled, an additional menu item "Memberlist" is being displayed in the coppermine main menu if a user is logged in, to let him see a list of all users, with stats on their last visits, uploads and quota usage.
This is a new feature in cpg1.3.0 (user contribution by Jason) - it's available as mod (not in the regular coppermine package) for older versions than cpg1.3.0.

[cpg1.3.0 or better required]

Allow users to change their email address in profile

This option has impact on the user's profile page, it toggles wether the user can change his/her own email address.
Use this option wisely, as the old email address of a user is not recorded: if you let users change their email address, they might change it to a non-existing email address (e.g. after uploading some pics that break your gallery's rules) - you would have no chance of tracking this user.
This option will only be taken into account if you use Coppermine as a standalone application; if you run Coppermine integrated with a bbs, this option will simply not be taken into account, as the user profile from your bbs will be used to manage your user's profile.

[cpg1.4.0 or better required]

Number of failed login attemps untill temporary ban (to avoid brute force attacks)

To make brute force attacks (where a hostile script tries to log into coppermine as admin by running through all possible combinations of username and password automatically) less effective Coppermine temporarily bans the IP address of a possible attacker after a certain amount of failed logins. This way, the brute force attack would need way to long to try all possible combinations.
With this setting you specify the number of failed logins after that the IP address is temporarily banned.

[cpg1.4.0 or better required]

Duration of a temporary ban after failed logins

This value specifies the duration of the temporary ban (in minutes) after the number of failed logins specified with Number of failed login attemps untill temporary ban.

[cpg1.4.0 or better required]

Back to top

4.12.11 Custom fields for user profile (leave blank if unused). Use Profile 6 for long entries, such as biographies

These fields are displayed within the "user profile" area. They will appear only if you give them a name. As the heading says, use field 6 for long entries, such as biographies, or if you want to use bb code.

You can also use field 6 for avatars. To show an avatar in the profile, it should be entered in bbcode, for example to show 'avatar.gif', which is located in your images folder, use the code [img]http://www.yoursite.com/images/avatar.gif[/img]

Back to top

4.12.12 Custom fields for image description (leave blank if unused)

These fields are displayed within the "file information" area. They will appear only if you give them a name.

Back to top

4.12.13 Cookie settings

Name of the cookie used by the script

Default value is "cpg140". Even if you have multiple instances of the script running on the same server you can keep the default value.
When using bbs integration, make sure it differs from the bbs's cookie name

Path of the cookie used by the script

Default value is "/". Don't change this unless you know what you are doing. This may prevent you from logging in.

If you have broken your gallery by modifying this value, use phpMyAdmin to edit the xxxx_config table in your database and restore the default value.

When using bbs integration into Coppermine, make sure to use different cookie names for coppermine and your bbs! The paths in both applications have to be set so coppermine is able to read both. Usually the default value "/" should be set as path both for coppermine install and the BBS app you bridge with.

Back to top

4.12.14 Email settings

Usually nothing has to be changed here; leave all fields blank when not sure. Only if you run into problems (e.g. if ecards, registration info or notifications don't get sent) you should change these settings. Coppermine itself doesn't come with an engine to send mails, it relies on a webserver being able to do so (using the built-in mechanisms of PHP). If you're not sure what to enter, ask your webhost for support.

SMTP Host

The hostname of the SMTP server
If you leave this blank, sendmail (or a surrogate) will be used to send emails from your server. Sendmail exists on most Unix/Linux webservers. If you specify a SMTP hostname, Coppermine will try to send emails using SMTP (this usually is needed on Windows webservers).

[cpg1.4.0 or better required]

SMTP Username

The username needed to authenticate on the SMTP server (this is not your coppermine admin username).

[cpg1.4.0 or better required]

SMTP Password

The password that goes with above mentioned username (not identical to your coppermine admin password).

[cpg1.4.0 or better required]

Back to top

4.12.15 Logging & statistics

Like all logs (that record data that would get dropped if logging was disabled), the logging features of Coppermine will have a slight performance impact as well as an impact on webspace and database usage. You should make up your mind if you actually will need the logs before enabling the feature. A log is only helpfull if the admin actually looks into it.

Logging mode

Set, what kind of logging you want to enable. This feature records all changes that are done in coppermine's database, which is especially helpfull if you're trying to debug or if there are various admins on a gallery.
All log files are written in english

[cpg1.4.0 or better required]

Log ecards

When enabled, all ecards that are being sent are as well written into the database, where the coppermine admin can view them. Before switching this option on, make sure that logging is legal in your country. It is also advisable to notify your users that all ecards are being logged (preferrably on the registration screen).

[cpg1.3.0 or better required]

Keep detailed vote statistics

Enabeling this option records:

1. Each vote seperatly
2. IP Address
3. Referer
4. Browser
5. Operating System

Note: The total votes may not match if you enable details and do not reset the earlier votes.

Keep detailed hit statistics

Enabeling this option records:

1. Each vote seperatly
2. IP Address
3. Search Keyword, if the referer is Google, Yahoo! or Lycos search engines
4. Referer
5. Browser
6. Operating System

Note: The total hits may not match if you enable details and do not reset the earlier hits.

Back to top

4.12.16 Miscellaneous settings

Enable debug mode

CPG will show error messages which are normally suppressed. This is helpful in troubleshooting problems with your gallery or when asking for help on the CPG Support Forums. Turn this feature off if you don't experience problems.
Turn it on (option "Everyone") if you are requesting help on the coppermine support board, so the supporters can have a look at the debug output as well. Choose the option "Admin only" when trouble-shooting on your own - debug output will be only visible when you're logged in as admin, regular users or guests won't see the debug output.

Display notices in debug mode

May be helpfull to trouble-shoot problems with your coppermine install - only recommended if you know a little PHP and you can understand the additional error messages this option shows. This option only applies if debug mode is enabled.

Enable plugins

Enable plugins. This feature is brand-new, there's no documentation for it yet.

[cpg1.4.0 or better required]

Allow banning of non-routable (private) IP addresses

Usually most people on the internet have dynamic IP addresses assigned to them when connecting to the internet by their Internet Service Provider. These IP adresses change with each session users connect to the internet, but during an internet session these IP addresses are "visible" for the web-sites the user is surfing. From the range of all IP adresses (0.0.0.0 to 255.255.255.255), some ranges have been reserved for special purposes (mostly for the use on private networks). The banning feature won't accept IP adresses to be banned that belong to these private ranges (e.g. 192.168.0.1) to avoid unexperienced coppermine admins to ban IP addresses within their own LAN. If you're actually running Coppermine on your LAN/WAN that uses private IP addresses (e.g. on a company's intranet) and you want to be able to ban users, switch this option to "Yes". If you're running coppermine on a webserver located in the internet (e.g. you're webhosted), you should keep this option set to "No".
If you don't use banning at all, you can savely ignore this setting completely.

[cpg1.4.0 or better required]

Browsable batch-add interface

When batch-adding files (that you have uploaded by FTP before) to your gallery, you have the option to switch between a browsable list, where you can go through the directory structure in your albums-folder and to display the whole directory structure at once. Enable this option if you have a larger structure of directories and subdirectories you want to browse through (this requires your browser to be capable of displaying iframes). Set this option to "No" (disabled) if you want to use the "classic" coppermine interface that shows a complete list of the structure at once.
You can toggle this option on the batch-add page as well.

[cpg1.4.0 or better required]

Path to custom header include

Optional relative path to a custom header file. Using this option, you can include non-coppermine code bits to be included into your theme, e.g. an overall navigation that gets included on your whole website. You can only add a relative path (seen from the root path of your coppermine install) - not an absolute one, nor a http include from another website. This option is only meant for experienced users who have some PHP know-how.
Warning: you mustn't include full html pages that contain an html header or footer (tags like <head> or <body>), nor can the included file do file header manipulation, e.g. reading another (non-coppermine) cookie.

[cpg1.4.0 or better required]

Path to custom footer include

Optional relative path to a custom footer file. The same remarks apply as for the custom header include path.

[cpg1.4.0 or better required]

Enable reports

Enable reports. When set to yes, this allows users to report uploaded files or comments to the site admin.
This setting is dependant on e-cards being enabled. Only users who have permission to send e-cards in the 'groups' settings are able to send reports. The report icon is hidden from those not allowed to do so.

[cpg1.4.0 or better required]

Back to top

5. Integrating the script with your bulletin board

5.1 Available bridge files

Coppermine can be integrated with the following bulletin boards (eg. Coppermine and your bulletin board will share the same user database).

• phpBB 2
• Invision Power Board
• vBulletin
• YaBB SE
• Woltlab Burning Board 2.1
• SMF
• Mambo
• PunBB 1.1.5

5.2 Pre-requistes

5.2.1 Authentification by cookie

The login integration uses your bulletin board cookies, therefore it won't work if your board cookies are not visible by Coppermine. So unless you are an expert, keep things simple and install Coppermine and your bulletin board on the same domain. Examples :

Important: the cookie names of your bbs and coppermine must not be the same - they must differ!

5.2.2 Standalone version first

To avoid confusion, make sure to set up both coppermine and your bbs as standalone first. Make sure they both run correctly without integration. Test all features of coppermine (like upload, registration etc.) when Coppermine is installed, before you even start integration.

5.2.3 Coppermine users, groups and pics uploaded by users are lost when integrating

Warning: If you already have users and custom groups in your coppermine database when you enable bbs integration, be aware that they will be lost. If your coppermine users have already created private albums and uploaded pics to them, they will be lost as well!

5.2.4 Backup

Backup: it is very advisable to backup both your coppermine database and your files before enabling bbs integration, so you can savely go back if the integration fails.

In fact you're encouraged to backup your database on a regular base, and especially before applying code changes.

5.2.5 Keep Coppermine and bbs tables in the same database

It is recommended that you use the same database for your board and Coppermine (in fact it is even mandatory!).

5.3 Integration steps

From cpg1.4.x on you have two options to bridge your coppermine install with a third party application: you can either use the Bridge Manager that will provide a wizard-like interface to enable/disable bridging, or you can manually edit some coppermine files to accomplish integration. Using the Bridge Manager is the recommended method - you should only use the "manual integration" if the first option fails, or you know your way around in Coppermine pretty well.

5.3.1 Using the bridge manager

The bridge manager is a new feature in cpg1.4, it is not available in older versions. Instead of manually editing coppermine code files, you can enable/disable bridging in your browser, using a wizard-like user interface. To start the bridge manager, log in as admin, choose "Admin Tools" from the navigation and the "bridge manager"

If you run the bridge manager for the first time, there will only be one button that let's you actually start the wizard (if you return to the bridge manager later, you will also find a switch to enable/disable bridging) click it.

Note: with each step in the wizard, some information is being written to the coppermine database. Unlike other wizards (mostly on your local machine), the bridge manager doesn't have a ""cancel"-button! Once you have enabled bridging and everything is working fine, you shouldn't change any values just out of curiosity, as they will get written to the database, which might result in a bridging that used to work not working any more after "playing" with it.

In the first actual step of the wizard "choose application to bridge coppermine with", you have to choose the application you actually want to coppermine with. Note that you must have this application already installed on your webserver, it has to be properly configured and must be up-and-running. Don't use the bridge manager yet if you only plan to integrate coppermine with another application later.
If you have a custom-made bridge file that is not available in the wizard, choose the radio button in front of the text field and enter the name of your bridge file there, without the extension ".inc.php" (the bridge file must reside in the coppermine sub-folder "bridge").
Click "next"

The next steps depend on the application you have chosen to bridge with: some applications need URLs to be entered, or paths. Some need mySQL table information or cookie data to be entered, others don't. The point of the wizard is that it will only "aks" you the relevant settings for your application - if one or more items of the following description doesn't turn up for your application, there's no need to worry - just keep filling in the mandatory information and then hit "next". However, you have to understand that coppermine can proof-check only some of your input - some input goes unvalidated.
If a reset button () is being displayed next to an input field, the field value doesn't have the default value. It can be perfectly OK to have a non-default value in a field, however you should keep in mind that if you have "played" with the bridge manager before, previous settings might exist in a field that are not correct - do not light-heartedly skip a step without paying attention to it. Use the reset button to revert to the default value (not necessarily "quor" default value though).

5.3.1.1 choose application to bridge coppermine with

• Invision Power Board 1.x
• Invision Power Board 2.x
• Mambo server
• phpBB
• phpBB 2.2
• PunBB
• Simple Machines (SMF)
• vBulletin 2.3
• vBulletin 3.0
• Woltlab Burning Board 2.1
• YaBB SE

5.3.1.2 path(s) used by your BBS app

• Forum URL
  Full URL of your BBS app (including the leading http:// bit, e.g. http://www.yourdomain.tld/forum/)
• Relative forum path
  Relative path to your BBS app from the webroot (Example: if your BBS is at http://www.yourdomain.tld/forum/, enter "/forum/" into this field)
• Relative path to your BBS's config file
  Relative path to your BBS, seen from your Coppermine folder (e.g. "../forum/" if your BBS is at http://www.yourdomain.tld/forum/ and Coppermine at http://www.yourdomain.tld/gallery/)
• Cookie prefix
  this has to be your BBS's cookie name (not the cookie name of coppermine!)

5.3.1.3 database connection

• Database name
  Enter the name of the database your BBS app uses
• Database host
  Hostname where your mySQL database resides, usually "localhost"
• Database user account
  mySQL user account to use for connection with BBS
• Database passsword
  Passsword for this mySQL user account

5.3.1.4 database tables

• Table prefix
  Must match the prefix you chose for your BBS when setting it up.
• User table
  (usually default value should be OK, unless your BBS install isn't standard)
• Session table
  (usually default value should be OK, unless your BBS install isn't standard)
• Group table
  (usually default value should be OK, unless your BBS install isn't standard)
• Group relation table
  (usually default value should be OK, unless your BBS install isn't standard)
• Group mapping table
  (usually default value should be OK, unless your BBS install isn't standard)

5.3.1.5 BBS groups

• Use standard BBS usergroups
  Use standard (built-in) usergroups (recommended). This will make all custom usergroups settings made on this page become void. Only disable this option if you REALLY know what you're doing!
• Validating group
  The group ID of your BBS where users accounts that need validation are in (usually default value should be OK, unless your BBS install isn't standard)
• Guest group
  Group ID of your BBS where guests (anonymous users) are in (default value should be OK, only edit if you know what you're doing)
• Member group
  Group ID of your BBS where "regular" users accounts are in (default value should be OK, only edit if you know what you're doing)
• Admin group
  Group ID of your BBS where admins are in (default value should be OK, only edit if you know what you're doing)
• Banned group
  Group ID of your BBS where banned users are in (default value should be OK, only edit if you know what you're doing)
• Global moderators group
  Group ID of your BBS where global moderators of your BBS are in (default value should be OK, only edit if you know what you're doing). Keep in mind that Coppermine doesn't have moderator privileges, so your board's moderators will be "regular" users in Coppermine.

5.3.1.6 BBS-specific settings

• phpBB version (logout flag)
  What's your BBS version (this setting specifies how logouts are being handled)
• Use post-based groups?
  Should the groups from the BBS that are defined by the number of posts be taken into account (allows a granular permissions management) or just the default groups (makes administration easier, recommended). You can change this setting later as well. This setting currently only applies to SMF.

5.3.1.7 enable/disable BBS integration

This is the last step of the bridge manager - it summarizes up the settings you have made in previous steps - you can enable or disable integration here. By default, integration is set to "disabled" after the bridge manager has been run for the first time. You should only enable integration if you're sure your BBS app is set up correctly. Click the "Finish" button in any case to finally write to the database, even if you choose to keep the current settings (leaving integration "disabled").

• Enable integration/bridging with XXX

[cpg1.4.0 or better required]

Back to top

5.3.2 Recover from failed bridging

If you have provided improper settings using the bridge manager, your integration might fail, resulting (in the worst case) in a stituation where bridging is enabled, but you can not log in as admin to switch it off again (e.g. if you provided improper cookie settings that stops authentification to work). For this situation a recovery setting was built into the bridge manager: if you are not logged in as coppermine admin (in fact: not logged in at all) and you access the URL of your bridge manager (http://yourdomain.tld/your_coppermine_folder/bridgemgr.php) by entering it manually into the address bar of your browser, you are prompted to enter your admin account details - use the admin account you used to install coppermine with in the first place (the standalone admin account). This will not log you in, but switch integration off, so you can fix improper bridging settings then. To avoid others trying to guess your admin account details, there's a login treshold that rises every time you enter wrong credentials, so enter your admin account details with care.

[cpg1.4.0 or better required]

Back to top

5.3.3 Manual integration

5.3.3.1 Check your bbs settings

You will also need to perform the following operations after having unpacked the archive on your harddrive and before uploading the files to your webserver:

• If you are using phpBB 2, go to the admin control panel and check that "Cookie domain" corresponds to your domain, "Cookie name" is "phpbb2mysql" and "Cookie path" is "/".
• If you are using Invision Power Board, go to the "admin control panel / board settings / cookies" and check that all fields are blank. If they are not, you modified the default values and you are an expert.
• If you are using vBulletin, go to the "admin control panel / vBulletin options / HTTP Headers and output" and check that the value for "Cookie Domain" corresponds to your domain and that "Path to save cookies" is "/"

5.3.3.2 Edit your bridge file

Go to the bridge directory and open the file that corresponds to the bulletin board you use (eg. phpbb.inc.php if you use phpBB) with a text editor.

At the beginning of the file there are a number a configuration values that need to be set. For phpBB as an example they are the following :

// database configuration
define('PHPBB_DB_NAME','phpBB');     // The name of the database used by the board
define('PHPBB_BD_HOST','localhost'); // The name of the database server
define('PHPBB_DB_USERNAME','root');  // The username to use to connect to the    database
define('PHPBB_DB_PASSWORD','');      // The password to use to connect to the database

// The web path to your phpBB directory
// If your URL to your board is for example 'http://yoursite_name.com/phpBB2/',
// you'll have to set the below var to '/phpBB2/'.
define('PHPBB_WEB_PATH', '/phpBB2/');
// Logout Flag
// the value of this boolean constant depends on your phpBB version:
// If your version of phpBB is 2.0.4 or lower - change the value to FALSE;
// if your version of phpBB is 2.0.5 or newer - leave it as TRUE
define('PHPBB_LOGOUT_GET', TRUE);

Modify them according to the configuration of your board and save the file.

5.3.3.3 Enable bbs integration

Edit the file include/init.inc.php. At the beginning of the file you will find the following lines :

// User database integration
// Uncomment the applicable line if you want to use it
// define('UDB_INTEGRATION', 'phpbb');
// define('UDB_INTEGRATION', 'invisionboard');
// define('UDB_INTEGRATION', 'vbulletin23');
// define('UDB_INTEGRATION', 'vbulletin30');
// define('UDB_INTEGRATION', 'yabbse');
// define('UDB_INTEGRATION', 'smf');
// define('UDB_INTEGRATION', 'woltlab21');
// define('UDB_INTEGRATION', 'mambo');
// define('UDB_INTEGRATION', 'punbb');

Un-comment the line that corresponds to the bulletin board you use (eg. remove the "//" that are at the beginning of the line)

define('UDB_INTEGRATION', 'phpbb');

5.3.4 Special steps depending on the bbs you use

Important: if you use phpBB or PunBB, you'll have to do this additional steps

5.3.4.1 For phpBB only

Create a new file named cpg_redir.php in your phpBB directory, and paste the following code into the file:

<?php
if (!$_SERVER['HTTP_HOST']) {
  $cpg_host=$_SERVER['HTTP_HOST'];
} else {
  $cpg_host=$_SERVER['HTTP_HOST'];
}
$cpg_path='/gallery';
header("Location: http://".$cpg_host.$cpg_path);
exit;
?>

Important - before you save the file, you must ensure that:

• $cpg_path - contains the the path in which Coppermine is installed
• $cpg_host - contains the domain pointer to Coppermine. If Coppermine and phpBB are installed on the same server and domain (the "normal" case), you should leave the default value. Otherwise you should provide a string constant which contains the domain where Coppermine is installed (for example: 'www.my-other-domain.com').
• If you change both variables make sure that either $cpg_host contains a trailing slash or $cpg_path contains a leading slash. In other words, the concatenation of the two variables must result in a correct path such as www.my-other-domain.com/my_gallery_dir

5.3.4.2 For PunBB only

Create a new file named redir.php in your PunBB directory, and paste the following code into the file:

<?php

/// Set URL of coppermine to return to after login
$cpg_url = 'http://www.yousite.com/coppermine';

if (isset($_POST['redir'])){
        echo '<html>
                  <body onload="document.redir.submit();">
                      <form name="redir" method="post" action="'.$_POST['redir'].'">
                      </form>
                  </body>
              </html>';
} else {
        header("Location: $cpg_url");
}
?>

• $cpg_url - contains the the path in which Coppermine is installed

5.3.5 Upload the modified files

Upload all modified files (the file in the "bridge" folder that corresponds to your bbs and the file include/init.inc.php, plus the redirector files your created in step "Special steps for depending on the bbs you use" if you're using one of the mentioned bbs) onto your webserver. Visit your coppermine gallery in your browser. To login as an admin, you will need to use the admin username and password of your board.

5.3.6 Synchronsising the bbs groups with Coppermine's groups

Login using the admin account of your board. Go to the gallery, enter admin mode and click on the "Groups" button. This will synchronize Coppermine groups with those of your board. The permission you will see for each group will be completely messy, so take some time to set them properly.

Each time you add or delete a group in your board you will need to do the operation above in order to keep the synchronisation of the groups.

When you will try to login / logout or manage users from Coppermine, you will be redirected to the corresponding page of your bulletin board. Once the login or logout is performed you won't be redirected automatically to the gallery because your board does not have any function for that. It's up to you to add a link on your board to get you back to the gallery.

Back to top

6. Translating Coppermine into other languages

Coppermine has a separate language file that make the translation of the script much more easy. The language files are stored in the lang directory. The files with the utf-8 suffix are unicode encoded files. They are automatically generated with the iconv program so there is no need for you to make an unicode version of your translation.

If you select an utf-8 language file as the default one, then the script will be able to automatically select a language file based on the visitor browser configuration. For instance if the default language file is danish-utf-8 and an english visitor access your gallery, the english-utf-8 language file will be used by the script.

If you have translated Coppermine into a language not already supported, please read the translator's guide and visit the Coppermine Web Site at Sourceforge and follow the instructions for submitting your language.

Back to top

7. Known Issues

The following slight quirks and tiny issues are known and will be fixed in future releases.

• Some small text items are only available in English, e.g picEditor. (Language issue)
• Documentation (this document) and FAQ still incomplete.
• The arrows used for navigation from one pic to the other display in the wrong order for rtl-languages
• As you're currently using the alpha version of coppermine 1.4, there are several more known issues that are being discussed in the CPG 1.4 Testing/Bugs board. Please refer to the board for details.
• If you are running an xhtml compliant theme, the following items will not validate;
• The full-size pop-up in displayimage.php.

Back to top

---

8. Credits

8.1 Coppermine team

Developer	Username	Role/Position	Status
Aditya Mooley	Aditya	Developer	active
Clive Leech	casper	Supporter	active
Maarten Hagoort	DJ Maze	Developer (nuke team)	active
Eyal Zvi	EZ	Developer	active
Joachim Müller	gaugau	Project Manager	active
Scott Gahres	gtroll	Developer (nuke team project manager)	active
Jack	datajack	Developer	active
Dave Kazebeer	kegobeer	Support Technician	active
Tommy	Nibbler	Supporter	active
Jay Hao-En Liu	Oasis	Developer	retired
Christopher Brown-Floyd	omniscientdeveloper	Developer	active
Timothy	skybax	Developer	active
Dr Tarique Sani	tarique	Lead Developer	active
Thu Tu	TranzNDance	Supporter	active
DJ Axion	djaxion	Developer	retired
Grégory Demar	Greg	Developer, Original creator of Coppermine	retired
Hyperion	hyperion01	Developer	retired
John Asendorf	jasendorf	Developer	pending
mitirapa	mitirapa	Porter (Cross Platform Devel.)	retired
Moorey	moorey	Web Designer	pending
David Holm	wormie_dk	Developer	pending
Mark Zerr	zarsky99	Tester	retired

Back to top

---

8.2 Contributors

DaMysterious	DaMysterious has created loads of fantastic themes for Coppermine
Nanobot	Doug has done the vBulletin v3 bridge file
Girish Nair	Girish has contributed to the film strip feature
Jason Kawaja	Jason did the memberlist hack

Back to top

---

8.3 Coppermine uses code from the following free softwares :

phpBB
Author: phpBBGroup
URL: http://www.phpbb.com/


phpMyAdmin
Author: phpMyAdmin devel team
URL: http://www.phpmyadmin.net/


phpPhotoAlbum
Author: Henning Støverud
E-mail: henning AT stoverud DOT com
URL: http://www.stoverud.com/PHPhotoalbum/


DOM Tooltip 0.6.0
Author: Dan Allen
E-mail: dan AT mojavelinux DOT com
URL: http://www.mojavelinux.com/forum/viewtopic.php?t=127
Note: DOM Tooltip, which is being used with the theme "styleguide" only, is released under LGPL


TAR/GZIP/ZIP Archive Classes
Author: Devin Doucette
E-mail: darksnoopy AT shaw DOT ca


phpExifRW
Author: Vinay Yadav (vinayRas)
E-mail: vinay AT sanisoft DOT com
URL: http://www.sanisoft.com/phpexifrw
Note: phpExifRW is a pure PHP class to read, write and transfer EXIF information that most of the digital camera produces. It is released under LGPL


Codelifter Slideshow
URL: http://www.codelifter.com


HTML Mime Mail class
Author: Richard Heyes
E-mail: richard AT phpguru DOT org
URL: http://www.zend.com/codex.php?id=103&single=1


PHP Calendar Class Version 1.4
Author: David Wilkinson
E-mail: davidw AT cascade DOT org DOT uk
URL: http://www.cascade.org.uk/software/php/calendar/


Back to top

---

8.4 Copyright and disclaimer

This application is opensource software released under the GPL.

Because the program is licensed free of charge, there is no warranty for the program, to the extent permitted by applicable law. Except when otherwise stated in writing the copyright holders and/or other parties provide the program "as is" without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the quality and performance of the program is with you. Should the program prove defective, you assume the cost of all necessary servicing, repair or correction.

Coppermine Photo Gallery is Copyright © 2002 - 2004 Grégory DEMAR and the Coppermine Dev Team, All Rights Reserved.


Back to top

---