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

Table of Contents


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.

The Plugin Manager

Coppermine 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:

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):

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:

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

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.