People interested in using plugins but who do not need to modify them or write their own should read the main documentation instead - the plugins section describes everything you need to know.

My First Plugin

The first thing you need to do is come up with a short name for your plugin. This short name must be unique enough so that it is different from other plugins currently available and be specific enough that it describes what your plugin does, compared to any plugins that are yet to be written. For example, do not name your plugin "thumbnail" because that's way too general. You need to come up with the name now because you need to use this name to create a folder to hold your plugin's files. Since this short name is to be used as your folder name (and later for a prefix for your plugin's functions), use a valid folder name: no spaces, start with a letter, and use only alphanumeric characters and underscores (to separate words). So take a moment and come up with a short name for your plugin. The full name of your plugin can be decided later.

Each and every Coppermine plugin requires its own folder and a minimum of two files. The folder must be located under the Coppermine plugins folder. So if your Coppermine is located in a folder named "cpg" on your domain, and the short name you chose for your plugin is "yellow_banana", the plugin folder would be: http://www.yourdomain.org/cpg/plugins/yellow_banana/ - put all plugin files in this folder. The two files every plugin requires are:

• codebase.php - holds the basic code to install, configure, uninstall, clean-up, and hook into the Coppermine system, along with any other custom functions you create; you may also use a separate file for functions that are not one of the basic plugin operations but this will be described later
• configuration.php - holds the name, description, author (your name), and version for your plugin; even though the name is 'configuration', the intent of this file is to hold only the very basic configuration information for your plugin - this information shows up on the plugin manager page so people can see quickly your plugin's basic information; all operational configuration forms and parameters should go in codebase.php

The 'sample' plugin that ships with Coppermine shows most of the features that will be described in this tutorial, but please do not copy the 'sample' plugin for this tutorial. Please start from scratch so you know precisely how a plugin is written and developed. You can download all the tutorial plugins using the links in each section. If you do so, each section's plugin will install in a different folder with a name related to the relevant section. Make sure you are using the correct plugin for the section you are reading. For the first tutorial plugin below, it is strongly recommended that you do things manually so you understand the basics. For the subsequent sections, you can then use the downloaded plugins knowing that you can create a plugin from scratch successfully. Keeping this in mind, click here to download the plugin for this section. Once again, it is recommended you only use these files if you have problems. Create the folder and files from scratch so you understand how to do so.

Let's get started!

Create a folder named "hello_world" in the Coppermine plugins folder as shown:

http://www.yourdomain.org/cpg/plugins/hello_world/

Make sure you enable read and execute permissions on this folder (see the permissions section in the main manual). You can create the folder and files on your personal computer and upload them using FTP to your web server, but keep in mind that you cannot try out your plugin until it is on the web server. For each step in this tutorial where you add new lines, edit the text file on your computer, save it, then upload the new version onto web server, making sure to overwrite the previous file on the web server. (Some FTP programs "append" by default - which won't work with these text files, so make sure you are definitely overwriting the file with the new version.)

Create this file in the "hello_world" folder, with contents as shown (and read & execute permissions):

configuration.php

<?php
/**************************************************
  Coppermine Plugin - Hello, World
  *************************************************
  Copyright (c) 2010 <-InsertNameHere->
  *************************************************
  This program is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License version 3
  as published by the Free Software Foundation.
***************************************************/

$name='Hello, World';
$description='Plugin API Tutorial - My First Plugin';
$author='Tutorial';
$version='2.1';
$plugin_cpg_version = array('min' => '1.5');
?>

The beginning part is a comment block of course. We suggest you use such a block at the beginning of each of your plugin files. The first text line tells people this is a Coppermine Plugin and lists the name of your plugin. The next text line has a copyright message with your name (real name or username used on the Coppermine forum). The next text block gives the GPL message that Coppermine uses and is recommended for your code as well. This comment block is not strictly required for your plugin to work. That being said, it is important for organization and clarity, so please make sure to add it to each of your plugin files.

The parameters used by the Plugin API are the 4 variables shown. These variables are shown on the plugin manager page to describe your plugin.

• $name gives the name of your plugin which will be shown on the plugin manager page. You can use any string here; you are not limited to the short name rules you picked earlier.
• $description gives a phrase or sentence or paragraph that describes your plugin. This will be shown on the plugin manager page underneath the plugin's name. You can use any text here; it's recommended to keep the description succinct so it's clear what your plugin does without using too many words.
• $author gives the author or authors of your plugin (if you collaborated with others on the creation or modification of the plugin). Use whatever credits you want to give here. This is also shown on the plugin manager page.
• $version gives the version number (or letter) of your plugin. You can use whatever version numbering you want. Most people use 1.0 for the first release of a plugin that works (sub-1.0 could be used for trial releases if you are not sure it will work in all cases). Then you can use tenths or hundredths for follow-up minor revisions, e.g. 1.01, 1.02, etc. or 1.1, 1.2, etc. Feel free to put the tag "beta" in the version variable if desired, however with the fact that most plugins are fairly simple, it's probably not necessary to do so. If you find a bug in a version, fix it, and release another revision. In any case, you can put whatever text you like to describe your plugin's current version.
• $plugin_cpg_version defines an array that allows you to specify the minimum and maximum Coppermine version for your plugin. It has been added in cpg1.5.x to make sure that users don't accidentally install plugins that haven't been designed for their version of Coppermine.
  Currently, two array keys are being processed: 'min' and 'max'. Against both, a version comparison will be performed using the function version_compare.
  Specifying $plugin_cpg_version = array('min' => '1.5'); will apply for all Coppermine versions, including both cpg1.5.0 as well as cpg1.5.23, but will fail for cpg1.4.27. Specifying $plugin_cpg_version = array('min' => '1.5.3'); will apply for all Coppermine versions equal or better than cpg1.5.3, so it will not apply for cpg1.5.0, but it will apply for cpg1.5.23. Only specify a minor version if a particular plugin hook was introduced in the Coppermine version you refer to.

Now create your code file in the "hello_world" folder, with contents as shown (and read & execute permissions):

codebase.php

<?php
/**************************************************
  Coppermine Plugin - Hello, World
  *************************************************
  Copyright (c) 2010 <-InsertNameHere->
  *************************************************
  This program is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License version 3
  as published by the Free Software Foundation.
***************************************************/

if (!defined('IN_COPPERMINE')) die('Not in Coppermine...');


// Add a filter for the gallery header
$thisplugin->add_filter('gallery_header','helloworld_header');

// Sample function to modify gallery header html
function helloworld_header($html) {
    $html = '<p style="color:red"><b>Hello, world.</b> (tutorial 2.1)</p>'
            .$html;
    return $html;
}

?>

These 2 files are all you need to install and run your first plugin. Before explaining the code for this plugin, go ahead and install this plugin. The plugin manager will show "Hello, World" as one of the "Plugins Not Installed". Click on the install button to install this plugin. It will immediately show up on the "Installed Plugins" section since there is no configuration for it. You should see bold red text declaring "Hello, world." near the top of the page. For detailed instructions on how to use plugins as an end-user, read the plugins section of the main documentation. If you haven't read this section completely, please do so now.

So how does this plugin work? The first block in codebase.php is the same comment block we used in configuration.php. For the same reasons as noted above, it is recommended that you use this comment block in each and every one of your plugin files.

Moving on, the first line of code is the following:

if (!defined('IN_COPPERMINE')) die('Not in Coppermine...');

The constant 'IN_COPPERMINE' is defined in each of the public scripts that users use directly, i.e. ones that show up in the URL of a webpage. All secondary scripts check for this constant before doing anything else. If it has not been set, then the script stops and exits with a "Not in Coppermine..." message. With this technique, all secondary files are inaccessible to users and cannot be run directly. Besides security, a larger reason is that these scripts are not meant to be run directly; they assume they are being called by another script - a script which ensures that all the standard Coppermine definitions and declarations have been made. Your plugin script is such a secondary script and is not meant to be run directly, hence the check for 'IN_COPPERMINE' and the quick exit if it doesn't exist. You can see this in action by typing the following URL into your web browser: http://www.yourdomain.org/cpg/plugins/hello_world/codebase.php (assuming Coppermine is located in the 'cpg' folder under your domain).

The next line of code (after the comment describing it) tells Coppermine which hook your plugin wants to access:

// Add a filter for the gallery header
$thisplugin->add_filter('gallery_header','hello_world_header');

With this line of code, you are registering your plugin to use this plugin hook. In this case, we're hooking onto the gallery_header hook which is located in functions.inc.php in the load_template() function. This function parses your theme's template.html file, replacing tags like {ADMIN_MENU} and {LANGUAGE_SELECT_LIST} with the corresponding Coppermine HTML to render these content blocks. The two plugin hooks gallery_header and gallery_footer allow HTML to be placed before and after the {GALLERY} tag, respectively. (See the reference section below on these hooks for more detailed information.) On the main page, {GALLERY} is replaced with the "content of the main page" config setting, which usually includes the breadcrumb, category list, album list, and random/lastup blocks. On a page like the plugin manager (where you first see "Hello, world." after installing the plugin), {GALLERY} is replaced with the main part of the page, in this case, the plugin manager tables listing the plugins. The "Hello, World" plugin places the text "Hello, world." just above {GALLERY} in both places. If you modify the line of code above to use gallery_footer instead, you'll see "Hello, world." just below the main part of the page, as expected.

Let's break apart this line of code to understand how you register your plugin to use a particular plugin hook. For those programmers who have used classes before (in PHP or another language with similar constructs), you'll recognize the arrow operator -> as a class operator used to access class properties and methods. In this case, the Coppermine Plugin API provides $thisplugin as a pointer to the instance of your plugin's class. So when your plugin's codebase.php is loaded by the plugin API, you can access the properties and methods of your plugin's class by using $thisplugin. For example, $thisplugin->name refers to your plugin's name (whose value is defined in your plugin's configuration.php). See the section below on plugin class properties & methods for more detailed information.

In this case, we are using the add_filter() function to add the filter hook we want to use to our plugin's list of registered plugin hooks. The user-defined function we will use for each call of the hook is hello_world_header, which is defined in the last section of code in our plugin, as shown:

// Function to modify the gallery header
function hello_world_header($html) {
    $html = '<p style="color:red"><b>Hello, world.</b>  (tutorial 2.1)</p>'
            .$html;
    return $html;
}

Our function needs one parameter since it is attached to a filter hook (instead of an action hook), and here we name it $html. In this function, we add on the "Hello, world." text, which is tagged to be bold & red for extra effect. We need to ensure that the parameter is added-on to, not replaced, so that it plays well with other plugins who tag on to the same hook. We place the parameter coming in on a separate line to ensure we don't forget to do this. Finally, the function returns the modified parameter. And that does it.

So now you should know how a plugin, albeit a very basic plugin, works. The other sections in this tutorial describe useful features to add to your plugin including installation, configuration, linking in Coppermine, multi-language support, and distributing your plugin as a package. Read on and follow along.

Back to top

Installation, Configuration, and Clean-Up

The tutorial plugin so far merely outputs text via a particular hook. During the installation of the plugin, nothing special is done besides registering the plugin with Coppermine. The only configuration parameters are the identification ones in configuration.php. It's fairly easy to imagine additional installation steps and configuration parameters that would be useful in a real-world plugin. This section teaches you how to add such installation and configuration features to the tutorial plugin.

Back to top

<form action="{$CPG_PHP_SELF}" method="post">

("Location: pluginmgr.php\n\n");  // go back to plugin manager without installing the plugin
exit(0);

$thisplugin->add_action('plugin_cleanup','coffee_maker_plugin_cleanup_function');

$thisplugin->add_action('plugin_uninstall','coffee_maker_uninstall');

Back to top

Linking to Custom Plugin Scripts

You can refer to any php-driven file within your plugin folder using the file URL parameter. The only pre-requisite is that the file you refer to needs to comply to the naming conventions for files within plugins.

With this being said, it's obvious that you don't have to move files into the coppermine root folder - you can refer to files that reside in your plugin's sub-folder as if it resided in coppermine's root folder that way.

You (as a coppermine plugin author) mustn't create plugins that require end users to move files around before they can start using your plugin. It's simply not necessary to create plugins that way, as you can savely do as if files resides in coppermine's root folder by using the technique used in this section.

Back to top

Adding a Button to Coppermine

There are two places where you might want to add a menu item to: to the admin menu (usually to offer a link to a plugin's config screen) or to the "regular" coppermine menu.

$thisplugin->add_filter('admin_menu','coffee_maker_config_button');

function coffee_maker_bar_config_button($admin_menu){
    global $lang_plugin_coffee_maker, $CONFIG, $coffee_maker_icon_array;
    if ($CONFIG['plugin_coffee_maker_config_link'] == 1) {
	    $new_button = '<div class="admin_menu admin_float"><a href="index.php?file=coffee_maker/index&action=configure"';
	    $new_button .= ' title="' . $lang_plugin_coffee_maker['config'] . '">';
	    $new_button .= $coffee_maker_icon_array['config_menu'] . $lang_plugin_coffee_maker['config'] . '</a></div>';
	    $look_for = '<!-- END export -->'; // This is where you determine the place in the admin menu
	    $admin_menu = str_replace($look_for, $look_for . $new_button, $admin_menu);
    }
    return $admin_menu;
}

$thisplugin->add_filter('sys_menu','coffee_maker_sys_button');

function coffee_maker_bar_sys_button($menu) {
    global $lang_plugin_coffee_maker, $template_sys_menu_spacer, $CONFIG;
    if ($CONFIG['plugin_coffee_maker_how'] == 4) {
		coffee_maker_bar_language(); // Call the function that populates the language variable
        $new_button = array();
        $new_button[0][0] = $lang_plugin_coffee_maker['picinfo_heading'];
        $new_button[0][1] = $lang_plugin_coffee_maker['menu'];
        $new_button[0][2] = 'index.php?file=coffee_maker/index';
        $new_button[0][3] = 'coffee_maker';
        $new_button[0][4] = $template_sys_menu_spacer;
        $new_button[0][5] = 'rel="nofollow"';
        array_splice($menu, count($menu)-1, 0, $new_button);
    }
    return $menu;
}

Back to top

Adding JavaScript to plugins

How to add JavaScript to plugins is being described in the section "How to include JavaScript files in plugins".

Back to top

Multi-language Support

You can make your plugins capable to be used in multiple languages. Therefore, your mustn't hard-code language strings into your plugin, but use variables instead. As you wouldn't want to introduce a load of individual language variables, you better use an array, preferably following the naming scheme $lang_plugin_foldername. All that is left to do is adding a little switch into your plugin that determines the end user's language and make it use the language file if present.

Let's assume that the folder your plugin resides in is named coffee_maker and the name is "Coffee Maker".

It's advisable to move the definition of languages and other resources that you want to use globaly into a separate file. This way, you can call the function directly if needed (outside the scope of the plugin).

require_once "./plugins/coffee_maker/initialize.inc.php";

Of course you need to create the file you just refered to.

<?php
function coffee_maker_language() {
	global $CONFIG, $lang_plugin_coffee_maker;
	require "./plugins/coffee_maker/lang/english.php";
	if ($CONFIG['lang'] != 'english' && file_exists("./plugins/coffee_maker/lang/{$CONFIG['lang']}.php")) {
	    require "./plugins/coffee_maker/lang/{$CONFIG['lang']}.php";
	}
}
?>

As you can see from the code above, inside your plugin's folder, there should be another folder named lang that contains the language files. It needs to contains english.php at least.

<?php
$lang_plugin_coffee_maker['plugin_name'] = 'Coffee Maker';
$lang_plugin_coffee_maker['plugin_description'] = 'This plugin will turn your gallery into a full-featured coffee machine.';
$lang_plugin_coffee_maker['coffee_bean'] = 'coffee bean';
$lang_plugin_coffee_maker['brew'] = 'brew';
?>

Within codebase.php or any other plugin file, you can then use the language strings instead of hard-coding them in. Don't forget to make them global inside functions (see PHP: variable scope).

Back to top

Adding a config section to your plugin

It's advisable to have a config screen available for your plugin - nearly all plugins sooner or later need one.

if (!GALLERY_ADMIN_MODE) {
    cpg_die(ERROR, $lang_errors['access_denied'], __FILE__, __LINE__);
}

require_once "./plugins/coffee_maker/initialize.inc.php";

if (!GALLERY_ADMIN_MODE) {
    cpg_die(ERROR, $lang_errors['access_denied'], __FILE__, __LINE__);
}
require_once "./plugins/coffee_maker/initialize.inc.php";

$plugin_coffee_maker_icon['submit'] = cpg_fetch_icon('ok', 1);

$sanitization_array = array(
    'plugin_coffee_maker_width' => array('type' => 'int', 'min' => '10', 'max' => '32'),
    'plugin_coffee_maker_height' => array('type' => 'int', 'min' => '0', 'max' => '100'),
    'plugin_coffee_maker_enabled' => array('type' => 'checkbox', 'min' => '0', 'max' => '1'),
);

if ($CONFIG['plugin_coffee_maker_enabled'] == '1') {
	$option_output['plugin_coffee_maker_enabled'] = 'checked="checked"';
} else { 
	$option_output['plugin_coffee_maker_enabled'] = '';
}

pageheader($lang_plugin_enlargeit['display_name']);
list($timestamp, $form_token) = getFormToken();
echo <<< EOT

EOT;
starttable('100%', $lang_plugin_coffee_maker['configuration'], 2, 'cpg_zebra');

echo <<< EOT
	<tr>
		<td valign="top">
			<label for="plugin_coffee_maker_enabled" class="clickable_option">{$lang_plugin_coffee_maker['enable_brewing_of_coffee']}</label>
		</td>
		<td valign="top">
			<input type="checkbox" name="plugin_coffee_maker_enabled" id="plugin_coffee_maker_enabled" class="checkbox" value="1" {$option_output['plugin_coffee_maker_enabled']} />
			({$lang_common['yes']})
		</td>
	</tr>
[... more table rows here ... ]
EOT;

echo <<< EOT
	<tr>
		<td class="tablef" colspan="2">
			<input type="hidden" name="form_token" value="{$form_token}" />
			<input type="hidden" name="timestamp" value="{$timestamp}" />
			<button type="submit" class="button" name="submit" value="{$lang_plugin_coffee_maker['submit']}">{$coffee_maker_icon_array['ok']}{$lang_plugin_coffee_maker['submit']}</button>
		</td>
	</tr>
EOT;
endtable();
echo <<< EOT
</form>
EOT;
pagefooter();

Back to top