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

Plugins

What is a plugin?

Starting from cpg1.4.0, Coppermine comes with a plugin API that enables plugin authors to modify Coppermine features without hacking the core code, making upgrading easier, as modifications don't have to be re-applied every time you upgrade your Coppermine version. It's recommended to use plugins instead of code modifications that require hacking the core code.

The Plugin API

The plugin API consists of several "hooks" all over the core code of Coppermine that allows plugin authors to interact with Coppermine functions, overriding or adding features. There are limitations to what can be done using a plugin, as the number of hooks is limited. As a result, not every change of Coppermine behaviour that could be accomplished by hacking the core code is possible to achieve using the plugin API. However, using a plugin is more elegant and usually much easier to install and get running (at least for the end user) than a crude core code hack. Installing and configuring a plugin doesn't require the Coppermine admin to mess with the source code - you simply upload the plugin, install it, configure it and you're done. If the plugin has been coded as suggested and is mature enough, it should come with a configuration screen that makes editing source code irrelevant.

Where to get Plugins from?

As suggested above, the plugin API provides developers an interface to come up with feature enhancements of Coppermine that they can distribute on whatever channels they prefer. All plugins that the Coppermine development team is aware of (and that are being released under a suitable license) are available on the official Coppermine page.

Additionally, many plugins that the Coppermine developers are aware of or plugins that they have created themselves are being stored in the subversion (SVN) repository (→ What is subversion?). This way, developers can work on the code of the plugins in the team, where each team member can contribute. In fact, subversion is meant to make sure that none of the edits and improvements made get lost accidentally. So, if you want the bleeding edge, the most recent version of a plugin, you're welcome to check out the subversion repository as well. You have to understand though that the usage of subversion itself goes unsupported on the Coppermine support board, so you mustn't ask questions there about SVN. If you decide to use the SVN version of a plugin, make sure to have read the section Checking out plugins.

Plugins that ship with Coppermine

Out of the box, Coppermine comes with some plugins that are meant to illustrate what plugins can be used for. Those plugins are by default disabled, so you (as admin) have to enable them deliberately (using the plugin manager) if you want to use them.

The plugins that come bundled with the Coppermine package are not being covered by the same level of support that the core components come with. There is no guarantee that particular plugins will remain in the bundle in future releases.

You can find more plugins on the board "cpg1.5 plugin contributions" on the Coppermine Support Forum, both from Coppermine developers and from user contributions.

• Link Target (link_target)

  Changes the way external links are being opened: when this plugin is enabled, all links that contain the attribute rel="external" will open in a new window (instead of the same window). This has the same effect as the use of the target="_blank" attribute, but it will not render your HTML output invalid.
  This plugin has an impact mostly on the "Powered by Coppermine" link at the bottom of the gallery output. It is strongly recommended not to use the deprecated target attribute for links any longer, as suggested in the article New-Window Links in a Standards-Compliant World by Kevin Yank.
  The dev team recommends not to use this plugin: opening links in a new window means bossing around your site visitors. All of them are aware how to open a link in a new window or browser tab if they want to: you should respect their decision and leave the decision to them if they want to leave your page for good.
  We suggest to think twice before enabling this little plugin: you will lose visitors who don't like to be forced to open links in new windows, and you will confuse complete newbies.
  This plugin has been bundled with cpg1.5.x to stop the requests from users who are still trying to open external links in a new browser window. Although the dev team is not fond of opening links in a new window we're aware that some will want this feature badly. So use it wisely if you must use it at all.

• Who is online? (onlinestats)

  Displays a block on each gallery page that shows users and guests actually online. The output looks roughly like this:

  Who is online?

  There are 42 registered users. The newest registered user is foobar. In total there are 12 visitors online: 3 registered user and 9 guests. Most users ever online: 2 on 08/27/08 at 19:44. Registered users who have been online in the past 10 minutes: Bill, Linus, Steve.

  The output is a page element similar to the category list or album list, so you can move the block around using the config option The content of the main page. Once the plugin has been installed, the "who is online" block will not be actually visible: you need to actually enable it by adding the string onlinestats (separated with a slash) to the above mentioned setting "The content of the main page", so if that config option contained before catlist/alblist/random,2/lastup,2 you could change that to catlist/alblist/random,2/lastup,2/onlinestats to display the output of this plugin on the index page.

