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