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

Table of Contents

The gallery configuration page

This is where you will configure the most important parts of your coppermine gallery. Some settings have an impact on the files you upload - changing those options after you have alreaded added a large number of files in your gallery can be a difficult undertaking. For this reason, it is important that you spend time with your coppermine setup at the early stages of gallery development to get those settings exactly the way you want them, before actually uploading too many pics or listing the gallery to the general public.

Most config option fields have a checkbox at the very right that allows you to reset that option to the default (or rather: recommended) option. This checkbox will only be displayed if your setting differs from the default or if there is no particular default setting (there can for example not be a default admin email address, as this entirely depends on your server setup) and if you have enabled the config option "Display reset boxes in config".

Please note that the config page does not contain all coppermine options - some options are being assigned per group, so you will find them on the groups control panel.

General settings

Gallery name

Default value: n/a
Recommended value: n/a
Importance: mandatory
Database record name: gallery_name
: General settings → Gallery name

Enter the name of your gallery in this text field. The name you enter will appear as the title that is displayed in the web browser's title bar and is also displayed in many of the different theme templates.

Even if you have removed the corresponding placeholder token from your custom theme, you should fill this in correctly, as it will be used when sending ecards and in all kinds of emails sent from your gallery (e.g. during registration).

It's mandatory to populate this field properly.

Example: Tim's incredible picture gallery

If you have absolutely no idea what to enter into this field, just enter your gallery's URL - that's better than nothing. It's definitely not an option to leave the default value - when the form is being submit with the default placeholder string Your gallery name here in place, there will be a warning message that explains that you must populate this field properly.


Gallery description

Default value: n/a
Recommended value: n/a
Importance: mandatory
Database record name: gallery_description
: General settings → Gallery description

Enter a short description of your gallery in this text field. This description is also displayed in some of the theme templates just below the name of your gallery.

Similar to the Gallery name field, the Gallery description field needs to be populated, even if your custom theme doesn't show that tag and even if you don't want to display that tag on your site: the field mustn't be empty and it mustn't be the default.


Gallery administrator email

Default value: n/a
Recommended value: n/a
Importance: mandatory
Database record name: gallery_admin_email
: General settings → Gallery administrator email

All emails sent by the gallery will be sent using this email address. This must be a valid email address.

Coppermine will use this address as "from"-address when sending emails (e.g. during registration). It's mandatory to have this email address populated properly. If you have your own domain, it might be a good idea to use an email account that correlates to your domain name.

Example: if your domain name is "example.com", you should create an email address named gallery@example.com and use that email address in coppermine's config. Coppermine does not create that email address for you!

Users sometimes ask on the support board if they can use another email, e.g. one from a freemail provider like GoogleMail, Hotmail or similar. The answer is: we can't tell you if your webhost will allow you to do this. Many webhosts disallow such things for reasons of spam prevention. Just keep in mind what the email address will be used for: the webserver will use that email address to send emails from. If you're not sure, ask your webhost for support.

This email address must not be confused with the email address that correlates to the email address of the gallery administrator's user account. Those email addresses can be identical, but they don't necessarilly have to.


URL of your coppermine gallery folder

Default value: n/a
Recommended value: n/a
Importance: mandatory
Database record name: ecards_more_pic_target
: General settings → URL of your coppermine gallery folder