• OpenSearch (opensearch)

  An implementation of OpenSearch for Coppermine. When enabled, visitors can add the gallery to their browser's search bar.
  What the plugin actually does is adding the corresponding meta tag to the header of your Coppermine-driven pages and creating the needed XML file that describes your gallery, based on what you have specified for "Gallery name" and "Gallery description" in Coppermine's config.

• Sample Plugin (sample)

  This is a sample plugin. It will not do anything particular useful - it is just meant to demonstrate what plugins can do and how to code them. When enabled, it will display some sample text in red. Remember that this output will be displayed to anyone visiting your gallery, no matter what privilege level the visitor has, so if you have enabled this plugin out of curiosity, remember to turn it off once you have seen what it does.

• User Gallery Alphabetic Tabbing (usergal_alphatabs)

  What it does: displays tabs from A to Z at the top of user galleries that visitors can click on to directly jump to a page that displays all user galleries of the users who's username starts with that letter. Plugin only recommended to be used if you have a really large number of user galleries.

• Visible HookPoints (visiblehookpoints)

  Tool for plugin developers to locate plugin entry points (plugin hooks) and array information. Do not enable this plugin unless you want to start developing your own plugin.
  In some cases the output of a hookpoint is not the same as its "echo" point. A good example of this is the 'gallery_footer'; it is processed very early and its echo point is above the doctype declaration, while the hookpoints actual output is just above the "powered by" text at the bottom of the document.
  • The first marker is placed in the HTML at the hookpoints "echo" point.
  • If the hookpoint is an array then the marker has "_ARRAY" appended to it
  • If the hookpoint is not an array it has "_HTML" appended to it and the marker without any appendage is tacked onto the filtered var
  • In all cases a var_dump of that filtered variable is output to the source html as an html remark just below the echo point
  There is now a statistics output showing how many times each hookpoint was called. There is also a timeline of when each hookpoint was executed relative to the scripts start time.

• SEF_URLS plugin

  The plugin enables "Search-engine-friendly URLs" - this is an experimental plugin and should be used with caution.
  The SEF_URLs plugin has been removed from the package for cpg1.5.x due to the known issues that made it not ready for production use. It can be obtained from the official Coppermine homepage - check the corresponding announcement thread "SEF_URLs plugin for cpg1.5.x". Please note that the plugin goes unsupported, so please don't ask questions about it.

The Plugin Manager

The plugin manager is the central place from where you upload, install, configure and remove plugins. It can be acceessed in two ways:

• Using Coppermine's navigation

  Click on the admin menu item "Plugin manager" when you're logged in as admin. Alternatively, log in as admin, go to Coppermine's config, expand the "General settings" section and click on the link "Manage plugins" next to the "Enable plugins" option if you plan on using plugins.

• Directly accessing the plugin manager

  Make sure that you are logged in as admin, then directly enter the plugin manager's url in the address bar of your browser, e.g. http://yoursite.tld/your_coppermine_folder/pluginmgr.php

The plugin manager organizes the plugins you have in your Coppermine directory. It is important to understand the difference between uploading plugins and installing plugins. When you copy a plugin to the Coppermine plugins folder (using the Upload button on the plugin manager or via FTP), you have merely uploaded the plugin files. The plugin is not installed yet. When you install a plugin, Coppermine runs the plugin's installation routine to configure and activate the plugin so that it will be executed when people use your gallery. To clearly show which plugins are running and which are not, the plugin manager is separated into three sections (see screen shot above):

