Coppermine photo gallery v1.5.x: documentation and manual

How the theme engine works

When a Coppermine page is being parsed, the core code will call theme functions. If those functions exist in your custom theme, they will be taken into account. If a particular function does not exist in your custom theme, the core function will be used. The core functions (the default theme behaviour if you want to put it that way) reside in includes/themes.inc.php.

Therefore, you mustn’t edit includes/themes.inc.php, under no circumstances, as all your changes will be lost when upgrading in the future. Everything that possibly could be accomplished by editing include/themes.inc.php can be accomplished by editing themes/yourtheme/theme.php as well — stuff defined in your custom theme will take precedence over the core theme functions.

Step by step

Here are the detailed steps for translating coppermine language files:

  1. open english.php with your text editor
  2. Save the file immediately after opening under a different filename (to make sure you always have an unmodified english language file that can be used as a reference) — the filenames of the language files will decide how the language name will look in the dropdown list of the coppermine backend — use the english (roman characters) name of your language as the final filename, using lowercase in the name with no spaces or special chars (except «-» and «_» and the dot to mark the extension. If the language name itself isn’t self-explanatory, add info with an underscore.Examples: german.php, italian.php, greek.php, brazilian_portuguese.php
  3. Edit the header info (example content is highlighted):// info about translators and translated language$lang_translation_info = 'German';The name of your language in English$lang_translation_info = 'Deutsch';The name of your language in your mother tongue$lang_translation_info = 'de';The country code representing your language. If your language is spoken in several countries, choose the one most people will relate to your language$lang_translation_info = 'GauGau';Your name (or rather the name you would like to appear on the credits page)$lang_translation_info = '';If you prefer, your email address, which would normally appear on the credits page, can be left blank$lang_translation_info = 'http://gaugau.de/';Your website (goes to credit page). If you specify none, your profile page will be displayed instead$lang_translation_info = '2009-01-27';The date you translated/last changed the language file);
    Fill in the data you want to appear on the credits page as shown in the example above.
  4. The coppermine language file is used to dynamically replace php variables/arrays with the correct content. There are different ways those arrays are being filled — as shown in these examples (stuff that needs to be translated is highlighted):
    • $lang_day_of_week = array('Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat');A plain list of values in an array. Translate each word inside the quotes.
    • $lang_yes = 'Yes'; A value is assigned to a variable. Translate everything inside the single quotes.
    • $lang_common = array(' '=>'space', ','=>'comma', ';'=>'semicolon'); An array with key => value pairs. Only translate the value, the key must be left alone!
      'albums' => 'Albums',
      'pictures' => 'Files',
      );
    • Cascaded/multi-dimensional arrays have been dropped from cpg1.4.x to cpg1.5.x, so you don’t have to worry about them any longer.
    • $lang_forgot_passwd_php = <<< EOT
      You have requested a new password. If you would like to proceed with having a new password sent to you, click on the following link:{VERIFY_LINK}Regards,
      The management of {SITE_NAME}
      EOT;
      Var definitions using the syntax: make sure to only translate the plain text, leaving everything in curled braces and all html tags intact

    Translate the entire language file as described — you’ll find your way around in no time, even if you’re not a seasoned PHP coder.

  5. Test your translation: upload your language file to your server and browse your gallery, adding an additional parameter lang=your_language_name to the URL (e.g. http://yoursite.tld/coppermine/?lang=german). Make sure to test as many aspects as possible from the file you creaeted, especially in the creation, renaming and deleting of users,categories, albums, pictures and comments.
  6. Proof-reading: if you can, let someone else (preferably non-tech user) test your translation as well. You might be surprised as to what they will discover…
  7. Post your language as a zipped attachment of the thread «: Translations for CPG1.5.x».
    You can post the attachment as a txt file or you can put it inside of a .zip archive, but please don’t use other exotic archival formats such as .rar, .ace, etc.

cpg15x_banned

If you want to refer to this table code-wise, use $CONFIG.

Field Type Description References
ban_id Integer Primary key. Unique identifier for a ban.
user_id Integer The user that this ban applies to. Banned users are unable to use the gallery in any way.
user_name Text ( A username that this ban applies to. Registrations from a banned username are refused.
email Text ( An email address which this ban applies to. Registrations from a banned email address are refused.
ip_addr Text ( An IP address or wildcard IP (eg. 192.168.0.%) that this ban applies to. Visitors with a matching IP address will be unable to use the gallery in any way.
expiry Datetime The date/time that this ban is set to expire.
brute_force Integer A counter used to track failed login attempts which may lead to an actual ban. Counts down from the config setting ‘Number of failed login attempts until temporary ban’ to 0.

Coppermine Support board

support board

I don’t know PHP/mySQL…

No problem with that, everyone stars as a newbie. Just don’t start each and every posting by stating «I’m a newbie», «I don’t know anything about PHP» etc.Usually, one can acertain that from your question itself. There’s no need to apologize. Most of us can still remember when we were in your shoes.

I’ve posted my question a while ago, but nobody answers. What the…?

The support board is not a hotline. Although there are many visitors to the site, only a few do actually support — on a unpaid, voluntary basis. Yes, we don’t receive remuneratio for our contributions and we each have a life, a job, family and more. We are away sometimes, as well. So, please, be patient, read the docs and search the boards while you are waiting.If you don’t get an answer to your question:

  • make sure you have given us enough time to react (days, not hours!)
  • maybe nobody knows the answer to your problem
  • maybe your question has been asked very often
  • maybe your posting has been rude or impolite and you’re ignored for that reason
  • maybe you requested a feature that requires a lot of coding, and none of those who are able to do it have a need for the feature

How should I write my question?

If you have a question, make sure you provide as much information as possible:

  • a link to your gallery, with a test account ID and test account password, is most often the only way to help — provide it with your question, or even better: edit your profile on the support board and enter the url of your page there!
  • when addressing server issues, make sure to provide information on your server (OS, server, PHP version, mySQL version, gd lib version, safe mode on/off?). Most information can be retrieved by
  • if it’s a client issue, give us information at least to your client’s OS and browser
  • Give us a screenshot, if necessary
  • use a proper subject line: state in the subject line what your question is actually about! Most supporters are reluctant to answer to a posting that has a silly subject line like «I have a question» or «Install problem» or «feature request» or «help me pleeeeaaaase»

I’ve run into trouble. What should I do first (before posting on the board)?

  • read the readme that comes with the coppermine distribution
  • read the documentation
  • read this FAQ
  • Search the support board
  • enable debug mode (log in as admin, config, debug mode)
  • choose the right support board: if you’re running the phpnuke-port of coppermine, don’t post in the support board for the standalone version and vice versa

If you are posting in the English support boards, please do not post in some other language — in this way, others may benefit from your question (and the answers you receive ), too. Don’t be afraid to write «poor english» — no one will laugh at you, and most of our visitor’s first language isn’t english to begin with!

We have language-specific support boards for Chinese, French, German, Italian,Persian and Spanish.

Who are you anyway?

We are a group of people who decided to form a team to develop Coppermine further — check the team page for details…

This FAQ is a work in progress, please contribute in the Coppermine Photo Gallery Support Board (don’t contact dev team members or supporters to ask for fixes of your Coppermine install). Please report any bugs, typos etc.Check the online-version of this document for updates!Have fun!

$LastChangedDate: 2018-12-21 21:21:36 +0100 (Fr, 21 Dez 2018) $
$Revision: 8884 $

Preparations

Before starting to hack away, you should make some preparations and maybe sketch the layout of your plugin.

  • Your plugin needs a meaningfull, simple name. Make sure that a plugin doesn’t already exist with the same name you’ve chosen. Then create a sub-folder within the plugin folder and name it as you see fit. Make sure to use web-safe names (only alphanumerals, all lower-case, no special chars except underscore.
    For clarification: there can be only alphanumerals in a plugin’s folder name. There mustn’t be any dots or other special chars in it. The only exception is the underscore (_)
    your_coppermine_folder/plugins/coffee_maker/
    Coming up with a folder name sounds easy, and you may be tempted to just use the name my_plugin or foobar to be able to start coding right away. However, you have to keep in mind that while you progress writing your plugin, the folder name will appear hard-coded into your plugin (possibly many times), so it will be hard to change it later. That’s why it’s advisable to come up with a good folder name in the first place: it should be descriptive, consist of two or three words and mean something initially. A folder named «coppermine_candy» wouldn’t mean much — the word «coppermine» would make no point, as the plugin already resides within coppermine, and the word «candy» would no describe what your plugin does. Better, self-explanatory names for plugins would be «rename_users», «thumbnail_dropshadow» or «backup_files». If someone else already has created a plugin that will do something similar to your plugin, make sure to use a name that differs from the other plugin. The second part of your plugin’s name could be your nickname or real name as well — something like «slideshow_nick» as a plugin short name would be OK. It’s not a bright idea to try to «cheat» by naming your plugin «aaaaaaa» in an attempt to make it stand out in the plugin list (the plugin list is sorted alphabetically) — the staff on coppermine-gallery.net will rename such plugins. Also please don’t use abbreviations that don’t mean anything — names like «dffds» for «damn fast flash-driven slideshow» are not easy to memorize — instead you should use something like «slideshow_flash»; if a user looks at the list of plugins on his gallery using his FTP application (during upload), it should be obious what plugin each sub-folder corresponds to.
    For details on a good name for your folder, please read up the sections «» and «» as well.

  • Coppermine is an international project, with users from all over the world. If you should decide to contribute your custom plugin later, it would be a good idea to design it properly in the first place: keep all strings that could need translation in a separate include file and only hard-code the corresponding vars into your code.

  • If your plugin is only going to add one single feature to coppermine without anything to configure, then there’s no need to provide a separate config screen for your plugin. However, if your plugin has options the end user could configure, it’s a good idea to come up with a config screen for your plugin.

  • If your plugin needs to write to the database or even changes the structure of tables, it’s almost mandatory to come up with a routine to write the needed database changes during install of the plugin. It’s a good idea as well to come up with a method to undo the database changes if the user should later decide to disable/uninstall your plugin. If this is the case, you should preferably come up with a database setup screen as well (see «»).

  • For every non-trivial plugin that gets published on the coppermine home page, there will be an announcement thread on the board. It’s a good idea to provide the URL of the announcement thread together with your plugin, preferably even a clickable link.

  • Although you may not plan to develop your plugin even further, others may do so. Therefore, it’s a good idea to provide a version number with your plugin.

cpg15x_banned

If you want to refer to this table code-wise, use $CONFIG.

Field Type Description References
ban_id Integer Primary key. Unique identifier for a ban.
user_id Integer The user that this ban applies to. Banned users are unable to use the gallery in any way.
user_name Text ( A username that this ban applies to. Registrations from a banned username are refused.
email Text ( An email address which this ban applies to. Registrations from a banned email address are refused.
ip_addr Text ( An IP address or wildcard IP (eg. 192.168.0.%) that this ban applies to. Visitors with a matching IP address will be unable to use the gallery in any way.
expiry Datetime The date/time that this ban is set to expire.
brute_force Integer A counter used to track failed login attempts which may lead to an actual ban. Counts down from the config setting ‘Number of failed login attempts until temporary ban’ to 0.

About the documentation

The Coppermine dev team strongly recommends enabling JavaScript and using a modern browser (with CSS and JavaScript according to the DOM standards) to read the documentation for a richer experience.

Text boxes

There are text boxes in this documentation that have special meanings:

Examples that are meant to illustrate the instructions given are displayed like this!

Additional information that should not be overlooked is being displayed like this.

Hints that usually will lead to a bigger insight into the overall mechanisms within Coppermine or that will help you applying features successfully are being highlighted like this.

Warnings about things that can easily go wrong if a mistake is being made are being displayed in this manner. It is advisable to pay close attention to the text within such boxes.

Things that can go wrong depending on user interaction or user input are being displayed like this.

Actual errors or issues that can have a huge impact are being displayed like this. This is the most serious kind of boxes — their content is very important to read.

Longer sections of code examples (can be PHP, HTML, CSS or JavaScript) are displayed using the typewriter icon in front of them.

Links

All «regular» links (that don’t have a special icon displayed next to them) are internal links, i.e. they refer to a section of this documentation and therefore allow you to navigate this documentation. The exception to this rule are the following links:

Creating a custom bridge file

In theory, coppermine could be bridged with all forms of third party applications that have a user management/authentication. There are thousands of applications available that could be potential candidates. Just because of the sheer number of possible bridges, but as well because of other restrictions (non-free software, lack of time, lack of need), the coppermine devs can not come up with a huge number of bridge files. That’s why there is only a comparatively small number of bridge files available. If you are looking for a bridge file for another application that is not being covered by the bridge files that come with coppermine out-of-the-box, you’re welcome to search the coppermine support board if there already is an existing user-contributed bridge, or (even better) you’re encouraged to come up with a bridge file of your own and publish it on the board. We (the coppermine dev team) have to rely on user contributions for most potential bridge candidates.

Sadly, there is no particular piece of documentation available (yet) that explains how to create a custom bridge file, so the best method to create your custom bridge file is to look at existing bridge files and modify one to fit your needs.

What bridging does

Coppermine can be integrated with other applications in terms of user management and sharing a common login on your overall website; this is what we call «bridging». It can create a more seamless end user experience, as your users will only have to register once; their login will stick both on the Coppermine pages as well as the pages you bridge with.

By default, bridging is turned off, and those who do not want to use it can safely leave it off forever. There are however (after there is already content in Coppermine), so if you intend to use bridging you should enable it before you start adding content.

Originally, Coppermine bridging was designed to bridge with BBS apps. Later, bridges for other apps (that don’t fall into the category «BBS») have been added — mostly Content Management Systems (CMS). However, the reference to BBS apps remained in some documents and strings. No reason to get alarmed.

Bridging does not integrate your gallery and the application you bridge with in terms of visual appearance. If you want a seamless visual integration, create a custom theme for your gallery that matches the look of your bridge app or your overall site and add links pointing from Coppermine’s navigation to your bridge app and vice versa.

When bridging is turned on, Coppermine drops the user management it comes with and uses the user management of the app you bridge with (i.e. your BBS app). Subsequently, your users will register and log in on your bridge app (BBS). After they do, they may be redirected to coppermine (if they came from coppermine’s login page in the first place and your bridge app allows redirects).

Character encoding

Many languages have special alphabets other than the latin set, or have additional characters (like ä ß à á â ã å æ ç þ ð ø). Many of these special chars have what are called html equivalents (e.g. &auml; for ä), but you must not use these html equivalents of your special language characters when doing your translations, as unwanted side-effects may appear with the usage of JavaScript!

No matter what encoding you use to contribute your translation, the encoding with which your translation contribution will be added to the package will be utf-8. In other words: some coppermine developer will have to transform your proprietary encoding to utf-8 before it can be used, so if you can you should use utf-8 in the first place.

Coppermine adds a charset meta tag to the header of each ouput file to instruct the browser how to render special chars. You should add the name of the charset you’re using for your translation at the very start of the language file, e.g.

$lang_charset = 'iso-8859-1';

http://www.w3.org/International/O-charset-lang.htmlwindows-1252iso-8859-1

You’ll have noticed that coppermine language files come in utf-8 encoding. You do not have to concern yourself with the creation of the utf-8 version if you have no idea how to accomplish this — the dev team will take care of that. However, your language file will finally go into the package as UTF-8 file. Subsequently, if you want to create a perfect language file, create it in utf-8 in the first place.

Bridging files

In coppermine’s root folder, you will find a subfolder named «bridge» — this is where the bridge files reside in. When coppermine is run (i.e. a visitor browses a coppermine-driven page), coppermine includes the bridge file that relates to the app you have bridged with. Using this file, coppermine does what is needed to authenticate the visitor. Even if coppermine is not bridged at all, there is still a file that is being included from the bridge folder («coppermine.inc.php») that determines what tables to use.

Usually, you should not edit the files within the bridge folder — in fact the only important thing that you have to remember is that coppermine needs the bridge folder and the contents even if you haven’t enabled the bridging feature. Just leave the files as they are. Power users who really know their way around are of course welcome to edit the bridge files and adjust them to their needs.

There have been users who tried to «run» the bridge files themselves directly in your browser — this will not work and do nothing but result in an error message. The bridge files are not meant to be run standalone — they get included by coppermine during runtime. If you have no idea what this means, just ignore those files and leave all in place. It won’t hurt to have bridge files reside on your webspace even if you don’t use the bridge that corresponds to a particular bridge file.

Features

Coppermine comes with many features. Below you’ll find an incomplete list. Features that are new in cpg1.5.x (compared to cpg1.4.x) are marked accordingly.

Details

  • Installer
    • easy (installer provided)
    • improved, wizard-like installer (cpg1.5.x)
  • Registration & Login
    • (cpg1.5.x)
    • config settable for registration feature (cpg1.5.x)
    • (cpg1.5.x)
    • (activation link)
    • resend activation link feature (cpg1.5.x)
    • by admin
    • for admin
    • optional (cpg1.5.x)
    • feature (cpg1.5.x)
    • (cpg1.5.x)
  • User management
    • (private galleries, groups)
      visitors can register for themselves (if the admin allows registrations). Alternatively, admin can create user accounts.
    • User management is group-based
    • Permissions are managed/assigned per group
    • : integration of user management with various bbs (like phpBB, YaBB SE, SMF, Invisionboard, vbulletin)
    • bbs integration settable with a wizard-like user interface ()
    • more fields
  • Managing categories and albums
    • arrangement of pictures in categories, optional sub-categories and albums
    • users can create albums in admin allowed categories (cpg1.5.x)
    • New category hierarchy system (cpg1.5.x)
    • users can (and admin can FTP-upload and to database)
    • caption, title, description and for each picture (searchable)
    • for admin
    • image rotation
    • multi-pic upload
    • option to choose will help in creating nicer looking thumbnail rows and cols
    • optional (cpg1.5.x)
    • allowed filetypes message displayed on upload screen (cpg1.5.x)
    • animated graphics on upload screen to indicate the upload progress (cpg1.5.x)
    • non-latin characters in file names are being replaced with transliteration if possible and underscore if there is no transliteration for web-safe file names regardless of user skills (cpg1.5.x)
  • Displaying images
    • Meta albums:
      admin can specifiy what virtual extra albums can be used to provide alternative «views» or methods to browse the gallery:
      • last commented
      • last added
      • random picture
      • browse-by-date meta-album (cpg1.5.x)
      • most viewed
      • top rated
      • favorites
    • slideshow viewer
    • option to display a clickable flimstrip of thumbnails below the image display
    • watermarking option (cpg1.5.x)
    • thumb cropping and sharpening (cpg1.5.x)
  • User interaction
    • option (cpg1.5.x)
    • (cpg1.5.x)
    • (cpg1.5.x)
    • (cpg1.5.x)
    • e-card feature
    • (cpg1.5.x)
    • language selection option in template
    • Voting/Rating
    • optional (cpg1.5.x)
    • (cpg1.5.x)
    • optional with captcha (cpg1.5.x)
    • users can to admin
    • favorites: visitors can add images to their favorites for future visits
  • Statistics
    • public display of number of images, views and last uploads
    • browser and os stats for admin (cpg1.5.x)
    • overall stats (cpg1.5.x)
    • album hits counter (cpg1.5.x)
    • public stats can be turned off (cpg1.5.x)
  • Searching
    • advanced search (boolean operators)
    • regular expressions in search (cpg1.5.x)
    • clickable keywords
    • tag cloud feature (cpg1.5.x)
  • Administration
    • basic authentication for update script (cpg1.5.x)
    • reset to default for individual config options (cpg1.5.x)
    • Uploaded files can be un-approved by the admin to temporarily hide them (cpg1.5.x)
    • Direct banning option on comment approval screen (cpg1.5.x)
    • User management screen with additional criteria, showing user interaction (cpg1.5.x)
    • plugin-API to allow the creation of user-contributed enhancements
    • many plugin contributions available
  • Documentation
    • online help feature for the admin pages
    • on comments (cpg1.5.x)
    • complete admin documentation available
    • multi-lingual documentation
    • documentation split into sections for easier reading (cpg1.5.x)
  • Miscellaneous
    • picture information stored in database
    • full multimedia support
    • multi-lingual
    • English as a language for un-translated entries in language files
    • all features customizable with web interface (admin section)
    • EXIF/IPTC support
    • URL parameters refer to absolute positions instead of relative ones for search engine friendliness (cpg1.5.x)
    • API for Coppermine to be used with applications like Koppermine and others (cpg1.5.x)
    • to alert him about updates (cpg1.5.x)
    • usage of Inspekt for the sanitization of superglobals, a tool to create secure PHP application (cpg1.5.x)
    • granular control for : no access, thumbs only, thumbs + intermediate only, thumbs + intermediate + full-size (cpg1.5.x)
    • Prevent search engine spiders from indexing meta albums (cpg1.5.x)
  • Visual appearance
    • template/theme system
    • option to of a category instead of just statistics of the category
    • option of turning on OR off the
    • option to send visitors directly pop-up (cpg1.5.x)
    • optional (cpg1.5.x)
    • alternating colors for table rows (cpg1.5.x)
    • optional tag cloud (cpg1.5.x)
    • for easier navigation (cpg1.5.x)
    • ajax filmstrip (cpg1.5.x)
Оцените статью
Рейтинг автора
5
Материал подготовил
Андрей Измаилов
Наш эксперт
Написано статей
116
Добавить комментарий