This is the URL where a user will be directed to when s/he clicks on the "See more pictures" link in an e-card. This must be the URL to the root of your coppermine installation followed by a forward slash (just the path to your coppermine folder, e.g. http://yourdomain.tld/coppermine/). Do not specify a specific file (such as index.php) or subfolder within the coppermine gallery in this field.

In previous versions of Coppermine, this field was called "Target address for the 'See more pictures' link in e-cards", but as this url is now being used for other functions in coppermine, it has been changed, appropriately.

It is absolutely mandatory that you enter the gallery URL setting properly - if you don't, you will almost certainly experience "funny" behaviours of your gallery.


URL of your home page

Default value:
Recommended value: n/a
Importance: optional
Database record name: home_target
: General settings → 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's default starting page, or any other valid URL. By default this is "index.php".


Allow ZIP-download of favorites

Default value:
Recommended value:
Database record name: enable_zipdownload
: General settings → Allow ZIP-download of favorites

When enabled, users of your site may download files that they previously saved into their favorites collection. These files are dowloaded from the user's "My favorites" page and saved onto their computers in a zip-file format. This option requires zlib to be installed on your server (run phpinfo to check if this php library file exists on your server).

Warning: the creation of zip-archives on the server is a resources-intensive process that can overload your server pretty fast. In fact, the same server-sided limitations that apply to uploading (e.g. memory consumption) must be taken into account as well when enabling the zip download feature. It is very likely that this feature will stop working when trying to create a zip archive out of a larger number of entries in the visitor's "my favorites" meta album.

You have the options to disallow the zip-download of favorites completely or to allow it. If you choose to allow it, you can determine if you want a readme file to be included within the zip archive that explains where the archive has been downloaded from.

Default (and recommended) option is "off".


Timezone difference relative to GMT

Default value:
Recommended value: n/a
Minimum:
Maximum:
Importance: optional
Database record name: time_offset
: General settings → 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.


Enable help-icons

Default value:
Recommended value:
Database record name: enable_help
: General settings → Enable help-icons

Enables the display of help icons in various sections of the coppermine admin pages. When enabled, make sure you have also uploaded the "docs" folder into your coppermine folder on your webserver.

If you choose to set this to "Yes: everyone", logged in (registered) users will be able to see the help icons in strategic locations as well, e.g. when creating a user gallery.

As the help text is based on the documentation that comes with coppermine, it is not available in all languages. If the native language of your user(s) is not among the number of translated documentations, it is advisable to set this option to "Yes: admin only" to avoid confusion among your users.

It is strongly recommended that you do not disable the help icons altogether: even though you feel that you know your way around in your Coppermine install, the help icons might help you with the functions of a new or unfamiliar option later.


Enable clickable keywords in search

Default value:
Recommended value:
Database record name: clickable_keyword_search
: General settings → Enable clickable keywords in search

When enabled, a list of all keywords entered in the "Edit files" page will appear at the bottom of the search page, with each keyword being a clickable search link. Enabling this option is recommended only if you have a small number of keywords in use (e.g. less than 100) - it will provide your users with some ideas as to what they could be searching for in your gallery (in addition to the standard full-text search). Please note that enabling this option for a large list of keywords (e.g. thousands of keywords) can slow down the search page considerably and may be confusing for new users and visitors to your site.


Keyword separator

Default value:
Recommended value:
Available options: (" ")
(",")
(";")
Database record name: keyword_separator
: General settings → Enable clickable keywords in search

For an image or a file, you can specify keywords that describe it. Choose a character here to separate keywords. Do not choose a character you want to include in a single keyword. If you only want single-word keywords, you can safely choose a space. If you want multi-word keywords, choose a different character. The safest option is the semicolon because that is seldom used in a keyword.

The default keyword separator for new installations of Coppermine 1.5 is the semicolon. For upgrades from Coppermine 1.4 or earlier, the space is retained as the keyword separator. You can convert the keyword separator for current keywords to another value by using the tool on the Admin Tools page.

Warning: do not change the keyword separator on the configuration panel if you have keywords in your gallery already. Use the "Convert keyword separator" tool on the Admin Tools page to convert current keywords and set the new keyword separator at the same time.

For example, if you want to have the keyword "Washington, George" as one keyword, choose a semicolon to separate keywords. Then an appropriate set of keywords for a photograph of Mount Rushmore would be "Washington, George;mountain;South Dakota" which has 3 keywords separated by semicolons.


Enable plugins

Default value:
Recommended value:
Database record name: enable_plugins
: General settings → Enable plugins

Enable or disable plugins, with a link to the plugin manager. This feature allows advanced copperminers to create plug-ins that can control the way coppermine looks and behaves without modifying the inherent code of the script itself. There are many exciting, user-contributed, plug-ins available on the Coppermine forum. More details can be found in the plugins section of this documentation. Since plugins add on to the core Coppermine system, if you are having problems, try to disable all plugins using this setting to see if a plugin may be at fault. If so, you can then enable all plugins here, then uninstall or install one plugin at a time in the plugin manager to figure out which one is at fault.


Browsable batch-add interface

Default value:
Recommended value:
Database record name: browse_batch_add
: General settings → Browsable batch-add interface

When batch-adding files (that you have uploaded using a FTP before) to your gallery, you have the option to switch between a browsable list, where you can scroll through the directory structure in your albums-folder, or 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.
Should you have difficulties using one, try the other. You can toggle between these options on the batch-add page as well.

Process concurrency for batch-add interface

Default value:
Recommended value:
Minimum:
Maximum:
Database record name: batch_proc_limit
: General settings → Process concurrency for batch-add interface

When batch-adding files (that you have uploaded using a FTP before) to your gallery, Coppermine will process multiple images at the same time. This makes the process a lot faster, and avoids timeouts commonly associated with long running scripts. This setting specifies the maximum number of images Coppermine should process concurrently. To force images to be processed one by one you can set this to 1. If you have a powerful dedicated sever then you can set this to match the number of processing cores available. The default of 2 should strike a good balance between speed and processor usage.

In versions of Coppermine prior to 1.5 this option was not available, and the number of images processed at the same time depended on server and browser settings that were not easily controlled by a gallery administrator.

Display preview thumbnails on batch-add interface

Default value:
Recommended value:
Database record name: display_thumbs_batch_add
: General settings → Display preview thumbnails on batch-add interface

When enabled, preview thumbnails are being displayed on the batch-add screen. The preview thumbnails are good to figure out what files to actually add to an album when batch-adding files. If you always add all files within a folder to an album anyway, it's safe to turn this feature off, which will lead to faster page loads of the batch-add screen. This feature will not save webspace nor does it have an impact on the thumbnail creation - it just gives more information on the batch-add screen, that's all.
You can toggle between these options (enabled or disabled) on the batch-add page as well.

When starting with your gallery, you should leave this option enabled until you're convinced that batch-adding works as expected. You can then turn this option off. If you later discover that something goes wrong with your uploads, re-enable this feature once more.

Lifetime of the form tokens

Default value:
Recommended value:
Minimum:
Maximum: (one week)
Database record name: form_token_lifetime
: General settings → Lifetime of the form tokens

This option will set the lifetime of the form tokens in seconds. Don't set this value too low as it could interupt with large uploads (default is 15 min). Also keep in mind that it could take some time entering a lot of data (title, description, keywords) after you uploaded several files. If you exceed the lifetime of the token, you won't be able to submit the form and all entered data is lost. That applies to all forms (and some links) in Coppermine!

Form tokens were introduced into cpg1.5.x to fight the Cross-Site Request Forgery potential that existed in previous versions and that lead to the removal of the bbcode tags [img] and [url] back in cpg1.4.21
Think of the form token as an additional check of a link or a form that is performed to make sure that the link's origin hasn't been tampered with.

Back to top

Language & Charset settings

This the the config section where you can set up the language settings. Make sure to read this section carefully before changing anything here.

All language files are stored in the lang directory on your server.

Languages and internationalization (often refered to as i18n) is a complicated and complex thing. You (as Coppermine admin) probably don't want to go into details, so this documentation skips the in-depth issues existing with i18n and just gives you an overview how Coppermine handles languages.

Default Language

Default value:
Recommended value: n/a
Available options: all language files that are being represented by a file inside the lang-folder
Database record name: lang
: Language & Charset settings → Default Language

This sets the default language for your gallery.

Next to this selector, you will find a link to the language manager that allows a more granular control over the language files available and how the gallery should use them.


Autodetect language

Default value:
Recommended value:
Database record name: language_autodetect
: Language & Charset settings → Autodetect language

If enabled, Coppermine will try to determine the language of the site visitor based on the language preference settings in the visitor's browser. If the detected language exists as language file for coppermine, that language will be used for the particular visitor. If the language detection doesn't yield a result, the default language set up in Config will be used instead.

Recommended setting is "Yes".

Details on how Coppermine handles languages can be found in the section Languages of the docs


Character encoding

Default value:
Recommended value:
Available options:

















Database record name: charset
: Language & Charset settings → Character encoding

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

Don't change this from Unicode to anything else if you're not absolutely sure about the impact this will have!

Once you have added comments or files to your gallery, you should not change the character set of your gallery. If you do so, non-ASCII characters may not display properly and your database's textual content will become a mixture of encodings that will be very hard to detangle.

To make this absolutely clear: Coppermine should be run with the character encoding set to Unicode (utf-8). The Coppermine developers believe that it's the best available solution for i18n by far. Setting your encoding to something else just because you believe that to be the correct encoding for your particular language is almost certainly a step into the wrong direction. If you have encoding issues, ask your question before changing this setting from Unicode to anything else.


Back to top

Themes settings

Theme

Default value:
Recommended value: n/a
Available options: the list is being populated dynamically, based on the folder names that exist within the themes folder. Out of the box, the list default themes that ship with Coppermine are displayed.
Database record name: theme
: Themes settings → Theme

Use this dropdown list to select the default theme for your gallery (Themes are stored in sub-directories of the themes directory ). Click here for more information.

Themes can be selected individually for each user, as the individual selection is being stored in a cookie. That's why you (as admin) can test a particular theme without making it the default for all visitors of your gallery - just add the theme as URL parameter (see Creating your custom theme → Tipps & tricks). The theme dropdown list on the config screen will set the selected theme as default theme for all visitors of your site. Usually, your visitors are not aware of your gallery's capabilities to use individual themes nor do they know what themes are available on your server (unless you have deliberately enabled the theme selector dropdown feature), so the change made by selecting a different theme will have an impact on all your visitors. You need to keep in mind though that the new default theme will not be taken into account on the very next page (i.e. if you have submit the config form), but only on all subsequent page visits (as the cookie setting will apply one page visit later). Additionally, individually-set theme preferences will override the default, so you (as admin) will not see the gallery using your default theme, but the one you selected using URL parameters. Clear your cookie or reset the theme preference (by using the name of a theme that doesn't exist) to use the default theme again.


Sidebar for users / guests

Default value:
Recommended value:
Database record name: display_sidebar_guest / display_sidebar_user
: Themes settings → Sidebar for registered users / Sidebar for guests

Determines wether a sidebar for browsers will be available for members of the admin group, registered users group and guest group.

The sidebar is a minimalistic interface to control your coppermine-driven gallery. Think of it as a sort of snap-in for your favorite browser. If you enabled the sidebar, the control structure of your gallery (with all categories/subcategories and albums) will be available in a separate panel in the browser for faster navigation.

It is recommended that you try this option first for the admin only: play with it and decide if it would be a helpful feature for your site's visitors. If yes, enable/promote the sidebar for the registered users and/or guests as well. It's up to you if you want to promote the usage of the sidebar by displaying a link to it in coppermine's menu or if you want to promote it by some other mechanism (e.g. by telling your users about it on a non-coppermine driven page of your website).

The sidebar is helpful for users who return to your page often. It provides an alternative method of browsing your gallery by displaying a tree structure of your categories, subcategories and albums. It is meant for advanced users who understand how their browser works.

The sidebar install screen tries to auto-detect the operating system and browser that the visitor is using and offers the corresponding option to install the sidebar (as those methods differ from browser to browser). Some browsers are capable of appearing as different browsers, which will make the auto-detection routine fail. Subsequently, there is an option on the install screen as well to skip auto-detection and make the visitor select his browser.

Group membership is being determined if a visitor is logged in or not: if he is not logged in, he is a member of the guest group and the corresponding option set up for guests (anonymous) is being taken into account. If the visitor is logged in, he is automatically a member of the registered group.

There are two independant config sections for granular permissions who can access the sidebar:

Members of the admin group can access the sidebar no matter what option you select.

Possible options for each of the above settings:

Make sure to set the sidebar options up so that they make sense: it is not a bright idea to allow guests to access the sidebar, but deny access to registered users; registered users would be "punished" for registering. It is advisable to test the sidebar feature thoroughly before allowing your visitors to access it.

How the sidebar is installed greatly differs from browser to browser. Sadly, the most complicated version is the sidebar for Internet Explorer, which is the most popular browser. In the past, it has been comparatively easy to add anything to IE's favorites and to come up with a "real" sidebar. However, as Microsoft had some bad press for releasing a browser with severe security holes, the options for developers to create a working sidebar that end users can add easily have been reduced deliberately by Microsoft when releasing patches for their browser and operating system. Therefore, you might have issues with the sidebar, depending on which version of Windows and IE you are using.

If you want to edit the text that explains the install of the sidebar, edit the file http://yoursite.tld/your_coppermine_folder/lang/yourlanguage.php with a plain text editor.


Custom menu link name

Default value:
Recommended value:
Database record name: custom_lnk_name
: Themes settings → Custom menu link name

Use this if you want to create a custom link that will appear in the menu. What you enter here will be the name of the menu link or button. Leave space blank if you do not have any specific use for it.


Custom menu link URL

Default value:
Recommended value:
Database record name: custom_lnk_url
: Themes settings → Custom menu link URL

This is the URL where the user's browser will be directed to when s/he clicks on the "Custom link name" button in the main menu.

You can use any valid URL, i.e. a relative path from your webroot (starting with a lading slash), a relative path as seen from your Coppermine folder or a full URI (starting with the protocol - usually something like http://, followed by the domain etc.).

Leave this blank if you do not have any specific use for it.

The config settings "Custom menu link name" and "Custom menu link URL" are of course closely related: setting one without setting the other doesn't make sense; you either configure both or none of them. If you need more than this one custom link inside your menu you can not accomplish this using Coppermine's configuration only - instead, you will have to create a custom theme of your own and add a menu item to your custom theme's menu.


Enable menu icons

Default value:
Recommended value:
Database record name: enable_menu_icons
: Themes settings → Enable menu icons

When enabled, this option will display icons next to some menu items to allow an easier navigation. The performance penalty should be neglectible. Default (and recommended) option is "on". Available options are:

The menu icons are themeable, so there can be different icon sets with different themes.


Display bbcode help

Default value:
Recommended value: n/a
Database record name: show_bbcode_help
: Themes settings → Display bbcode help

When enabled, this will display the bulletin board codes that may be used in description fields to help with the formatting of text, images and links.


Path to custom header include

Default value:
Recommended value:
Database record name: custom_header_path
: Themes settings → 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.

For details on the include files, refer to the section Custom header and footer

Example

If your Coppermine install resides in http://yourdomain.tld/your_coppermine_folder/ and your include file is supposed to be http://yourdomain.tld/my_overall_navigation/my_custom_header.php, you need to specify ../my_overall_navigation/my_custom_header.php (the relative path to your include file, seen from the folder coppermine resides in) as "Path to custom header include".

The custom include files are an answer to the FAQ "How can I include Coppermine into an existing web site?": although the primary answer to the question is "You can't include Coppermine into another page by using the PHP commands include or require at all.". This looks like a contradiction in terms, but you need to see the idea behind this: everybody who has been using includes agrees that they can be an easy method to efficiently maintain a site without having to edit many files to accomplish only a minor change on all or many pages. You just need to figure this out differently: include your overall site's navigation into coppermine instead of trying to integrate coppermine into an existing site (because you can't do that for technical reasons).

Path to custom footer include

Default value:
Recommended value:
Database record name: custom_footer_path
: Themes settings → Path to custom footer include

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


Enable browsing by date

Default value:
Recommended value:
Importance: low
Database record name: browse_by_date
: Themes settings → Enable browsing by date

When enabled, another link in the sub_menu will appear named "By Date". When the user clicks on it, the calendar will open in a pop-up and will allow the user to view files uploaded at a certain date.


Display redirection pages

Default value:
Recommended value:
Database record name: display_redirection_page
: Themes settings → Display redirection pages

When enabled, there will be pages that tell the user if his action has been successful or not, with a link to continue to the next page. If disabled, the user will be redirected to the target page immediately without displaying the redirection page first, with the message displaying at the top of the page instead. Recommended (and default) setting is "No", as it then will need less clicks.

Example: if enabled, users will be sent to a page that says "comment added" after they have submit a comment. Only after clicking on continue they will be sent back to the intermediate image display (where they posted their comment in the first place). If this option stays disabled, the user will see a box at the top of the intermediate image screen that just says "comment added" after he submit his comment.

Promote usage of XP Publisher by displaying a corresponding link on upload page

Default value:
Recommended value:
Importance: low
Database record name: display_xp_publish_link
: Themes settings → Promote usage of XP Publisher by displaying a corresponding link on upload page

When enabled, there will be section on the upload screen that is meant to make your visitors aware of the fact that they can upload as well using the XP Publishing Wizard. The link will be displayed regardless of a user's permission to upload in the first place, so make sure to only display the promotional link if your users can actually use the publishing wizard in the first place.

Back to top

Album list view

Width of the main table (pixels or %)

Default value:
Recommended value:
Importance: high
Database record name: main_table_width
: Album list view → Width of the main table

The number you type in here becomes the default width of the display tables used on your main page or when you are viewing thumbnails of an album. You can enter the width in pixels or specify it in percentages. The default value is 100%.
Setting this to a ridiculously high value (i.e. above 100% or a pixel value higher than regular desktop resolutions) doesn't make sense and will lead to unexpected results.


Number of levels of categories to display

Default value:
Recommended value: (for larger galleries)
Minimum:
Maximum:
Database record name: subcat_level
: Album list view → 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. Setting this to "1" will result in not only the current category level to be displayed without sub-categories.


Number of albums to display

Default value:
Recommended value:
Minimum:
Maximum:
Database record name: albums_per_page
: Album list view → Number of albums to display

This is the number of albums to display on a page. If the current category contains more albums than what is allowed on the page, the album list will be split over multiple pages with tabs at the bottom of each album list table (pagination) that users can click on to advance to the next set of albums in a particular category.


Number of columns for the album list

Default value:
Recommended value:
Minimum:
Maximum:
Database record name: album_list_cols
: Album list view → Number of columns for the album list

This config setting should be pretty self-explanatory: it determines the maximum number of columns that the albums will be grouped in on the album list display.


Size of album thumbnails

Default value:
Recommended value:
Minimum:
Maximum:
Database record name: alb_list_thumb_size
: Album list view → Size of album thumbnails

This sets the maximum size of the thumbnails that are to be 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. Aesthetically, it is better to have thumbnails smaller than or equal to the Max width or height settings here.


The content of the main page

Default value:
Recommended value:
Importance: high
Database record name: main_page_layout
: Album list view → 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" to include other items:

Unless you really know what you are doing you should always keep catlist and alblist in "the content of the main page", as they make up the core parts of the index page or any gallery site, for that matter.

The ,2 dictates that cpg should display 2 rows of thumbnails.

Some example configurations:

There might be plugins that add more codes that can be used in this field.

You can not use a code more than once inside this field: a string like breadcrumb/catlist/alblist/breadcrumb will not work as expected and may have undesired side-effects.


Show first level album thumbnails in categories

Default value:
Recommended value: (for larger galleries)
Database record name: first_level
: Album list view → Show first level album thumbnails in categories

Use this setting to choose whether or not to display each category's album thumbnails below its row in the category list.

By default, this option is enabled. If your gallery grows and you get a larger number of categories, you might want to disable this option to make the index page look less cluttered.
Enabling this option will have the advantage that your visitors will need less clicks to reach the page that contains the pics they want to see. Drawback of this option is that your index page may look cluttered and will burn more resouces (CPU cycles), so you should disable this if you have issues with resources consumption.


Sort categories alphabetically (instead of custom sort order)

Default value:
Recommended value:
Database record name: categories_alpha_sort
: Album list view → Sort categories alphabetically

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


Show number of linked files

Default value:
Recommended value:
Importance: mandatory
Database record name: link_pic_count
: Album list view → Show number of linked files

If you use album keywords to display images/files in more than one album, enabling this option will display additional information for the album stats: if an album doesn't only contain "regular" files, but files linked via the "album keyword" option as well, the number of linked files will be displayed separately like this "3 files, last one added on Oct 07, 2004, 3 linked files, 6 files total".

Back to top

Thumbnail view

Number of columns on thumbnail page

Default value:
Recommended value:
Minimum:
Maximum:
Database record name: thumbcols
: Thumbnail view → Number of columns on thumbnail page for the album he is in

Default value is 4 this means that each row will show 4 thumbnails. There can be no general recommendation on the number of thumbnail columns you should use, as the optimal setting depends on your thumbnail width setting, the theme you use, the width of the main table and especially the display resolution of your site visitor.


Number of rows on thumbnail page

Default value:
Recommended value:
Minimum:
Maximum:
Database record name: thumbrows
: Thumbnail view → Number of rows on thumbnail page

If an album contains more files than the number that will fit on one thumbnail page ("Number of columns on thumbnail page" x "Number of rows on thumbnail page"), a pagination tab will be displayed that allows the visitor to jump to the next page of thumbnails.


Maximum number of tabs to display

Default value:
Recommended value:
Minimum:
Maximum:
Database record name: max_tabs
: Thumbnail view → 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. If the number of thumbnail pages is greater than the number set for "Maximum number of tabs to display", the "neighbouring" tabs will be displayed as well as the first and last tab.



Show dropdown list of all pages next to tabs

Default value:
Recommended value:
Database record name: tabs_dropdown
: Thumbnail view → Show dropdown list of all pages next to tabs

When the thumbnails spread over multiple pages, tabs are displayed at the bottom of the page. This setting will display a dropdown list of all pages so that users can access any page even if the page is not listed in the tabs displayed. To customize the display of tabs further, modify your theme's variable $template_tab_display and function theme_create_tabs.


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

Default value:
Recommended value:
Database record name: caption_in_thumbview
: Thumbnail view → Display file caption below the thumbnail

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

This setting can (as most settings) be overridden in a custom theme. If you should experience issues where your gallery doesn't seem to respect this setting, take a look at your current theme and make sure that there is no code in it that overrides this setting.


Display number of views below the thumbnail

Default value:
Recommended value:
Database record name: views_in_thumbview
: Thumbnail view → Display number of views below the thumbnail

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

It's recommended to turn this off if your gallery is not very busy and doesn't get many hits (which is usually the case for family galleries and similar), as it will not look very attractive to your visitors if the number of hits per file is low (or even zero).


Display number of comments below the thumbnail

Default value:
Recommended value:
Database record name: display_comment_count
: Thumbnail view → Display number of comments below the thumbnail

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

Turning this option on only makes sense if there is a lot of discussion and comments going on in your gallery. If you don't have many comments (or if you don't allow comments in the first place), leave this setting disabled.


Display uploader name below the thumbnail

Default value:
Recommended value:
Database record name: display_uploader
: Thumbnail view → Display uploader name below the thumbnail

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

Again, this setting only makes sense if your gallery is mostly community-driven and there is not just a single admin uploader, but the uploads come from many different visitors.


Display the file name below the thumbnail

Default value:
Recommended value:
Database record name: display_filename
: Thumbnail view → Display the file name below the thumbnail

Toggles the display of the file name below each thumbnail.

It's recommended to leave this option disabled, especially if you have no direct control over the file names (because you allow uploads by users). Better use the actual textual content (title and caption) features. If you have long file names that can not be wrapped, the file name displayed may be wider than the thumbnail, so the table cell that wraps the thumbnail and all text that relates to it may get much wider than expected, resulting in a distorted view of the table.


Display rating below the thumbnail

Default value:
Recommended value:
Database record name: display_thumbnail_rating
: Thumbnail view → Display rating below the thumbnail

Toggles the display of the rating results below each thumbnail.

Recommended (and default) setting is "off" unless your gallery's focus is on community-building and voting is a core feature for you.


Go directly from thumbnail to full-sized image

Default value:
Recommended value:
Database record name: thumbnail_to_fullsize
: Thumbnail view → Go directly from thumbnail to full-sized image

When enabled, this option sends the visitor directly from the thumbnail to the full-sized image pop-up, skipping the display of intermediate images.

It is not recommended to enable this option, because

This option has been added because a lot of coppermine users have asked for it. However, the dev team does not recommend using it.


Default sort order for files

Default value:
Recommended value:
Available options: ("ta")
("td")
("na")
("nd")
("da")
("dd")
("pa")
("pd")
Database record name: default_sort_order
: Thumbnail view → Default sort order for files

This option determines the default order in which thumbnails should be displayed. Your visitors can override this by selecting a custom sort order from the sort buttons above the albums (unless you have disabled that option in your custom theme).


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

Default value:
Recommended value:
Minimum:
Maximum:
Importance: mandatory
Database record name: min_votes_for_rating
: Thumbnail view → Minimum number of votes for a file to appear in the 'top-rated' list

Used to determine how many votes a file must receive before appearing as a "top-rated file.". If a file has received less than "this value" of votes, it will not be displayed in the "top-rated" page. This value must be greater or equal to 1.

Setting this to a high number is only recommended for busy sites with a lot of visitors. A higher number has the advantage that votes just by one individual won't boost up the relevance of a file to much, reducing potential rating fraud.

Back to top

Image view

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

Default value:
Recommended value:
Database record name: picture_table_width
: Image view → Width of the table for picture display

The minimum width of the table (in pixels or %) that will be used to display the intermediate picture.

Examples:

Recommended setting is "100%". When setting this to a value that doesn't make sense (over 100% or a silly absolute size in pixels), your gallery pages will look distorted and horizontal scrollbars will appear.

If you decide to use an absolute size in pixels, make sure that the value is equal or greater than "Max width or height of an intermediate picture".


File information are visible by default

Default value:
Recommended value:
Database record name: display_pic_info
: Image view → File information are visible by default

Define whether or not the file information block that appears below the intermediate image should be visible by default (If turned off, users can still view the info block by clicking on the ( i ) button.

Default setting: off. Recommended setting: on.


Display movie download link in the file information area

Default value:
Recommended value:
Database record name: picinfo_movie_download_link
: Image view → Display movie download link in the file information area

When enabled, a link will be displayed in the pic info section (that can be toggled by clicking the (i) button) that allows the visitor to download a movie. If the file displayed is not a movie, but another file type (e.g. an image), the download link will not be displayed.


Max length for an image description

Default value:
Recommended value:
Minimum:
Maximum:
Database record name: max_img_desc_length
: Image view → Max length for an image description

Maximum number of characters that an image description may contain.

It's advisable not to tamper with this setting unless you absolutely must. Note that this will not have an impact on the field size in the database, but only an impact on the business logic of Coppermine when a new image description is being added to the database. Allowing needlessly large numbers will encourage visitors with upload permission to actually have an influence on the design of your site by the sheer amount of text that they can enter.


Show film strip

Default value:
Recommended value:
Database record name: display_film_strip
: Image view → Show film strip

Toggles display of a "film strip" showing thumbnails of prior and subsequent files in the album.


Number of items in film strip

Default value:
Recommended value:
Minimum:
Maximum:
Database record name: max_film_strip_items
: Image view → Number of items in film strip

Sets the number of thumbnails to display in film strip. The number you can set here is dependent on your thumbnail size and monitor size. If you do not want to inconvenience users with smaller monitors set this value between 3-7.

It's recommended to use an odd number, so the thumbnail that represents the file actually viewed is being displayed in the center of the film strip. Default (and recommended) setting is 5.



Slideshow interval

Default value:
Recommended value:
Minimum:
Maximum: (15 minutes)
Database record name: slideshow_interval
: Image view → Slideshow interval

This sets the time that each pic is to be displayed (transition interval) when a user is viewing a slideshow (the next pic is being loaded/cached while the current one is being displayed). This setting must be in milliseconds (1 second = 1000 milliseconds).
Remember that setting this to a very low value may not be in the best interest for all of your users, especially those who are on dial-up connections, or if you have large files (in terms of file size) that may take longer than the allotted time to display.


Count hits in slideshow

Default value:
Recommended value:
Database record name: slideshow_hits
: Image view → Count hits in slideshow

When enabled, the hit counter will increase when a visitor views the slideshow as well. When disabled, the hit counter will only be increased if visitors browse your gallery using the regular navigation. This option may have a slight performance impact, don't enable it when your gallery is slow already. If you enable it, malevolent visitors may be tempted to effortlessly increase the view counter for a particular album or a set of files to make files appear more popular than they actually are.


Allow Flash in Ecards

Default value:
Recommended value:
Database record name: ecard_flash
: Image view → Allow Flash in Ecards

When enabled, you can not only send images as ecards, but flash files as well. This feature has been added because many users requested it. However, it is not recommended at all, simply because most email clients will not display Flash embedded into emails or (even worse) will show messages that may confuse the recipient.
You have to understand that this setting does not determine the ability of users to send ecards in the first place (this is being configured on the groups page instead). Only if a user is allowed to send ecards (i.e. belongs to a group that is allowed to do so), this setting is being taken into account.


Insert a transparent overlay to minimize image theft

Default value:
Recommended value:
Database record name: transparent_overlay
: Image view → Insert a transparent overlay to minimize image theft

When enabled, a transparent gif will be inserted "over" the pics displayed in your gallery (intermediate sized and full-size pics). Subsequently, if a user right-clicks the image and uses the "save as..." context menu of his browser, only the transparent gif will be saved on his PC, but not the actual image he tried to save. This option will reduce the number of users who are capable to steal your images, but it will only fool newbie users. There is no effective method to completely avoid image theft, but the transparent overlay method is much better than any no-right-click script that keeps users from the legitimate use of the right mouse button and subsequently makes them shy away. Please note that the transparent overlay is being added by using the deprecated HTML attribute "background" to avoid the context menu entry "save background image" that would appear if the overlay image was added using standards-compliant CSS methods. Subsequently, your pages will not contain valid, standards-compliant HTML output if this option is enabled.
Recommended (and default) setting for this option is "off".


Go back to old rating system

Default value:
Recommended value:
Importance: mandatory
Database record name: old_style_rating
: Image view → Go back to old rating system

If you want to use the old rating system instead of the new one, you have to check this option.
This will not allow you to set a custom amount of rating stars as it defaults back to 5


Amount of rating stars to be used to vote

Default value:
Recommended value:
Minimum:
Maximum:
Database record name: rating_stars_amount
: Image view → Amount of rating stars to be used to vote

Used to determine on what scale users will be able to vote. The number you set here will set the amount of rating-stars on the thumbnail page.

It's highly recommended not to change this at all.

Keep in mind that changing this option while you already have votes in your database may have undesired results. If you change this setting, you should reset all votes as well.


Back to top

Comment settings

To get a grasp how comments work in Coppermine it's recommended to read the documentation section "Comments" as well!

Filter bad words in comments

Default value:
Recommended value:
Importance: mandatory
Database record name: filter_bad_words
: Comment settings → Filter bad words in comments

Remove "bad words" from comments. The "bad words" list is in the language file. NOTE: Not all language files may contain an equivalent for this list.


Allow smilies in comments

Default value:
Recommended value:
Database record name: enable_smilies
: Comment settings → Allow smilies in comments

Toggle the use of smilies in comments.


Allow several consecutive comments for a specific pic/file from the same user

Default value:
Recommended value:
Database record name: disable_comment_flood_protect
: Comment settings → Allow several consecutive comments for a specific pic/file from the same user

This setting toggles flood protection for the comments option. When enabled, a user can post another comment, even though he already posted a previous one. Some users may abuse this setting. The recommended setting is: off (disabled).


Max number of lines in a comment

Default value:
Recommended value:
Minimum:
Maximum:
Database record name: max_com_lines
: Comment settings → Max number of lines in a comment

Prevent a comment for containing too many "new line" characters (enter key).


Maximum length of a comment

Default value:
Recommended value:
Minimum:
Maximum:
Database record name: max_com_size
: Comment settings → Maximum length of a comment

Maximum number of characters that an overall comment may contain.


Max number of characters in a word

Default value:
Recommended value:
Minimum:
Maximum:
Database record name: max_com_wlength
: Comment settings → Max number of characters in a word

This is designed to prevent someone from breaking the flow of your gallery layout by posting lengthy comments without using spaces between words. With this default value, "words" that longer than 38 characters are automatically censored. Allowing only comparatively small words reduce the benefit of comments for spammers as well, as they can not post deep links that have long URLs.


Notify admin of comments by email

Default value:
Recommended value:
Database record name: email_comment_notification
: Comment settings → 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 user traffic or you may soon find yourself flooded with notification emails.


Sort order of comments

Default value:
Recommended value:
Database record name: comments_sort_descending
: Comment settings → Sort order of comments

Changes the sorting order of comments made to a file.
Ascending: latest comment at the bottom, oldest comment at the top
Descending: latest comment at the top, oldest comment at the bottom


Comments per page

Default value:
Recommended value: n/a
Minimum:
Maximum:
Database record name: comments_per_page
: Comment settings → Comments per page

Changes the number of comments displayed per page.


Prefix for anonymous comments authors

Default value:
Recommended value:
Importance: mandatory
Database record name: comments_anon_pfx
: Comment settings → Prefix for anonymous comments authors

If you allowed anonymous comments (permissions set on the groups control panel), this prefix will be used for comments left by unregistered users. This can be helpful in preventing and identifing unregistered users posing as other registered users (or even an admininstrators) when leaving comments. Leave this blank if you do not want a prefix for guest's comments.


Comments require approval

Default value:
Recommended value:
Database record name: comment_approval
: Comment settings → Comments require approval

By default, comments don't require approval and are visible instantly. To fight the problem of comment spamming, you can require admin approval of comments posted by users. Comments will then not be visible instantly, but only after admin approval on the review comments screen. If you don't allow comments at all, this setting won't apply, so you can leave it as-is.

Options:

Please note:


Only display comments needing approval on the "Review Comments" page

Default value:
Recommended value:
Database record name: display_comment_approval_only
: Comment settings → Only display comments needing approval on the "Review Comments" page

With this toggle you can determine if the admin will see only the comments that actually need approval on the "Review Comments" page. You can toggle this option in config or on the actual "Review Comments" page - it won't hurt to toggle this setting frequently when reviewing comments.

This option does not have any impact on the visibility of comments, but only on the "Review Comments" page display.


Display placeholder text to end users for comments waiting for admin approval

Default value:
Recommended value:
Database record name: comment_placeholder
: Comment settings → Display placeholder text to end users for comments waiting for admin approval

When enabled, the non-admin end user will see a placeholder text saying Someone has posted a comment here. It will be visible after admin approval. instead of the comment. When disabled, the comment that needs approval will be completely invisible for the end user.

This setting is only being taken into account for non-admin users, so you won't notice any difference when being logged in as admin.


Allow users to edit their comments

Default value:
Recommended value:
Database record name: comment_user_edit
: Comment settings → Allow users to edit their comments

When enabled, users are allowed to edit or delete their comments after submitting them.

Note: this setting doesn't determine if users can actually post comments at all (this is instead being determined on the groups page). Instead, it just displays an edit and delete icon next to a comment that turns the comment into an input field when being clicked.
The admin is not affected at all - he can edit any comment no matter what.


Display Captcha (Visual Confirmation) for adding comments

Default value:
Recommended value:
Database record name: comment_captcha
: Comment settings → Display Captcha (Visual Confirmation) for adding comments

To prevent spam comments being posted by bots (automated scripts), this toggle will display an image next to the comment field with some random letters on it. The visitor is required to enter those letters into a textfield to prove that he's actually a human and not just some dumb bot that drops spam. It's recommended to enable Captchas for anonymous comments (guests who are not logged in).

Note: this setting doesn't determine if guests can actually post comments at all (this is instead being determined on the groups page).

Captchas will only work if GD2 is available on your server with FreeType support enabled.


Akismet API key

Default value:
Recommended value: n/a
Database record name: comment_akismet_api_key
: Comment settings → Akismet API key

Another method to fight comment spam is the option to filter all comments posted using Akismet. To use this feature, you need a valid Akismet API key. To get such a key, you need to sign up (for free) for small/non-profit pages on the Wordpress page to obtain an API key. If you plan to use Akismet on a commercial page, you need to purchase a professional API key on akismet.com/commercial/
After you got your API key by email you can paste it into this config field. You can not make up the API key, nor can you use someone else's API key.

Leaving this field empty will disable the usage of Akismet.

After entering your Akismet API key into the config field, go to the review comments page - at the bottom you will find a little info box that will display the number of comments that Akismet has blocked for you and a lookup field that displays the results of a connection attempt with the Akismet server using your Akismet API.

Please understand that the Coppermine group is not affiliated in any way to Akismet.com nor Wordpress: the Akismet service is provided by a third party. Terms and conditions of Akismet usage may change at a later stage - the Coppermine dev team doesn't have control over this service and can not be held liable in case something goes wrong in relation to Akismet. The Coppermine dev team just provides an interface within the application's code to allow you to process comments through Akismet.
Please do not ask questions how to get an API key on the Coppermine support board: both the Wordpress pages as well as Akismet.com provide documentation how to obtain an API key. Go to those pages to get your API key.

Find more details on the comments page of the documentation, particularly within the Akismet section of that page.


Akismet Options

Default value:
Recommended value:

These options will only be taken into account if you have entered a valid Akismet API key into the corresponding config field. It determines what should be done if Akismet rejects a comment as spam? Here's what the options do:


Apply Akismet for comments made by

Default value:
Recommended value:
Database record name: comment_akismet_group
: Comment settings → Apply Akismet for comments made by

You can specify if only the comments posted by anonymous visitors (guests) should be checked by Akismet or if all comments that get posted will be pumped through the Akismet filtering.

This toggle does not determine the ability of a registered user or guest to post comments in the first place. The overall switch for that purpose resides on Coppermine's groups control panel instead. The config option "Apply Akismet for comments made by" only applies if users or guests have permission to post comments in the first place.

This toggle will only be taken into account if you have entered a valid Akismet API key into the corresponding config field.

Default value is "Everyone", which is the more restrictive setting - it usually doesn't hurt to spam-check the posting of registered users as well, since some spammers take the time to register and then drop their spam comments as registered users if you let them.

The drawback of this option set to "Everyone" is a slightly increased traffic and (depending on the bandwidth of your webserver) a small penalty in the speed of comment processing - after all, the comments are being sent to a third party site first, where that remote server checks the comment and then returns information to your webserver wether a comment should pass or not. If your site is extremely busy or you have limited bandwidth on your webserver, you should set this option to "Guests only" to lighten the load.


Ask guests to log in to post comments

Default value:
Recommended value: n/a
Database record name: comment_promote_registration
: Comment settings → Ask guests to log in to post comments

When enabled, an explanation will appear at the bottom of the comment section for anonymous users (guests) that explains that they need to log in if they want to post comments. This is meant to promote registration, to explain to your site's visitors that they could interact even more if they registered.
Of course this message will only be displayed if you have disallowed guests to post comments in the first place (you do so on the group control panel). However, this switch does not take into account if there actually is a user group that is actually allowed to post comments at all, i.e. wether you have configured registered users to post comments. If you don't allow registered users to post comments, then don't enable this option.

Back to top

Contact form settings

Settings that determine if the contact-form is available. Make sure that sending emails from Coppermine works in the first place before enabling the contact form.

Display contact form to anonymous visitors (guests)

Default value:
Recommended value:
Database record name: contact_form_guest_enable
: Contact form settings → Display contact form to anonymous visitors (guests)

Toggles wether the link to the contact form will be displayed in the menu and wether guests (visitors of your gallery who are not logged in) can use the contact form.

Possible options:

If disabled, the below options that apply to guests using the contact form will not be taken into account.


Display sender-name field for guests

Default value:
Recommended value:
Database record name: contact_form_guest_name_field
: Contact form settings → Display sender-name field for guests

When enabled, the visitor (guest) using the contact form will be allowed to enter his name.

Possible options:


Display sender-email field for guests

Default value:
Recommended value:
Database record name: contact_form_guest_email_field
: Contact form settings → Display sender-email field for guests

When enabled, the visitor (guest) using the contact form will be allowed to enter his email address.

Possible options:


Display contact form to registered users

Default value:
Recommended value:
Database record name: contact_form_registered_enable
: Contact form settings → Display contact form to registered users

Toggles wether the link to the contact form will be displayed in the menu for registered users and wether your users (visitors of your gallery who are logged in) can use the contact form.

Possible options:


Subject line for emails generated by contact form

Default value:
Recommended value: n/a
Database record name: contact_form_subject_content
: Contact form settings → Subject line for emails generated by contact form

Subject line for the emails generated by the contact form. Will be put in front of the custom subject line the user can enter (if "Display subject field" is enabled).


Display subject field

Default value:
Recommended value:
Database record name: contact_form_subject_field
: Contact form settings → Display subject field

When enabled, the visitor (guest or registered user) using the contact form will be allowed to enter a subject line.

Possible options:


Use the sender's email address as "from"-address

Default value:
Recommended value:
Database record name: contact_form_sender_email
: Contact form settings → Use the sender's email address as "from"-address

When enabled, the sender's email address will be used to send the email (if applicable, i.e. if a valid email exists). This is helpful in terms of comfort, as you can use your email app's reply functionality. The drawback may be issues with the emails not being delivered properly, as you can't be sure that the user has entered his actual email address. Additionally, your webserver's mail server may be configured to only allow certain email addresses in the from field. Anti-spam mechanisms may be in place that validate the domain part of the from-field and only accept emails when the domains of the mail server and the from field match. Subsequently, use this option with care and test it througly before making using it "live".

Recommended (fail-safe) setting is "off".


Back to top

Thumbnail settings

Use dimension

Default value:
Recommended value:
Available options: ("any")
("ht")
("wd")
("ex")
Database record name: thumb_use
: Thumbnails settings → Use dimension

Sets the dimension (width or height or max aspect or exact) on which the maximum pixel size limitation should apply to for the thumbnail.

The options width or height should be pretty self-explanatory: if you specify the value width for the setting "Use dimension", all thumbnails will have exactly the width (in pixels) that you specify in the setting "Max dimension of a thumbnail". Settings all thumbnails to have the same width makes the "grid" of thumbnails on the thumbnails page look very structured, especially when there is little space between the thumbnail rows. The same thing applies if you choose height - all thumbnails will then have the same height, which will look good particularly when looking at a row of thumbnails, e.g. on the film strip display.

Choosing max aspect means that whatever will be the longer side (width for images in landscape format, height for images in portrait format) will have the dimension you specify in "Max dimension of a thumbnail" - the shorter side will be shorter of course, as the aspect ratio that exists for the orginal pic will be preserved as well for the thumbnail.

Only if you choose exact as value for the setting "Use dimension", the value entered into the field "Height of a thumbnail" will be taken into account at all: the thumbnail will then be resized to the fixed dimensions you specify for width and height. If the aspect ratio of the original doesn't match the aspect ratio that results from the width and height settings for thumbnails, the thumbnail will be cropped as well. The main advantage of this setting is that all your thumbnails will have identical dimensions, which leads to a super-clean look of your thumbnails page, with the drawback of the fact that important parts of the content of the original image may not be visible on the thumbnail page because cropping has been applied. Use this option to create square thumbnails (setting width and height for the thumbnail to the same value).

Option value Explanation Correlation Advantages Disadvantages
width Thumbnails will have exactly the same width (in pixels) that you specify in the setting "Max dimension of a thumbnail". The height may differ from thumbnail to thumbnail, as the aspect ratio of the original image is preserved for the thumbnail. Max dimension of a thumbnail Nice look for thumbnails aligned vertically. Predictable results for themes with fixed width (i.e. where the content defined by the {GALLERY}-token is meant to fit in a table cell or div container with fixed or limited width. Doesn't align well horizontally.
height Thumbnails will have exactly the same height (in pixels) that you specify in the setting "Max dimension of a thumbnail". The width may differ from thumbnail to thumbnail, as the aspect ratio of the original image is preserved for the thumbnail. Max dimension of a thumbnail Nice look for thumbnails aligned horizontally (e.g. the film strip). Looks silly for extreme landscape resolutions, e.g. stitched panorama images. Doesn't align well vertically. Unpredictable results for fixed-width themes.
max aspect Whatever will be the longer side (width for images in landscape format, height for images in portrait format) will have the dimension you specify in "Max dimension of a thumbnail" - the shorter side will be shorter of course, as the aspect ratio that exists for the orginal pic will be preserved as well for the thumbnail. This is the recommended setting. Max dimension of a thumbnail Thumbnails will have similar files sizes. Estetically pleasant if you have a mixture of landscape and portrait images. Thumbnail rows and columns will not align. Unpredictable results for narrow themes.
exact Thumbnail will be resized to the fixed dimensions you specify for width and height. All thumbnails will have the same dimensions and look identical. If the aspect ratio of the original doesn't match the aspect ratio that results from the width and height settings for thumbnails, the thumbnail will be cropped as well. Max dimension of a thumbnail and Height of a thumbnail Clean look of your thumbnails page because thumbnails will align both vertically as well as horizontally. Parts of the content of the original image may not be visible on the thumbnail page because cropping has been applied, so your thumbnails may not attract the attention of the visitor.

When changing this setting, only files that are added after the change will be affected. Therefore, it is advisable that this setting not be changed after photos have already been added to the gallery. You can, however, apply the changes to the existing pictures with the "admin tools (resize pictures)" utility from the admin menu.


Max dimension of a thumbnail

Default value:
Recommended value:
Minimum:
Maximum:
Database record name: thumb_width
: Thumbnails settings → Max dimension of a thumbnail

Sets the maximum allowable size in pixels for the specified dimension of your thumbnails - it depends on what you have set up in "Use dimension" wether the setting from "Max dimension of a thumbnail" will apply to the width or height or the longer side (max aspect).

For details on this setting please refer to the explanations given in "Use dimension".

When changing this setting, only files that are added after the change will be affected. Therefore, it is advisable that this setting not be changed after photos have already been added to the gallery. You can, however, apply the changes to the existing pictures with the "admin tools (resize pictures)" utility from the admin menu.


Height of a thumbnail

Default value:
Recommended value:
Minimum:
Maximum:
Database record name: thumb_height
: Thumbnails settings → Height of a thumbnail

Only applies if you use "exact" in "Use dimension". This setting is not being taken into account when "Use dimension" has been set to "height".

For details on this setting please refer to the explanations given in "Use dimension".

When changing this setting, only files that are added after the change will be affected. Therefore, it is advisable that this setting not be changed after photos have already been added to the gallery. You can, however, apply the changes to the existing pictures with the "admin tools (resize pictures)" utility from the admin menu.


The prefix for thumbnails

Default value:
Recommended value:
Database record name: thumb_pfx
: Thumbnails settings → The prefix for thumbnails

This prefix is added to the file name of created 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 become invalid.

It's recommended to leave the setting as is (thumb_) if you're not absolutely sure what you're doing.

This feature is deprecated in cpg1.5.x or better and can no longer be configured, since it only lead to end user confusion. If you performed a fresh install or if you have never changed this prefix, the option won't show through. Only for those who have actually changed this option and have a config setting that differs from the default prefix, the text field will show at all. If this is the case for you: you're strongly encouraged to change this back to the default value to avoid possible issues in future versions.
Bottom line: don't be alarmed if this option doesn't show for you - that's OK.


Thumb Sharpening: enable Unsharp Mask

Default value:
Recommended value:
Database record name: enable_unsharp
: Thumbnails settings → Thumb Sharpening: enable Unsharp Mask

Unsharp masking is an image manipulation technique of increasing the acutance, or apparent sharpness, of photographic images. The "unsharp" of the name derives from the fact that the technique uses a blurred, or "unsharp", positive to create a "mask" of the original image. The unsharped mask is then combined with the negative, creating the illusion that the resulting image is sharper than the original.

With this setting you toggle the creation of thumbnails on with an unsharp mask applied, i.e. you enable thumbnail sharpening. If this option is enabled, you usually get sharper-looking thumbnails. Turn the option off if the exact looks of the original need to be preserved without the improved visual effect that thumb sharpening applies. Default setting (for compatibility reasons) is "off". Recommended setting is "on".


Thumb Sharpening amount

Default value:
Recommended value:
Minimum:
Maximum:
Database record name: unsharp_amount
: Thumbnails settings → Thumb Sharpening amount

The amount of sharpening that is applied, listed as a percentage, controling the magnitude of each overshoot (how much darker and how much lighter the edge borders become). This can also be thought of as how much contrast is added at the edges. It does not affect the width of the edge rims.

Recommended setting (and default) is 120.

This setting will only be taken into account if thumbnail sharpening is enabled in the first place.


Thumb Sharpening radius

Default value:
Recommended value:
Minimum:
Maximum:
Database record name: unsharp_radius
: Thumbnails settings → Thumb Sharpening radius

This affects the size of the edges to be enhanced or how wide the edge rims become, so a smaller radius enhances smaller-scale detail. Higher Radius values can cause halos at the edges, a detectable faint light rim around objects. Fine detail needs a smaller Radius. Radius and Amount interact; reducing one allows more of the other.

The decimal separator is always a dot even if the separator in your language differs!

Default (and recommended) setting is 0.5

This setting will only be taken into account if thumbnail sharpening is enabled in the first place.


Thumb Sharpening threshold

Default value:
Recommended value:
Minimum:
Maximum:
Database record name: unsharp_threshold
: Thumbnails settings → Thumb Sharpening threshold

Controls the minimum brightness change that will be sharpened or how far apart adjacent tonal values have to be before the filter does anything. This lack of action is important to prevent smooth areas from becoming speckled. The threshold setting can be used to sharpen more pronounced edges, while leaving more subtle edges untouched. Low values should sharpen more because fewer areas are excluded. Higher threshold values exclude areas of lower contrast.

Default (and recommended) setting is 3

This setting will only be taken into account if thumbnail sharpening is enabled in the first place.


Back to top

File settings

Quality for JPEG files

Default value:
Recommended value:
Minimum:
Maximum:
Database record name: jpeg_qual
: File settings → Quality for JPEG files

The quality used for JPEG compression when the script resizes an image. Values can range from 0 (worst) to 100 (best). By default this value is set to 80. This value can be set to 75 when using ImageMagick.
Do not change this setting unless you really know what you're doing. Other settings for thumbnail and intermediate pic (dimensions) may have a significant and undesireable impact on filesizes and image quality.


Create intermediate pictures

Default value:
Recommended value: n/a
Database record name: make_intermediate
: File settings → Create intermediate pictures

By default, whenever you upload a file, the script creates both a thumbnail of the file (file name using "thumb_" as its prefix) and an intermediate version of the file(file name using "normal_" as its prefix). If you set this option to NO, the intermediate file will not be created. This will keep Coppermine from creating intermediate-sized pics during the upload process, displaying the full-sized picture even on the intermediate-display page (resizing the full-sized image on that screen using the width and height attributes of the <img>-tag) to the size that you have specified for "Max width or height of an intermediate picture". Setting this option to "no" will save webspace but may result in increased loading times for the intermediate image display screen.

A lot of additional information on intermediate images can be found on the "Getting Started" page, especially within the sub-sections "Intermediates" and "Recommended resizing setups".


Use dimension

Default value:
Recommended value:
Available options: ("any")
("ht")
("wd")
("thumb")
Database record name: picture_use
: Thumbnails settings → Use dimension

Sets the dimension (width or height or max aspect or like thumbnail) on which the maximum pixel size limitation should apply to for the intermediate picture.

The options width or height should be pretty self-explanatory: if you specify the value width for the setting "Use dimension", all intermediate pictures will have exactly the width (in pixels) that you specify in the setting "Max width or height of an intermediate picture".

Choosing max aspect means that whatever will be the longer side (width for images in landscape format, height for images in portrait format) will have the dimension you specify in "Max width or height of an intermediate picture" - the shorter side will be shorter of course.

If you choose like thumbnail as value for the setting "Use dimension", the value entered into the thumbnail field "Use dimension" will be taken into account.

This setting also applies when resizing full-sized pictures during the upload process.

When changing this setting, only files that are added after the change will be affected. Therefore, it is advisable that this setting not be changed after photos have already been added to the gallery. You can, however, apply the changes to the existing pictures with the "admin tools (resize pictures)" utility from the admin menu.


Max width or height of an intermediate picture

Default value:
Recommended value:
Minimum:
Maximum:
Database record name: picture_width
: Configuration → Picture and thumbnail settings → Max width or height of an intermediate picture

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 be created to fit inside a square of 400x400 pixels. NOTE: Currently, 33% of your users have monitors set at 800 pixels wide, another 33% have their settings at 1024 pixels, the rest have settings less than or greater than these two numbers. Therefore a setting of 600 or less would fit the screens of most users. Keep in mind,however, that setting this size larger than 400 impacts the file size of your intermediate pictures and the time it takes to download and display on slower connections.

If you disable the creation of intermediate images, the value specified for "Max width or height of an intermediate picture" will still have an impact: the full-size image will then be resized using the width and height attributes of the <img>-tag on the intermediate image display pages (displayimage.php), resizing the full-size pic that way to fit on the page.


Max size for uploaded files (KB)

Default value:
Recommended value:
Minimum:
Maximum:
Database record name: max_upl_size
: Configuration → Picture and thumbnail settings → Max size for uploaded files

Any file with a file size larger than this value will be rejected by the coppermine script. Setting this option to a higher value than what is actually supported by your webserver will only result in "funny" webserver error messages in lieu of "regular" coppermine error messages. Therefore, it is recommended that you set this value to a size that is slightly lower or equal to the max file size that your server is set to handle. The actual size your server can handle cannot be determined by Coppermine (or any PHP script) - when in doubt, contact your webhost.

Prior to an FTP upload of files, it is recommended that the admin use their imaging software to resize (individually or by batch processing) larger files to a more practical size. This will facilitate the FTP process and the creation of intermediate pictures and thumbnails.


Max width or height for uploaded pictures (pixels)

Default value:
Recommended value:
Minimum:
Maximum:
Database record name: max_upl_width_height
: File settings → Max width or height for uploaded pictures

Limits the height and width dimensions of the pictures that are uploaded. Resizing large pictures requires a lot of memory and consumes CPU resources. As a result, there are usually limitations that have been set by your webserver (host) regarding the maximum uploadable file sizes - you cannot set this value to one that is higher than what is actually supported by your webserver. Contact your webhost/server if you are not sure about your site's file size limitations. (Ideally, users will resize their pictures to a more manageable size prior to attempting any uploads). Determine what you would like the maximum size for a full size pic should be (dpi and dimensions, while keeping in mind the screen size of your users) and use that as a recommended standard for FTP and user HTTP uploads. Inform your users of this recommended size constraints.)

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 an intermediate picture)"


Auto resize images that are larger than max width or height

Default value:
Recommended value:
Database record name: auto_resize
: File settings → 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 be resized to the maximum allowable size. Users with especially large files should be advised to resize their pictures outside of coppermine before uploading as this process also consumes considerable resources when processed online.

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 an intermediate picture)"

There are three options:


Horizontal padding for full-size pop-up

Default value:
Recommended value:
Minimum:
Maximum:
Database record name: fullsize_padding_x
: File settings → Horizontal padding for full-size pop-up

This setting is used to determine the width of a full-size pop-up, as most major browsers mysteriously add some padding to pics opened in a pop-up. It's recommended to leave this set to the default 5 pixels unless you know what you're doing.


Vertical padding for full-size pop-up

Default value:
Recommended value:
Minimum:
Maximum:
Database record name: fullsize_padding_y
: File settings → Vertical padding for full-size pop-up

This setting is used to determine the height of a full-size pop-up, as most major browsers mysteriously add some padding to pics opened in a pop-up. It's recommended to leave this set to the default 3 pixels unless you know what you're doing.

Albums can be private

Default value:
Recommended value:
Database record name: allow_private_albums
: File settings → Albums can be private

If set to YES then your gallery can contain albums that are visible only to users that belong to a specified group. This is ideal for creating albums that contain files that you want accessible to only a select group of people. You could also create a userID and password and inform specific users/customers of the ID and password needed to view these files.

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 any of his/her albums from other users.

This option does not determine whether users can have personal galleries at all, nor does it determine who is allowed to upload and who is not (these settings are accessible 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' all currently private albums will become public! Do not set this option to 'no' unless you understand what this option actually does!


Show private album Icon to unlogged user

Default value:
Recommended value: n/a
Database record name: show_private
: File settings → Show private album Icon to unlogged user

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

It is recommended to enable this option especially if you want to encourage visitors to register (this does of course only make sense if you allow registered users to see albums that guests are not allowed to see).


Characters forbidden in filenames

Default value:
Recommended value:
Database record name: forbiden_fname_char
: File settings → Characters forbidden in filenames

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

Don't change this unless you know exactly what you are doing. Default value is $/\:*?"'<>|` &#@


Enable "silly safe mode"

Default value:
Recommended value:
Database record name: silly_safe_mode
: File settings → Enable "silly safe mode"

A significant number of webhosts 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 you have issues uploading pics, find out if safe_mode is enabled on your webserver by searching for it on your phpinfo page (go to admin tools -> phpinfo). If safe_mode is enabled there, coppermine might be able to workaround the misconfiguration of your server if you enable coppermine's "silly safe mode" option.

What "silly safe mode" does: if you enable this option, Coppermine will not try to create sub-folders for each user, but upload all files into the root of the userpics folder. There might be a slight performance impact for larger galleries, but then you probably won't be running a large gallery on a "crippled" webserver that is not configured properly.

Before playing with the silly safe mode option, make sure that you have set permissions on the albums folder and everything within it as suggested.

Don't change this if uploading works just fine for you. Do not enable the Coppermine setting "silly safe mode" if your webserver is not running in safe mode in the first place.


Allowed image types

Default value:
Recommended value:
Database record name: allowed_img_types
: File settings → Allowed image types

Enter the allowed image file types that your image library (GD or ImageMagick) is capable of handling to be allowed as uploads and content in your gallery. Restrict the allowed file types to certain types only by entering a slash-separated list of extensions, e.g. jpg/bmp/tif (only possible if you use ImageMagick) or jpg/png (possible both for ImageMagick as well as GD).

You have to understand that you can not specify "all image file types that exist", but instead "all image file types that your image library (GD or ImageMagick) supports.

In Coppermine versions prior to cpg1.5.0, the option "ALL" used to be available as well for this field - it has been removed, as it caused users to think that this actually meant "all image file types that exist" - this is not the case: you can only specify the file types that the image library you use actually supports.

Allowed movie types

Default value:
Recommended value:
Database record name: allowed_mov_types
: File settings → Allowed movie types

Specify the allowed movie file types to be uploaded. If you want to restrict the allowable file types to certain extensions only, enter a slash-separated list of extensions, e.g. wmv/avi/mov.

Note that being able to display a movie requires that the cpg-user have the necessary codecs properly configured on their computers to display the movie file, e.g. if you allow the file type mov, the user who wishes to view the file 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 'avi' codecs.

File types supported by Coppermine:
asf/asx/mpg/mpeg/wmv/swf/avi/mov

In Coppermine versions prior to cpg1.5.0, the option "ALL" used to be available as well for this field - it has been removed, as it caused users to think that this actually meant "all movie file types that exist".


Movie Playback Autostart

Default value:
Recommended value:
Database record name: media_autostart
: File settings → Movie Playback Autostart

If set to YES, movies will instantly start playing when loaded (has no affect on flash files, however). Nothing will happen if the user does not have the necessary codecs installed on their computer. This option is browser-dependant, so there is no guarantee that it will work on all platforms.


Allowed audio types

Default value:
Recommended value:
Database record name: allowed_snd_types
: File settings → Allowed audio types

Specify the allowable audio file types to be uploaded. If you want to restrict the allowed file types to certain extensions only, enter a slash-separated list of extensions, e.g. wav/mp3/wma.

Note that being able to listen to an audio file requires that the cpg-user have the necessary codecs properly configured on their computers to hear these files, e.g. if you allow the file type mp3, users who wish to listen to the file will need to have a media player installed on their computer that can handle mp3 files.

File types supported by Coppermine:
mp3/midi/mid/wma/wav/ogg

In Coppermine versions prior to cpg1.5.0, the option "ALL" used to be available as well for this field - it has been removed, as it caused users to think that this actually meant "all sound file types that exist".


Allowed document types

Default value:
Recommended value:
Database record name: allowed_doc_types
: File settings → Allowed document types

Specify the allowable document file types to be uploaded. If you want to restrict the allowable file types to certain extensions only, enter a slash-separated list of extensions, e.g. txt/pdf.

Note that being able to browse a document file requires the cpg-user to have a compatible software installed and configured properly on their computer that is capable of displaying the type of document in question, e.g. if you allow the file type xls, users who wish to browse the file will need to have an application installed on their computer that can display MS-Excel sheets. Be extremely careful with documents that are known to be vulnerable to virus contamination, embedded or as macros. This is especially true if you plan to allow users the capability of uploading documents without admin approval.

File types supported by Coppermine:
Real-Media-files: ram/ra/rm
Images: tiff/tif
MS Office: doc/xls/pps/ppt/mdb/accdb/accde/accde/accdr/accdt/docm/docx/dotm/dotx/grv/gsa/one/onepkg/ost/potm/potx/ppam/ppsm/ppsx/pptm/pptx/pub/xlam/xlsb/xlsm/xlsx/xltm/xltx/xsf/xsn
Misc: txt/rtf/pdf
Archives: zip/rar/gz/001/7z/arj/bz2/cab/lzh/rpm/tar/z
OpenDocument (OpenOffice 2.x): odt/ods/odp/odg/odc/odf/odi/odm/ott/ots/otp/otg/otc/otf/oti/oth
OpenOffice 1.x / StarOffice 6.x: sxw/stw/sxc/stc/sxd/std/sxi/sti/sxg/sxm

For security reasons coppermine doesn't enable all document types by default. Before adding more file types, make sure that the file types are supported on your webserver.

In Coppermine versions prior to cpg1.5.0, the option "ALL" used to be available as well for this field - it has been removed, as it caused users to think that this actually meant "all document file types that exist".


Method for resizing images

Default value:
Recommended value: n/a
Available options:


Database record name: thumb_method
: File settings → Method for resizing images

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

If you are using GD 1.x and the colors of your thumbnails or intermediate image do not display properly, then, chances are, you actually have GD2 on your server - switch this option to GD 2.x

More recent distributions of PHP come pre-packaged with GD - if you're not sure what you have, set this option to GD2. You can also look at your PHP settings by pointing your browser to the phpinfo.php file in your gallery. eg, http://www.yourgallery.com/your_cpg_folder/phpinfo.php. For more information on using PHP click on this link: phpinfo.


Path to ImageMagick's "convert" executable

Default value:
Recommended value:
Database record name: impath
: File settings → Path to ImageMagick's "convert" executable

If you intend using ImageMagick's convert executable to resize your pictures, you must enter the absolute path to the name of the directory where the convert program is located in this line. Don't forget the trailing "/" to close the path. This path must only indicate the directory where the convert executable is located, it should not point directly to the convert executable itself.

The path you specify here will only be taken into account if you set the Method for resizing images to "ImageMagick". If you specify anything else there, the Path to ImageMagick's "convert" executable will not be taken into account. You need to make sure to specify a valid path with a traling slash no matter what - the config form will complain if you don't.

ImageMagick will not work properly if PHP on your server is running in safe mode and it is a real challenge to get it running under Windows. Please consider using GD (see What's GD and how can I get it? in these cases and don't waste your time asking for support in the forum with ImageMagick installation questions. There are just too many things that can prevent ImageMagick from working properly and without physical access to your server it is extremely difficult to guess what is wrong.

Also refer to: What's ImageMagick and how can I get it? and How do I enable ImageMagick on my Windows server?.

ImageMagick on Windows-driven servers

On Windows, the path that you need to enter into Coppermine's config can look like this for example: c:/ImageMagick/ if the convert executable actually resides at c:/ImageMagick/convert.exe

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 spaces under Windows so that it will not put ImageMagick in the "Program files" directory.

ImageMagick on Lunix-driven servers

On Posix-compliant server operating systems (i.e. Unix/Linux/BSD-driven systems), the path that you need to enter into Coppermine's config can look like this: /usr/bin/ if the convert executable resides at /usr/bin/convert (mind the fact that executables on Lunix don't have the extension .exe). Another example for the path you need to enter can be /usr/bin/X11/ if the convert executable resides at /usr/bin/X11/convert.


Command line options for ImageMagick

Default value:
Recommended value:
Database record name: im_options
: File settings → 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.

Usually (unless you're an expert) this setting can be left alone.


Read EXIF data in JPEG files

Default value:
Recommended value: n/a
Database record name: read_exif_data
: File settings → 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.

Since cpg1.4.x there is even an EXIF-manager available that will allow you to determine what exif fields are supposed to be displayed.


Read IPTC data in JPEG files

Default value:
Recommended value: n/a
Database record name: read_iptc_data
: File settings → Read IPTC data in JPEG files

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

Please note: IPTC does not support unicode encoding. Therefore, it may collide with coppermine if you use special, non-latin characters in your IPTC tags.


The album directory

Default value:
Recommended value:
Database record name: fullpath
: File settings → 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 so, all references to your existing files will break.

Unless you really know what you are doing, do not change this setting.


The directory for user files

Default value:
Recommended value:
Database record name: userpics
: Configuration → Picture and thumbnail settings → The directory for user files

This is the directory where files uploaded using the web interface (URL/URI) are stored. This directory is a subdirectory of the album directory. It's recommended that you leave this setting as is. Should you decide to change it, keep in mind that the folder must exist within the albums folder and the path should be relative to it.

The same remarks as above apply.

When you upload files by FTP, store them in a subdirectory (folder) 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 previously existing files will no longer be valid.


The prefix for intermediate pictures

Default value:
Recommended value:
Database record name: normal_pfx
: File settings → 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 become invalid.

Default prefix is normal_.

This feature is deprecated in cpg1.5.x or better and can no longer be configured, since it only lead to end user confusion. If you performed a fresh install or if you have never changed this prefix, the option won't show through. Only for those who have actually changed this option and have a config setting that differs from the default prefix, the text field will show at all. If this is the case for you: you're strongly encouraged to change this back to the default value to avoid possible issues in future versions.


Default mode for directories

Default value:
Recommended value: n/a
Database record name: default_dir_mode
: File settings → Default mode for directories

If, and only if, during the file upload or batch add process, the installer complains about the directory not having the right permissions, try setting this to 0777 . Failure to do so may prevent you from being able to delete directories created by the script with your FTP client should you ever decide it necessary to uninstall the coppermine script.

Note: setting this option doesn't CHMOD the files or folders that are being uploaded. Instead, the setting is used when coppermine, itself, creates new folders for user uploads (within the userpics directory). If you experienced problems during the initial Coppermine setup related to permissions, this option is not what you have been looking for nor should it be changed (for more information regarding CHMOD, see the permissions section of this document and the FAQ section).


Default mode for files

Default value:
Recommended value: n/a
Database record name: default_file_mode
: File settings → Default mode for files

If, and only if, during the file upload or batch add process, the installer complains about the directory not having the right permissions, try setting this to 0666.

Note: setting this option doesn't CHMOD the files or folders that are being uploaded. Instead, the setting is used when coppermine, itself, creates new folders for user uploads (within the userpics directory). If you experienced problems during the initial Coppermine setup related to permissions, this option is not what you have been looking for nor should it be changed (for more information regarding CHMOD, see the permissions section of this document and the FAQ.htm document located in the DOCS folder of this installation package).

Back to top

Image watermarking

Starting with cpg1.5.x Coppermine comes with support for permanently watermarking pictures with the possibility to undo the watermarking. Use watermarking to protect your images against theft.

Details on watermarking can be found on the corresponding article in the docs.


Watermark Images

Default value:
Recommended value:
Database record name: enable_watermark
: Image watermarking → Watermark Image

General toggle that determines if watermarking should be enabled or disabled. By default, it is disabled.

As watermarking actually means that each picture needs to be re-calculated during the upload stage, there may be issues with memory consumption and speed. If you experience issues with watermarking, turn it off or ask your webhost to increase server-sided settings that have an impact on watermarking.
Also keep in mind that the re-calculation of the image will result in a loss of quality.

Remember as well that watermarking will not only have an impact on the quality and recources consumption (in turns of burning CPU cycles on the server), but as well in the consumption of webspace: when watermarking is enabled, coppermine will keep a safe, unmodified copy of the orginal image (prefixed with "orig_") in the same folder your watermarked file will reside and thus consume additional webspace.
You can use the admin tools to get rid of this copy as well, ,but you have to keep in mind then that there is not turning back in this case: if you delete the unmarked original, you can never go back or apply another watermark.

When enabling this option, you have to understand that watermarks are not automatically being applied to all files that already exist in your gallery. When enabled, only images that get uploaded from that point on will become watermarked. If you want to apply watermarking to all the images that already existed in your coppermine gallery before you enabled watermarking, take a look at the corresponding section of the admin tools. However, before applying your new watermark permanently to all your images, perform some test uploads first to see if watermarking works as expected for you.


Watermark custom thumbs (movie, audio, document)

Default value:
Recommended value:
Database record name: enable_thumb_watermark
: Configuration → Image watermarking → Watermark custom thumbs

When enabled, custom thumbnails will be watermarked as well.

If you don't use custom thumbnails, don't worry about this option.


Where to place the watermark

Default value:
Recommended value: n/a
Available options: ("southeast")
("southwest")
("northwest")
("northeast")
("center")
Database record name: where_put_watermark
: Image watermarking → Where to place the watermark

Determines where the watermark is supposed to be displayed on each picture. Possible options are:


Which files to watermark

Default value:
Recommended value: n/a
Available options:


Database record name: which_files_to_watermark
: Image watermarking → Which files to watermark

Determines which files the watermarking should be applied to. Possible options are:

All three options make sense in different environments: if you want to use watermarking to encourage your users to register, you should apply the watermark to resized image (intermediate images) only and only allow registered users to access the original (full-sized) images. On the other hand, if you only want to make sure that your high-resolution full-size images are not being stolen, apply the watermark to the original only.


Which file to use for watermark

Default value:
Recommended value: n/a
Database record name: watermark_file
: Image watermarking → Which file to use for watermark

Specify the relative path to the watermark file, seen from the root folder of your coppermine-gallery. Default value: images/watermark.png. You can (and are even encouraged) to come up with a watermarking file of your own - only a standard desktop drawing application is needed, e.g. MS Paint.

Coppermine only comes with a sample watermarking file that you should not apply lightheartedly, as it is only meant for testing purposes and to give you an idea how the watermarking file could look like. You have to come up with your custom watermark file and FTP-upload that file to your webserver. It's a good idea to name it accordingly, e.g. "custom_watermark.png" and upload it to the images folder (http://your_domain.tld/your_coppermine_folder/images/). All you then have to do is change the setting for "Which file to use for watermark" to images/custom_watermark.png.

Coming up with a custom watermark can be tricky: it should work well both for dark as well as light backgrounds. You have to find a good compromise: the watermarked files should be still OK to look at, while on the other hand potential image thieves should get discouraged to steal your watermarked images.


Transparency 0-100 for entire image

Default value:
Recommended value:
Minimum:
Maximum:
Database record name: watermark_transparency
: Image watermarking → Transparency 0-100 for entire image

Determines the transparency level for the watermark. By setting transparency you can make your image blend nicely into the pictures you upload that get watermarked.


Downsize watermark if width of an picture is smaller than entered value

Default value:
Recommended value:
Minimum:
Maximum:
Database record name: reduce_watermark
: Image watermarking → Downsize watermark if width of an picture is smaller than entered value

That is the 100% reference point. Resizing of the watermark is linear (0 to disable).

Keep in mind that images might get uploaded by your users (if you allow uploads by others than the admin) that you might not have made up your mind about: the image uploaded may be smaller in resolution. If the dimension of the image uploaded is smaller than the dimension of your watermark file, the watermarking would get cut off and look silly. That's why this option exists: you can specify that images that are smaller than a particular size will have the watermarking applied in a resized manner, making the watermark again fit on the uploaded image. It's a good idea to set this option to the horizontal dimension of your watermarking image.

Example:
Let's assume that your custom watermarking image has got the same dimensions as the sample one that comes with the coppermine package: 300 x 51 pixels. Subsequently, if you set the option "Downsize watermark if width of an picture is smaller than entered value" to 300, you should be fine: if someone uploads an image that is only 250 x 100 pixels, the resulting watermarked image will be 250 x 100 pixels as well, but the watermarking image will have been resized to 250 x 43 before being applied as a watermark, so it will fit on the original file that was uploaded.

Set color transparent x

Default value:
Recommended value:
Minimum:
Maximum:
Database record name: watermark_transparency_featherx
: Image watermarking → Set color transparent x

This option is only available if you have set the method for resizing images to GD2. If you have set it to GD1 or ImageMagick, this setting will not be taken into account at all. Specify the horizontal coordinate of the pixel that should represent the transparent color, seen from the left of the watermarking image.

The transparency setting is particularly usefull if you use a jpeg image as watermarking file or if you don't know how to set transparency up for your watermarking image inside the desktop app where you compose your custom watermark. Your best option (to go out of harms way) will be to use a png watermarking file with transparency - in this case, this setting will not be needed.


Set color transparent y

Default value:
Recommended value:
Minimum:
Maximum:
Database record name: watermark_transparency_feathery
: Image watermarking → Set color transparent y

This option is only available if you have set the method for resizing images to GD2. If you have set it to GD1 or ImageMagick, this setting will not be taken into account at all. Specify the vertical coordinate of the pixel that should represent the transparent color, seen from the top of the watermarking image.

The transparency setting is particularly usefull if you use a jpeg image as watermarking file or if you don't know how to set transparency up for your watermarking image inside the desktop app where you compose your custom watermark. Your best option (to go out of harms way) will be to use a png watermarking file with transparency - in this case, this setting will not be needed.


Back to top

Registration

Allow new user registrations

Default value:
Recommended value:
Database record name: allow_user_registration
: Registration → Allow new user registrations

Defines 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.


Set global password for registration

Default value:
Recommended value:
Database record name: global_registration_pw
: Registration → Set global password for registration

This password should be known by users who want to register. They will be asked for this password on the registration form. User will be able to set his own password while registring. User's password should be different from the global password. To disable global password, leave the field blank.

This option is meant for galleries that are half-private. Example use: if you're going to take pics on a wedding, just tell the guest of the wedding party to visit your page and to use the global password set up here. As a result, visitors who have been guests of that party can actually register, but others who just came to your gallery by accident can't.


Display disclaimer on user registration

Default value:
Recommended value: n/a
Database record name: user_registration_disclaimer
: Registration → Display disclaimer on user registration

Toggles wether users will see the disclaimer on the registration page. You have the option not to display the disclaimer at all, display it as separate page before the actual registration page or inline on the registration page.
This setting only applies if coppermine is not bridged.


Display Captcha (Visual Confirmation) on registration page

Default value:
Recommended value:
Database record name: registration_captcha
: Registration → Display Captcha (Visual Confirmation) on registration page

To prevent automated registration by bots (automated scripts), this toggle will display an image on the registration page with some random letters on it. The visitor who is trying to register is required to enter those letters into a textfield to prove that he's actually a human and not just some dumb bot.

Note: this setting isn't being taken into account when coppermine is bridged.

Captchas will only work if GD2 is available on your server.


User registration requires email verification

Default value:
Recommended value:
Database record name: reg_requires_valid_email
: Registration → 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

Default value:
Recommended value:
Database record name: reg_notify_admin_email
: Registration → 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.


Admin Activation

Default value:
Recommended value:
Database record name: admin_activation
: Registration → Admin Activation

Enable admin activation. When set to yes, a gallery administrator must first activate the new registration before the user can log-in and take advantage of any registered user privileges.

By default, it is set to no, so users would activate their own accounts upon registering.


Create user album in personal gallery on registration

Default value:
Recommended value:
Database record name: personal_album_on_registration
: Registration → Create user album in personal gallery on registration

When enabled, each user will have a personal album created during the registration process, even if your permissions for the group new users are in do not allow this (i.e. if you have allowed personal galleries for members of the registered group disabled). Warning: usually, only a small percentage of registered users actually upload files - when this option is enabled, a lot of unneeded user galleries will be created, severely cluttering the database (which has an impact on performance). Don't enable this option if you don't know what it actually does!

This option is disabled when being bridged.


Back to top

User settings

Allow unlogged users (guest or anonymous) access

Default value:
Recommended value:
Database record name: allow_unlogged_access
: User settings → Allow unlogged users (guest or anonymous) access

When set to "No", unlogged users (i.e. guests or anonymous users) can not access anything in your gallery except the login screen (and the registration screen, if you allow registrations). Completely disabling anonymous access will probably decrease your site's popularity. Use this option only if you need your gallery to be absolutely private. The recommended setting is to leave anonymous access enabled and use the more specific permissions by groups and albums settings instead.

This option can be set to 4 different levels of access for anonymous users:

Keep in mind that search engine spiders will be treated as non-registered guests as well, so if you restrict the accessibility for guests, search engine spiders will not index whatever you hide from your guests.


Default upload method

Default value:
Recommended value:
Database record name: upload_mechanism
: User settings → Default upload method

Select which type of form users will use to upload files:

There might be other choices you can choose. If so, these come from plugins you have installed. The basic Coppermine options are the two listed above. For assistance on any other upload methods, please check your plugins and their documentation.

You are encouraged to use the advanced upload form unless you have problems with it. This form uses SWFUpload, which has some known issues.

Since it is your users who will run into these problems, you may want to allow your users to choose the upload method themselves. See the configuration setting "Allow users to choose the upload method".

The flash-driven interface is the most elegant solution for most, but of course it has got several drawbacks as well, with the most serious drawback being that those who don't have flash support won't be able to upload at all. Don't take for granted that everybody will have flash: users on a corporate PC where the admin has disallowed flash won't be able to use it, nor do all mobile gadgets (like PDAs, smart phones, game consoles etc.) have flash support.


Allow users to choose the upload method

Default value:
Recommended value:
Database record name: allow_user_upload_choice
: User settings → Default upload mechanism

When enabled, users can choose the upload method themselves. This is recommended so that if some users have an issue with their web browsers or operating systems, they can choose another upload method that works better. At the very least, they can use the simple, one file at-a-time, upload method.


Allow two users to have the same email address

Default value:
Recommended value:
Database record name: allow_duplicate_emails_addr
: User settings → 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. As most internet users today have more than one email address, this option is being considered as deprecated and has been removed in cpg1.5.x for fresh installs. Only if you have upgraded from an older version you should be able to see this option. It's a one-way setting though: once you disallow identical email addresses for different users, you can not re-enable that option. It's recommended to turn this option off if you have it turned on.


Notify admin of user upload awaiting approval

Default value:
Recommended value:
Database record name: upl_notify_admin_email
: User settings → Notify admin of user upload awaiting approval

When enabled, the gallery admin receives an email notification of all pics that await for his/her approval (depends on the approval settings in "groups"). The email is sent to the address specified in "General settings".

This option is only recommended for websites with low or medium traffic (where users only upload every now and then).


Allow logged in users to view memberlist

Default value:
Recommended value:
Database record name: allow_memberlist
: User settings → Allow logged in users to view memberlist

When enabled, an additional menu item "Memberlist" is 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.

Recommended setting is 'no', especially if you're concerned about your user's privacy.


Allow users to change their email address in profile

Default value:
Recommended value:
Database record name: allow_email_change
: User settings → Allow users to change their email address in profile

This option impacts the user's profile page, it determines whether or not the user can change his/her own email address.
Use this option wisely, as the old email address of a user is not preserved after a change: if you allow users to change their email address, abusers may change it to a non-existing email address (e.g. after uploading some pics that go against your gallery's rules) - you would have no chance of tracking this user.

This option only applies if you use Coppermine as a standalone application; if you run Coppermine integrated with a BBS, this option will be deferred to the user profile from your bbs to manage each user's profile.


Allow users to delete their own user account

Default value:
Recommended value:
Database record name: allow_user_account_delete
: User settings → Allow users to delete their own user account

When enabled, users can delete their user accounts. This option has been added in cpg1.5.x because of legal requirements in some countries.

This option will not be taken into account if your gallery is bridged.


Allow users to retain control over their pics in public galleries

Default value:
Recommended value:
Database record name: users_can_edit_pics
: User settings → Allow users to retain control over their pics in public galleries

When enabled, both the admin and the uploading user can edit and delete files that were uploaded to a public gallery. Of course the user must have permissions to upload to the public gallery in the first place (see the groups control panel) before this option will have any effect.


Allow users to move their albums from/to allowed categories

Default value:
Recommended value:
Database record name: allow_user_move_album
: User settings → Allow users to move their albums from/to allowed categories

When enabled, users will be able to move their albums around from/to categories that the admin has allowed.


Allow users to edit their albums when it is in a locked category

Default value:
Recommended value:
Database record name: allow_user_edit_after_cat_close
: User settings → Allow users to edit their albums when it is in a locked category

When enabled, users will be able to edit their albums even if the admin has locked down the category the album resides in.


Allow users to assign album keywords

Default value:
Recommended value:
Database record name: allow_user_album_keyword
: User settings → Allow users to assign album keywords

When enabled, users will be allowed to assign an album keyword to albums they have control over. This setting doesn't have an impact on the admin - the admin can assign and edit album keywords no matter what. If you allow users to assign album keywords, files from other albums that contain the album keyword set as individual file keyword will show up in their album as linked file.


How do you want your users to be able to login

Default value:
Recommended value:
Available options:


Database record name: login_method
: User settings → How do you want your users to be able to login

You can have your users login with their username, email address or let them choose themselves.
Select the option you want in the dropdown.


Number of failed login attempts until temporary ban (to avoid brute force attacks)

Default value:
Recommended value:
Minimum:
Maximum:
Database record name: login_threshold
: User settings → Number of failed login attempts until temporary ban

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 maximum number of failed log-in attempts before the IP address of the user is temporarily banned.

Keep in mind that this setting will definitely have an impact on your legitimate ability to log in as well: if you mis-type your password too often or if someone else has tried to brute-force your admin account, you will be banned temporarily as well. The ban will of course go away after the time set below, but during the ban phase you will be locked out from administration just as well as an attacker would be logged out.

Default and recommended value is 5. Value can range between 1 and 20 (as 0 would mean that zero logins are allowed, which would lock you (as admin) out permanently as well.


Duration of a temporary ban after failed logins

Default value:
Recommended value:
Minimum:
Maximum:
Database record name: login_expiry
: User settings → Duration of a temporary ban after failed logins

This value specifies the duration of the temporary ban (in minutes) after the number of failed log-in attempts specified with Number of failed login attempts until temporary ban.

The warnings posted above for Number of failed login attempts until temporary ban applies here as well: setting this to a value that doesn't make sense will have an impact on legitimate users as well!

Default is 10 minutes. Range is between 0 (which would mean that there will be no temporary ban at all, so use this value to disable the temporary ban feature alltogether) and 9999 minutes (which is roughly less than a week).


Automatically purge expired bans

Default value:
Recommended value:
Database record name: purge_expired_bans
: User settings → Automatically purge expired bans

When enabled, ban records that have a set expiry date will be deleted as soon as the expiry date is reached. This setting will not have an impact wether the banned user will be able to log in again or not. Instead, this option is meant if you want to preserve records of users who misbehaved in the past and therefore have been banned temporarily. If you do not automatically purge those records, then the ban record will show on the ban users page for the admin, together with an indicator that will show that the ban has expired.

The drawback of turning this option off is the fact that the database table that contains the ban records will fill faster and the ban users page will look more cluttered. Subsequently, the ban lookup for each page will take a little longer. If you have performance issues, turn this option on, as it will purge unneeded records from the ban table.


Enable reports

Default value:
Recommended value:
Database record name: report_post
: User settings → Enable reports

When set to "yes," this feature will allow users to report on uploaded files or comments to the site admin.

When enabled, an additional icon will appear in the navigation bar that visitors can click on. If they do, they are being sent to a form where they can explain why they want to see a particular file reported to the admin.

There is a number of pre-defined reasons for the reports (like "obscene", "offensive", "off-topic/misplaced", "missing", "error/cannot view") that visitors can choose from and a text field where they can enter additional information.

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.

It's advisable to enable this feature on larger, community-driven galleries that don't require admin-approval for uploaded pics, as it gives your community the chance to alert you of potential issues and keep your gallery clean.

As a drawback, the feature can be abused by spammers to send emails to the admin, so it's advisable to only allow reports for registered users.


Users can rate their own files

Default value:
Recommended value:
Database record name: rate_own_files
: User settings → Users can rate their own files

Determines if your users can rate their own files or not. Recommended setting is "no" to make sure there is no rating war among your users who try to boost their popularity by committing rating fraud.
This option does not determine wether your visitors will be able to rate files at all. "Users can rate their own files" will only apply if rating is enabled in the first place, i.e. if the user belongs to a group that is allowed to rate/vote (you can determine the overall rating permission per group on the groups control panel) and if rating is enabled for the album the file is in (you can toggle the ability to rate on or off on a per-album base - use the controls on the album properties page to accomplish that).


Custom fields for user profile

Default values: Profile 1 name:
Profile 2 name:
Profile 3 name:
Profile 4 name:
Profile 5 name:
Profile 6 name:
Recommended values: n/a
Database record name: user_profile1_name...user_profile6_name
: 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 assign a name to the field. As instructed in the heading, use field 6 for long entries, such as biographies, or if you want to include the use of bb code.

You can also use field 6 for avatars. To show an avatar in the profile, it should be entered in bbcode. Determine the full URL of the image you want to use as an avatar and wrap that URL into the bbcode tags for images.

If you want to use the file avatar.png that is stored in a sub-folder of your web root that is named images, the full URL would be something like http://www.example.com/images/avatar.png. Subsequently, you'd have to insert
[img]http://www.example.com/images/avatar.png[/img]
into the field number 6.

Custom fields for image description

Default value:
Recommended value: n/a
Database record name: user_field1_name...user_field4_name
: 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

Cookie settings

Name of the cookie used by coppermine

Default value:
Recommended value:
Database record name: cookie_settings
: Cookie settings → Name of the cookie used by coppermine

Default value is something like "cpg15x". Even if you have multiple instances of the script running on the same server you can keep the default value.

When using bridging, make sure it differs from the bridge app's cookie name.

This has to be a valid cookie name (no special chars, particularly no dots!) - this setting should best be left alone unless you really know your way around. After all, the cookie name doesn't matter and doesn't mean anything to the end user anyway. Let me repeat: there are many users who blindly change the cookie name to something that just doesn't make sense at all and then complain on the coppermine support board that things are not working as expected. Do not use special chars in the cookie name! In fact, don't change it at all unless you must.

Path of the cookie used by the script

Default value:
Recommended value:
Database record name: cookie_path
: Cookie settings → 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 (aka bridging), make sure to use different cookie names for coppermine and your bridging app! 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

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.

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 are required to supply a hostname, a username and a password, you will need to edit the CONFIG menu section "Email settings" and insert the correct values there. If you don't need a username and password to connect to your SMTP server, just leave these lines blank. If you don't know what settings to enter, you will need to check with your webhost.

SMTP Host

Default value:
Recommended value: n/a
Database record name: smtp_host
: Email settings → 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).

To specify a non-default port number enter it after the hostname with a colon, for example yourdomain.com:26 to use port 26. To use SSL or TLS add a prefix to the hostname, for example ssl://yourdomain.com to use an SSL encrypted connection. You must have OpenSSL support enabled in PHP and the SMTP server must support SSL connections for this to work. You can use both an SSL prefix and a port number if neccessary. To use gmail's SMTP server you would use ssl://smtp.gmail.com:465


SMTP Username

Default value:
Recommended value: n/a
Database record name: smtp_username
: Email settings → SMTP Username

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


SMTP Password

Default value:
Recommended value: n/a
Database record name: smtp_password
: Email settings → SMTP Password

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

Back to top

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 helpful if the admin actually looks into it.

Logging mode

Default value:
Recommended value:
Database record name: log_mode
: Logging & statistics → 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 helpful if you're trying to debug or if there are various admins on a gallery.
All log files are written in english

You have to understand that this option does not toggle the recording of what your site visitors do. Instead, you log particularly what admins do.


Log ecards

Default value:
Recommended value:
Database record name: log_ecards
: Logging & statistics → 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).


Keep detailed vote statistics

Default value:
Recommended value:
Database record name: vote_details
: Logging & statistics → Keep detailed vote statistics

Enabling this option records:

  1. Each vote separately
  2. IP Address
  3. Referer
  4. Browser
  5. Operating System
  6. User ID (if logged in)

of the voter.

As the statistics are being kept per file, the link to the stats can be accessed on the individual file's page (displayimage.php) by clicking the link in the file info section to open the stats pop-up. Alternatively, you can access the overall stats for your entire gallery by clicking on the admin menu item "Overall stats", which will of course only show if you have enabled stat recording in the first place.

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

Warning: keeping detailed statistics means additional database queries and subsequently a heavy load on the page. You have to understand that the size of the corresponding database tables can increase if you enable this feature, which can have a serious performance impact.

This feature can be very usefull to find out about voting/rating fraud, so if voting is an important part of your gallery (i.e. if you're running a community-driven gallery where users can gain something for voting or for obtaining good votes) it's advisable to turn this feature on.


Keep detailed hit statistics

Default value:
Recommended value:
Database record name: hit_details
: Logging & statistics → Keep detailed hit statistics

Enabling this option records:

  1. Each vote separately
  2. IP Address
  3. Search Keyword, if the referer is Google, Yahoo! or Lycos search engines
  4. Referer
  5. Browser
  6. Operating System
  7. User ID (if logged in)

of the visitor.

As the statistics are being kept per file, the link to the stats can be accessed on the individual file's page (displayimage.php) by clicking the link in the file info section to open the stats pop-up. Alternatively, you can access the overall stats for your entire gallery by clicking on the admin menu item "Overall stats", which will of course only show if you have enabled stat recording in the first place.

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

Warning: keeping detailed statistics means additional database queries and subsequently a heavy load on the page. You have to understand that the size of the corresponding database tables can increase dramatically if you enable this feature, so you should closely monitor the resources consumption caused by it and empty the table from time to time.

Do not enable this option if you don't need it! If you enable it, frequently check the size of the stats table in the database (using a third party tool like phpMyAdmin) and the impact of the stats recording on the overall performance. Make sure that you understand the performance impact that enabling this option has. If you need really detailed stats, you might consider implementing a third-party tool like Google Analytics, which will in turn be less resources-consuming for your server.

Display statistics on index page

Default value:
Recommended value:
Database record name: display_stats_on_index
: Logging & statistics → Display statistics on index page

Turning this option off ("No") will keep the text X files in X albums and X categories with X comments viewed X times from appearing on the index pages (category and album views). Disabling this option will slightly improve performance, as the stats query that builds those numbers doesn't have to be performed. Default value is "Yes", which means that the feature is enabled ("On").


Count file views

Default value:
Recommended value:
Database record name: count_file_hits
: Logging & statistics → Count file views

Turning this option off ("No") will disable counting of file views. This does not affect the display of the view counter. Disabling this option will slightly improve performance. Default value is "Yes", which means that the feature is enabled ("On").

Count album views

Default value:
Recommended value:
Database record name: count_album_hits
: Logging & statistics → Count album views

Turning this option off ("No") will disable counting of album views. This does not affect the display of the view counter. Disabling this option will slightly improve performance. Default value is "Yes", which means that the feature is enabled ("On").

Count admin views

Default value:
Recommended value:
Database record name: count_admin_hits
: Logging & statistics → Count admin views

Turning this option on ("Yes") will enable counting of admin views. This does not affect the display of the view counter. Default value is "No", which means that the feature is disabled ("Off").

Back to top

Maintenance settings

The settings here will not give you additional features to enhance your gallery. Instead, they are meant for maintenance purposes only, so only enable the options here if you actually need them.

Enable debug mode

Default value:
Recommended value:
Database record name: debug_mode
: Maintenance settings → Enable debug mode

Coppermine 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 troubleshooting 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.

Do not post debug_output on the coppermine support board unless a supporter explicitely asks for it!

Details

Debug_output details

If this sub-section is all greek to you, don't worry: this entire section is aimed at coders for reference purposes - you don't need to understand it to be able to use Coppermine.

The debug_output will appear at the bottom of your gallery's output, together with a link to your phpinfo output for the admin. By default, the debug_output textarea will be displayed collapsed to make sure that it doesn't interfere with the width of your page. To actually see the debug_output, click on the show/hide toggle that will expand or collapse the debug_output field.

The debug_output contains the following sub-sections:


Display notices in debug mode

Default value:
Recommended value:
Database record name: debug_notice
: Maintenance settings → Display notices in debug mode

May be helpful to troubleshoot problems with your coppermine install - only recommended if you know a little PHP and you can understand the additional error messages this option shows. Notices being displayed don't actually mean that there is something wrong with your gallery. This option only applies if debug mode is enabled.

If you enable this option, you will see notices all over your coppermine-driven pages. This does not mean that there is actually something wrong with your install. As suggested above: leave notices_display off if it doesn't mean anything to you. In fact this can be considered a dev-only feature that merely exists to help the Coppermine dev team members to troublehsoot particular issues when coding.

The supporters on the Coppermine support board are not very keen to see posting where people complain that "funny output" resides on their gallery when it later turns out that the output they don't understand just is notices output, so if you have been sent here directly from a posting made by a supporter you should feel a little bit guilty for not reading first.


Gallery is offline

Default value:
Recommended value: n/a
Database record name: offline
: Maintenance settings → Gallery is offline

If you have to do maintenance work 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.

Putting your gallery into offline mode will only affect the legitimate visitors of your gallery. It will not have any effect on unwanted visitors (email harvesters, spam bots, hackers), so you mustn't believe that this is a security seal. Think of it as the putting the "closed" sign into the window of a shop. This setting will just put that sign into the window, but it will not lock the front door nor will it enable the burglar alarm.


Display news from coppermine-gallery.net

Default value:
Recommended value:
Database record name: display_coppermine_news
: Maintenance settings → Display news from coppermine-gallery.net

Starting with cpg1.5.0 there is a feed from coppermine-gallery.net that is being displayed for the gallery admin (and for the gallery-admin only) on each and every coppermine page to alert him of potential security issues and upgrades. You can toggle this option on and off in Coppermine's config (default is "on"). It is recommended to leave it enabled to make sure your coppermine install is always up-to-date.

This is meant as a service for gallery admins; you're of course welcome to disable this option at any time. Coppermine-gallery.net will not collect data from your site (although this would be technically possible to a certain extent). If you're concerned about this option, then disable it or review the code used. We (the Coppermine dev team) are not trying to spy on our users - the feed is only being used to alert you of issues related to coppermine - that's all.


Display reset boxes in config

Default value:
Recommended value:
Database record name: display_reset_boxes_in_config
: Maintenance settings → Display reset boxes in config

When enabled, there will be reset boxes all over the config screen that show if a particular value differs from default. This will allow you to quickly set the value back to default. This will however eat a lot of resources and will not work in all browsers. Recommended setting is "off", at least if you experience issues with the loading speed of the config screen.

Back to top

Usage of this page

This page is intended to be used as a reference both to help you configure your gallery, but it is as well meant as a tool for developers, plugin authors or - more generally speaking - those who want to expand their Coppermine-driven gallery into new directions using custom coding. We have put additional details into the pink boxes next to each config option that can be helpful for some additional tasks:

Restore factory defaults

There is a hidden option to reset the entire configuration and restore the factory defaults. You can't access that option using a button in Coppermine's user interface to make sure it isn't being tampered with lightheartedly out of curiosity. To restore the entire coppermine config to factory defaults, you need to go to the config panel and then add the parameter ?restore to the URL.

If your gallery resides at http://yoursite.tld/your_coppermine_folder/, your "regular" config panel's URL is http://yoursite.tld/your_coppermine_folder/admin.php. To go to the page where you can reset your configuration to factory defaults, go to http://yoursite.tld/your_coppermine_folder/admin.php?restore

On that "restore factory defaults" page, you need to tick the confirmation checkbox and submit the form by clicking on the button at the bottom.

Resetting the configuration can not be undone! Make sure that you understand the impact before restoring the config!