• an overall toggle that enables/disables the use of plugins (upper section; can be changed on the config page as well)
• the plugins that are installed and running (middle section)
• the plugins that exist within the plugins folder of your server's hard drive but have not been installed and therefore are not running in your Coppermine gallery (lower section)

By default, Coppermine comes with some sample or code plugins (none of them are enabled by default though), additional plugins can be found on the corresponding section of Coppermine's forum.

Uploading a plugin

Unless you're going to code your own plugins, they usually come packaged up already, compressed into a zip file. There are two options how to upload a plugin:

• Method 1: Using the upload interface on Coppermine's plugin manager page

  • Download the plugin you need from the internet (usually the Coppermine page) to your local hard drive
  • Click the "browse" button on the plugin manager page
  • Navigate to the plugin zip file you just have downloaded to your local PC's hard drive
  • Click "upload"
  This is the more elegant and easier method - you just use the upload control on the plugin manager page and the zip file you uploaded gets extracted from the archive and stored on the server within the proper folder. There are two pre-requisites though:
  • PHP running on your webserver needs zip support - not all webservers have zip support enabled.
  • the script needs write permissions within the plugins folder.
  If you fail to fullfil those two pre-requisites, this simple method (upload interface) won't work for you (i.e. you will get error messages when trying, or the plugin will even simply fail to work without an error message at all). If this is the case for you, it's recommended not to mess with server setup (unless you're an expert and the server is yours to administer), but just to use the second upload method described below.

• Method 2: Uploading the unzipped plugin files using your FTP app

  • Download the plugin you need from the internet to your local hard drive (same step as above)
  • Unpack the zip file into a folder on your hard drive (preserving the folder structure of the plugin)
  • Use your FTP app to upload the unpacked plugin files into the plugin folder of your Coppermine install on your server, preserving the structure of the zip archive.
    For example: if the plugin contained the folder "foobar", which held the actual plugin files, you upload the whole folder "foobar" and all of its contents into the plugins folder. The resulting folder structure on your server should be something like /your_coppermine_folder/plugins/foobar/

After uploading the files (you may need to refresh the plugin manager page), the plugin you just uploaded should show in the list "Plugins Not Installed". If it does, you can continue to the next step and install the plugin.

Installing a plugin

Installing a plugin is fairly straightforward - just click on the -icon next to the plugin. The install will enable the plugin to be executed when Coppermine is being run (depending on the plugin's purpose). Some plugins come with a configuration screen that will be executed right after the install - if this is the case, configure it accordingly.

A check routine tries to determine if a plugin has been designed for your version of Coppermine.

• If the check succeeds, the install plugin icon with a tick mark will be displayed: .
  The plugin has been designed for your version of Coppermine and therefore should work as expected. You can install that plugin by clicking on the icon.
• If the check fails, i.e. if the checking routine determines that a plugin was definitely not designed for your version of Coppermine, a cancel icon () will be displayed next to the plugin. You can not click that icon and subsequently you can not install the plugin.
• If the plugin's code has not been designed with the checkin routine in mind (which will be the case for all plugins designed/released before 2010-01-24), it won't be possible for the script to determine if a plugin was determined for a particular version. The plugin manager icon without the tick mark () will be displayed next to such plugins. You can click on such icons to start the install, but you will first be prompted about the dangers that lie in installing plugins that haven't been designed for your version of Coppermine).
  Details

  Version determination fails

  Shortly before the release of cpg1.5.x as a release candidate (in cpg1.5.3) a feature has been added to the plugin manager that attempts to determine for each plugin if the plugin was designed to be used with your Coppermine version. This feature was added as an additional precaution: installing a plugin that hasn't been designed for your Coppermine version might break your entire gallery. A corresponding setting has been added to the specifications for a plugin: plugin designers are requested to specify within the code of their plugin what version of Coppermine their plugin is supposssed to work with.

  • If you're a plugin writer, read up the details in Plugin Writing for Coppermine → Core files → configuration.php → $plugin_cpg_version.

  • If you're just a plugin user and not a plugin author, you don't need to read up those details - you should just be aware of the mechanisms used: there is no guarantee that the author of the plugin has added the Coppermine version requirements settings to the plugin's core code. If that piece of data hasn't been added this does not mean that the plugin is badly written or something like this: when you're attempting to install such a plugin, you will get a message that says Could not determine the version requirements for this plugin. This is usually an indicator that the plugin was not designed for your version of Coppermine and might therefore crash your gallery. Continue anyway (not recommended)?. Please understand that this message does not mean that the plugin itself is at fault. It basically means that you as a gallery admin have to make sure that the plugin you're about to install has actually been designed for the Coppermine version that you are using. To do so, review the readme file that might come with the plugin and review the announcement thread of the plugin.

  Please do not post questions on the Coppermine support board like "I got warned that the plugins version cannot be determined. Shall I continue to install or not?": you should be able to see for yourself if the versions match. If they don't or you can't determine the version, install the plugin at your own risk. The message means exactly what it says: that the version can't be determined, that's all. It doesn't say "don't use the plugin". It just says "hey, I'm not sure if the plugin you're about to install matches the version of Coppermine". The message just means that you (as a human) have to check because the machine can't. So you check: what version of the plugin are you trying to install? If the plugin has been designed for your version of Coppermine, you're fine to go ahead and install the plugin even if the warning shows up.

  Ideally, the number of plugins that don't contain the Coppermine version requirements settings should decrease in the future.

Plugin Configuration

Some plugins may need to be configured during install, others may have a separate configuration page that can be accessed at any time. This depends on how the plugin author wrote the plugin, so we can't give any recommendations within this documentation. Some plugins may even need to be configured before actually being uploaded (especially plugins in alpha or beta stage - these may come without a browser-driven configuration page and require you to modify the plugin's code to configure the plugin). If unsure, take a look in the unzipped plugin archive on your hard-drive - usually, plugins that require you to edit or configure anything come with a README file that tells you how to do so.

Uninstalling a plugin

Executing a plugin might be consuming resources or not work as expected, so you might want to uninstall a plugin at some time (maybe because you just tried it out and it doesn't work as expected for you). It's recommended not to just delete the plugin's subfolder using your FTP app (because the plugin might have applied database changes that need to be undone). Instead, you should go to the plugin manager and click on the -icon next to an active (installed) plugin. The plugin then should get uninstalled and turn up in the list "Plugins Not installed". It's safe to leave the sources of an unneeded plugin on the server, so there should be no need to delete the plugin right after uninstall, however you may as well delete it, especially if you're short on webspace and the plugin eats up a lot of space.

To finally delete an inactive plugin from your server's plugin folder, click the -icon next to a plugin that is in the list "Plugins Not installed". If the script fails to delete a plugin this way (because of lacking permissions to do so on file/folder level), you can use your FTP app to delete the particular plugin's sub-folder within Coppermine's "plugins" folder (deleting manually). As with all delete operations, you should make a local backup before deleting if you're not absolutely sure what you're doing.

Writing plugins

There's some documentation available for plugin authors, so the best method to learn how plugins work is by looking at the source code. Examine the code of the plugins that come with Coppermine, or take a look at some that are available for download from the plugin contributions sub-board on the Coppermine web page.

If you accomplished writing a plugin, we ask you to share it with the Coppermine community by posting it on the appropriate board (this is of course not mandatory, but we'd appreciate to see your contribution). We would welcome contributions to the plugin API documentation and the reference list of plugin hooks as well, or other related documentation.

Although it is not mandatory (technically speaking) to add instructions to a plugin, it is being recommended that you include a readme file with your plugin that explains what it does and how to use it.

We ask plugin authors as well to keep i18n in mind: not everybody will be using the language you used. Therefore, it's always a good idea to keep possible translations in mind when designing your plugin.

Please refer to the Plugin Writing section for details.