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 Git repository (→ What is Git?). This way, developers can work on the code of the plugins in the team, where each team member can contribute. In fact, Git 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 Git repository as well. You have to understand though that the usage of Git 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.
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.
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.
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.
- 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
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
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:
- 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"
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.
- PHP running on your webserver needs zip support - not all webservers have zip support enabled.
- the script needs write permissions within the plugins folder.
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).
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.
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.
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.