Coppermine Photo Gallery v1.6.x: Documentation and Manual
Table of contents
Documentation Language Selection
Coppermine documentation
About Coppermine
About the documentation
Documentation Conventions
Features
Quick-Start guide
Table of contents
Minimum requirements
Server-sided minimum requirements
Web server
PHP support
mySQL database
Image library
Self-Hosting & Webserver Setup
Personal requirements
Requirements FAQ
Testing / bug reports
No support for alpha and beta versions
Areas to be particularly mindful of
Feature list
The report format
Availability
Languages
How languages work in Coppermine
Get rid of a particular language
Language fallback
Scope of internationalization
The language manager
Controls
Columns
Default
Language name
English
Native
Custom
Flag
Language file
Available
Complete
Enabled
Translation guide
Translators wanted!
Why translate?
Translations for which languages are needed?
Who can translate?
Character encoding
Editors & Tools
Full translations only
Step by step
Special issues
Language versions
Work in progress
Initial translation for release
Using older language files
Translating the documentation
Steps for translating the docs into your language
Make sure that the translation doesn't already exist
Create the structure
Copy the core language files
Start translating
Areas to pay attention to
Take care of the table of contents
Zip your translation
Further reading
Credits
Coppermine team
Contributors
Translators
Language files
Documentation
Free code used
Acknowledgements
Many Thanks
License & Copyright
Copyrights
License
Previous versions
Additional terms (license add-ons)
Preservation of author attributions
Marking of modified versions
Freedom
Known issues
Installation and setup
How to install the script
What the installer does
Related information
Server configuration
register_globals
Setting permissions
Permissions on different webserver types
Apache on Unix/Linux (CHMOD)
Basics
Groups in Lunix
Webserver daemon
Binary arithmetics
What good is all of this?
FTP application
Website control panel
Shell access
Ownership (CHOWN)
Apache on Windows
IIS on Windows
Asking for support on permissions issues
Permissions on folder level
The install screen
The classic install screen
The install wizard
Auto-Installers
Installation FAQ
Uninstall
Upgrading
Why upgrade?
Reasons for package releases
Changelog
Steps needed to perform when upgrading Coppermine (from any version)
Additional actions for updating from particular versions
Upgrading from versions cpg1.0,1.1,1.2.x or 1.3.x
Upgrading from cpg1.4.x to version cpg1.5.x
Plugins
Custom theme
Language files
Password encryption
Display FAQ
Outdated files
Safe mode
Upgrading from older versions of cpg1.5.x to the most recent version of cpg1.5.x
The update script
What it does
Purpose
Authorization check
When must the updater be run?
The version check tool
What it does
First run
Options
Display output
Only show potential errors
Hide images
Don't check for modified files
Do not connect to the online repository
Version comparison
Path
Missing
Permissions
Version
Revision
Modified
Comment
Repository link
Things that could go wrong using versioncheck
Wrong expectations
Upgrading FAQ
Downgrading from cpg1.5.x to an older version
Getting Started
Basic concepts
Initial configuration
Category/album/file structure
Resized images
Thumbnails
Intermediates
Originals
Recommended resizing setups
No full-size pop-ups
Allow full-size pop-ups with maximum space saving
"Regular" setup with moderate file space consumption
Your admin account
Check uploads
Consider bridging
What are your visitors allowed to do?
Change your coppermine's design
Typical setups
Single uploader without user interaction (Monolithic gallery)
Single uploader with user interaction
Multiple uploaders without new registrations (closed group)
Frequently Asked Questions
Setup / Configuration
Add-ons / Modifications / Hacks
Coppermine Support board
Themes
Themes that come with Coppermine
Upgrading your custom theme
Converting cpg1.5.x themes to cpg1.6.x
Edit style.css
Edit template.html
Edit theme.php
Validation Methodology
Content of a theme
Editing template.html
Template tokens
Important
List of tokens in template.html
Editing style.css
Tools
Web Developer Toolbar usage
Editor
List of classes in style.css
Additional stylesheet
Editing theme.php
Item types
The sample theme - a template to copy from
Method
Scope
List of items in theme.php
Theme Examples
Additional content
Additional content on the thumbnail page
Extra row between thumbnail rows
Extra table cell on each thumbnail page
Additional content on the intermediate-image pages
Directly next to the intermediate image
Directly next to the film strip
Additional content on the full-size pop-up
Summary
How the theme engine works
User-contributed themes
Preview user-contributed themes
Download user-contributed themes
Installing user-contributed themes
Copyrights of user-contributed themes
Asking for support on user-contributed themes
Contributing your own theme
Creating your custom theme
Rename your theme first
Tipps & tricks
Using WYSIWYG-editors
Modifying colors
Creating a Coppermine theme that matches your overall site layout
Introduction
Pre-requisites
Tools
Skills
Example
Pick a similar theme first
Start editing your theme
Replace the content from the sample with placeholder tokens
Adapting the style
Initial test
Editing template.html
Template tokens
Important
List of tokens in template.html
Editing theme.php
Item types
The sample theme - a template to copy from
Method
Scope
List of items in theme.php
Editing style.css
Tools
List of classes in style.css
Additional stylesheet
Theme examples
Summary
Additional content
Additional content on the thumbnail page
Extra row between thumbnail rows
Extra table cell on each thumbnail page
Additional content on the intermediate-image pages (displayimage.php)
Directly next to the intermediate image
Directly next to the film strip
Additional content on the full-size pop-up
Copyright-disclaimer in footer
Fair use
Unfair use
Dynamic (PHP-driven) content
Using anycontent.php
Custom header and footer
Theme-based dynamic content (theme.php)
Modifying core files
Graphic resources in themes
Menu Icons
Image Navigation bar
Rating images
Film Strip graphics
Progress image (loader)
Administration
Admin menu items
Enable / disable admin controls
Upload approval
Config
Categories
Albums
Sort my pictures
Groups
Users
Ban Users
My profile
Review Comments
Display Ecards
Batch add files
Admin Tools (Resize Pictures)
Keyword manager
Plugin Manager
Bridge Manager
View log files
Overall stats
Check versions
Update database
Export
phpinfo
Show news
Documentation
Admin mode for regular users
Admin menu items for regular users
Banning
What's new?
Scope
How banning works
Why banning by IP address is not recommended
Page controls
No banning when bridged
To do
Configuration
General settings
Language & Charset settings
Themes settings
Album list view
Thumbnail view
Image view
Comment settings
Contact form settings
Thumbnail settings
File settings
Image watermarking
Registration
User settings
Custom fields for user profile
Custom fields for image description
Cookie settings
Email settings
Logging & statistics
Maintenance settings
Restore factory defaults
Groups
The group control panel
Group names
Group types
Quota
Group permissions (Rating/Ecards/Comments)
Public albums upload
Personal gallery
Upload method
Assigned albums
Creating custom groups
Deleting custom groups
Triggering synchronisation (bridged only)
Membership in more than one group
Users
The user control panel
Page controls
Searching for user(s)
Creating new users
Editing users
Group membership
Lost passwords
Coppermine user account password
Coppermine in standalone mode
Coppermine bridged
mySQL account password
Categories
The categories control panel
Page controls
Top box "Sort categories alphabetically"
Middle box "Manage Categories"
Bottom box "Update/Create category"
Special category "User galleries"
Albums
The Album Manager
Creating albums
Renaming albums
Changing the album order
Deleting albums
Modifying albums/files
Album properties
Reset album properties
Admin vs. user
Album FAQ
Files
Editing files
Editing videos
Custom Thumbnails
Order of thumbnails
Types of thumbnails
Uploading custom thumbs
How it works
Naming scheme
Why can't coppermine create thumbnails for my videos?
Step-by-step instructions
Custom thumbnails FAQ
Keywords
Assigning keywords
Keyword separator or keyword delimiter
Editing/adding keywords
Keywords manager
Album keywords
bbCode
Purpose
Available bbcode tags
Dangers
More control
Exif data
What is EXIF
Different flavors
How it works
No exif support on the server
Limitations
EXIF manager
Plugins
What is a plugin?
The Plugin API
Where to get Plugins from?
Plugins that ship with Coppermine
Link Target (link_target)
Who is online? (onlinestats)
OpenSearch (opensearch)
Sample Plugin (sample)
User Gallery Alphabetic Tabbing (usergal_alphatabs)
Visible HookPoints (visiblehookpoints)
SEF_URLS plugin
The Plugin Manager
Uploading a plugin
Installing a plugin
Plugin Configuration
Uninstalling a plugin
Writing plugins
Performance
Configuration settings
General
Spiking
Server settings
PHP settings
MySQL settings
Third party tools
YSlow
Admin Tools
Available Tools
Update thumbs and/or resized photos
Filename → File title
Change values for (or clear) title, description and keywords
Delete original size photos
Delete intermediate pictures
Delete files that are older than a set number of days
Delete comments on missing files
Delete original image backup (watermark mod)
Reload file dimensions and size information
Reset view counters
Convert keyword separator
Usage
Errors
Error types
Soft Errors
Hard Errors
Unhandled Errors
Fatal error
Enabling debug_mode in Config
Manually enabling debug_mode
Turning debug_mode off
Common error messages
Database-related error messages
Common PHP errors
Upload-related error messages
Webserver response codes
Backup & Moving
Backing up your gallery
File Backup
Complete File Backup
Partial File Backup
Incremental File Backup
Database Backup
What needs to be backed up?
Database Backup Tools
phpMyAdmin
mySqlDumper
mysqldump
mysqlhotcopy
After the database backup
Moving your gallery
Moving on your webserver
Moving from one webserver to the other
Disadvantages of renaming
Changing Coppermine's URL in config
Watermarking
Alternatives
Turning the context menu off
Only display your precious content to legitimate viewers
Display on overlay
Client-sided watermarking
Uploading
Uploading pics by FTP / Batch-Add Pictures
What batch-add does
How batch-add works
Common mistakes
Batch-add does not work as expected
Files appear to be broken
Do not rename
Do not delete
Sorting
Capitalization matters
Computers see numbers differently
Uploading by HTTP
Upload interfaces
Flash-driven multiple-files upload interface
Usage
HTML-driven single-file upload interface
Usage
Upload troubleshooting
Permissions
Enable troubleshooting settings
Asking for support on upload issues
Step-by-step guide when asking for support
Example support request
Error messages
Impossible to move x to y
failed to open dir: No such file or directory
Undefined variable: HTTP_POST_VARS
Sorry there is no album where you are allowed to upload files
Allowed memory size of X bytes exhausted
Exec() has been disabled
Not a GD extension
Error executing ImageMagick - Return value 127
PHP running on your server does not support the GD image library
No file was uploaded ! If you have really selected a file to upload, check that the server allows file uploads
Destination directory x is not writable by the script
Server-sided restrictions
The PHP configuration file php.ini
Things to check
Upload mechanisms/methods
Memory usage during resizing
Comments
Allowing comments
Comments options
Spam issues
Captcha
Approval
Akismet
Summary
Reviewing Comments
Individual Comments
Bridging
What bridging does
Available bridge files
Pre-requistes
Authentication by cookie
Standalone version first
Coppermine users, groups and pics uploaded by users are lost when integrating
Backup
Integration steps
Using the bridge manager
Choose application to bridge coppermine with
Path(s) used by your bridge app
Bridge app URL
Absolute bridge app path
Relative path to your bridge app's config file
Cookie prefix
Bridge-app-specific settings
Use bridge app custom groups?
Enable/disable bridging
Recover from failed bridging
Synchronising the bridge app groups with Coppermine's groups
Bridging support
Some config options get disabled
Bridging files
Creating a custom bridge file
Bridging philosophy
Individual bridge issues
phpBB3
PunBB1.1.5
PunBB1.2
XMB
Subdomain issues
File system
Cookies
www-subdomain
Developer documentation
Adding/renaming/removing files
Target audience
Scope
Naming conventions
Adding files
Language files
Renaming files
Deleting files
Coding guidelines
Target audience
Scope
Indentation
Encoding
General guidelines
PHP code
Formatting
Control Structures
Function Calls
Function Definitions
PHP Code Tags
Nesting of HTML in PHP
Line breaks
Naming Conventions
Database queries
Documentation
HTML output
Image-tags in HTML output
Links in HTML output
Form elements in HTML output
Deprecated tags
Prefered tags
Credits for coding guidelines
Usability
Forms
Config options
Target audience
History
New features
Step by Step
Basic.sql
Update.sql
Admin.inc.php
Language file
Documentation
To Do
Database schema
Configuration file
Database reference within coppermine code
cpg16x_albums
cpg16x_banned
cpg16x_bridge
cpg16x_categories
cpg16x_categorymap
cpg16x_comments
cpg16x_config
cpg16x_dict
cpg16x_ecards
cpg16x_exif
cpg16x_favpics
cpg16x_filetypes
cpg16x_hit_stats
cpg16x_languages
cpg16x_pictures
cpg16x_plugins
cpg16x_sessions
cpg16x_temp_messages
cpg16x_usergroups
cpg16x_users
cpg16x_votes
cpg16x_vote_stats
Editing the documentation
Target audience
Edit existing documents
Add new documents
Moving content from one document to the other
Hidden features
Database structure
Header & footer blocks
Documentation internationalization
Expandable/collapsible "detail"-blocks
Help
Start and end anchors needed
Adding anchors to headings
Code
CSS class "code"
HTML-tag "pre"
CSS class "cpg_code"
CSS class "smallcode"
HTML-tag "textarea"
Combining HTML tags and CSS classes
No syntax highlighting
Javascript in Coppermine
Target audience
Javascript files location and organization
TODO
How to include javascript files
How to include JavaScript files in plugins
How to pass PHP variables to included javascript
Autostart JavaScript
Packaging a new release
Target audience
Git repository
Steps
Pull
Edit the version number
Replace version number in all files
Linux
Windows
Remove Byte Order Marks
Prepare an announcement thread
Edit the upgrade section of the docs
Edit the changelog
Update the versioncheck data
Push your changes
Merge branches
Create a release at GitHub.com
Clone master to fresh local directory
Create the archive
Upload the archive
Publish announcement thread
Update cpg16x.files.xml on the Coppermine home page
Update the download button on the Coppermine home page
Create news items
News item on sf.net
News item on forum
News item on home page
News embedded into existing galleries
Update the demo
Plugin Writing for Coppermine
Quick Start Guide
Intended Audience
People who should read this documentation
People who do not need to read this documentation
Why write plugins?
Preparations
Choose a name
Consider translations
Consider a config screen
Database changes
Support issues
Plugin versions
Core files
Naming conventions
Folders
Files
Archives
Coding
Use of Superglobals
Database access
Direct queries
Accessing database tables
Creating database tables
Deleting database tables
Storing your plugin's config values
Plugin Types
Using includes
Plugin Writing: Tutorial, API
Intended Audience
Required Skills & Knowledge
Recommended Software & Support Forums
"Hello, world" Plugin Tutorial
My First Plugin
Installation, Configuration, and Clean-Up
Installation with Simple Configuration
Installation with Configuration Parameters
Configuration during Operation
Uninstallation & Clean-Up
Linking to Custom Plugin Scripts
Adding a Button to Coppermine
Adding a Button to the admin menu
Adding a Button to the overall menu
Adding JavaScript to plugins
Multi-language Support
Distributing Your Plugin
Plugin Hooks
Plugin Class Properties & Methods
Global Variables & Constants
Reference list of plugin hooks
Target audience
Choosing Plugin Hooks
Finding Plugin Hooks
Plugin Hooks by File Name
Script: index.php
Filter: 'anycontent'
Filter: 'user_caption_params'
Filter: 'plugin_block'
Script: displayimage.php
Filter: 'file_info'
Filter: 'post_breadcrumb'
Script: thumbnails.php
Filter: 'post_breadcrumb'
Script: functions.inc.php
Filters: 'gallery_header' and 'gallery_footer'
Filter: 'thumb_data'
Filter: 'template_html'
Filter: 'page_meta'
Filters: 'thumb_caption' and all derivatives
Script: themes.inc.php
Filter: 'file_data'
Script: usermgr.php
Filter: 'usermgr_header'
Filter: 'usermgr_footer'
Script: pluginmgr.php
Filter: 'plugin_configure'
Filter: 'plugin_cleanup'
Script: plugin_api.inc.php
Filter: 'page_html'
Filter: 'page_end'
Filter: 'plugin_install'
Filter: 'plugin_uninstall'
Filter: 'plugin_wakeup'
Filter: 'plugin_sleep'
Script: init.inc.php
Filter: 'page_start'
Script: picmgmt.inc.php
Filter: 'add_file_data'
Plugin Hooks Alphabetically
Plugin Hooks by Hook Type
Plugin Hook Examples
Adding an upload method
Add tags for thumbnails display
Sanitization of Superglobals using Inspekt
Target audience
What's new?
Reason
What Inspekt does
Inspekt accessor methods
How to use Inspekt with Coppermine Photo Gallery
Using Inspekt
Inspekt in Coppermine
Consider the methods to use
Examples
Regular Expressions
Links
Git
Target audience
Caveats
What is Git?
Where is the Git repository hosted?
Recommended software
Alternative access using GitHub
Repository structure
Coppermine core files
Plugins
Checking out
Checking out the entire repository
Checking out a particular Package
Checking out a particular file
Refering to files downloaded from the Git repository
Is there no single package that I could download instead?
Download Tarball archives
Developers-only
Check out before checking in
Committing your code
Changelog
Obtaining write access
Step by step
Download the client application
Initial checkout
Revisions
Git file headers
Tools recommended by the devs
Database manipulation
FTP clients
Web development
Text editors
Picture Editors
Updating
Target audience
Hidden feature
Variables & Constants
System Global Variables
Coppermine Constants
Versioncheck
Hidden features
XML structure
To do list