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

No translation available

# Plugin Hooks

This is just a list of the different existing plugin hooks supported in version 1.5.x of Coppermine. The following list is designed to aid in the creation of plugins by listing the hooks based on their different uses and properties. This list does not explain how to use each hook but simply lists them so that they can be identified, further researched, and implemented.

## Target audience

This part of the documentation is not meant for end users of Coppermine, but only for developers and skilled users who are familar with coding. There is no support for this section, it comes as-is.

## Choosing Plugin Hooks

In order for your plugin to do anything in Coppermine, you need to register your plugin with the Coppermine plugin API and in so doing, tell Coppermine which hooks you will use to add or modify features of Coppermine. A plugin hook is a place in a Coppermine script where Coppermine pauses what it is doing and checks to see if any plugins need to be called before Coppermine can continue. Some hooks are unique and only occur one place in the Coppermine core code. Others occur in multiple places. Once a hook is reached, Coppermine checks to see if a plugin has registered to use that hook. If so, Coppermine calls the plugin, lets the plugin execute its code and return, then Coppermine will continue where it left off. Some plugin hooks pass data along to the plugin; others do not.

So, in designing your plugin, you need to determine which plugin hook or hooks to use. If you plugin adds text or images to a certain page (like displayimage.php), then look for the plugin hooks on that page (using the table below or by searching the script). Decide which hook occurs at the place you want in Coppermine's order of execution and which hook provides the information you need. In many cases, it's more important to choose the place in the code, and if the hook doesn't provide the data you need, you can pull in that data from Coppermine global variables, configuration settings, or from the database tables themselves. In some cases, you may need to add your own database tables to store information that Coppermine does not keep or that only your plugin needs. There are examples of many of these cases in the core plugins and in the contributed plugins.

Included as a Coppermine core plugin is the plugin 'visiblehookpoints'. This plugin places markers on pages and is a useful tool for determining where plugin hooks are called with respect to the HTML displayed by Coppermine. Read the documentation for this plugin for more information.

Back to top

## Finding Plugin Hooks

There are sections below that list the plugin hooks by script and alphabetically. All plugin hooks should be listed in those 2 sections. However, you can also search for hooks by searching for the text 'CPGPluginAPI' (in all scripts). Action hook calls start with 'CPGPluginAPI::action' and filter hook calls start with 'CPGPluginAPI::filter'. If you are looking for a particular page or place on a page to add text or images, you can look in the script and see where the closest plugin hook is located. In some cases, you may find there is not a convenient hook available. In that case, you can use the 'page_html' filter hook which is called just before the page is output to the web browser. This is not ideal in some cases because the output HTML may change depending upon the theme or other plugin calls (before or after your plugin is called). In some cases, it may be better to replace a Coppermine page entirely by using this call, either to deny access to a particular page (based upon permissions your plugin sets up) or using a new page your plugin provides. Usually this is best for administration or configuration pages since pages your users see will use a particular theme and it can be tedious to write whole pages that are theme-compatible. For user pages, you should try to use a specific plugin hook besides 'page_html'.

See also the core plugin 'visiblehookpoints' for assistance in associating plugin hooks with Coppermine's output to the web browser.

Back to top

## Plugin Hooks by File Name

In this section you will find a list of plugin hooks, sorted by script filenames in which the hook is called.

File | Hook name | Hook type | Explanation | Code
--- | --- | --- | --- | ---
banning.php | ip_information | Filter | Filters additional information to an IP address (empty out of the box). Use this hook to add information after the output of an IP address. | list($row['ip_detail']) = CPGPluginAPI::filter('ip_information', array('', $row['ip_addr']));
contact.php | captcha_contact_print | Filter | filters $captcha_print when CAPTCHA is enabled and allows you to override the standard CAPTCHA for the contact form. | $captcha_print = CPGPluginAPI::filter('captcha_contact_print',$captcha_print);
contact.php | captcha_contact_validate | Action | action when CAPTCHA is enabled and allows you to override the standard CAPTCHA validation for the contact form. | CPGPluginAPI::action('captcha_contact_validate', null);
db_ecard.php | ip_information | Filter | Filters additional information to an IP address (empty out of the box). Use this hook to add information after the output of an IP address. | list($line['ip_detail']) = CPGPluginAPI::filter('ip_information', array('', $line['sender_ip']));
db_input.php | captcha_comment_validate | Action | action when CAPTCHA is enabled and allows you to override the standard CAPTCHA validation for comments | CPGPluginAPI::action('captcha_comment_validate', null);
db_input.php | upload_html_pre_move | Action | executed before a file is moved to its final location | CPGPluginAPI::action('upload_html_pre_move', $superCage->files->getRaw("/userpicture/tmp_name"));
delete.php | before_delete_file | Action | Plugin action to be called before deleting a file | CPGPluginAPI::action('before_delete_file', $pic);
delete.php | after_delete_file | Action | Plugin action to be called after a file is deleted | CPGPluginAPI::action('after_delete_file', $pic);
displayimage.php | file_info | Filter | filters file information array | $info = CPGPluginAPI::filter('file_info',$info);
displayimage.php | post_breadcrumb | Action | only on thumbnails.php and displayimage.php | CPGPluginAPI::action('post_breadcrumb',null);
editpics.php | before_delete_file | Action | Plugin action to be called before deleting a file | CPGPluginAPI::action('before_delete_file', $pic);
editpics.php | after_delete_file | Action | Plugin action to be called after a file is deleted | CPGPluginAPI::action('after_delete_file', $pic);
editpics.php | after_edit_file | Action | executed after a file update is committed | CPGPluginAPI::action('after_edit_file', $pid);
edit_one_pic.php | after_edit_file | Action | executed after a file update is committed | CPGPluginAPI::action('after_edit_file', $pid);
index.php | anycontent | Filter | anycontent (anycontent page + plugin accessible content) | $anycontent = CPGPluginAPI::filter('anycontent',ob_get_contents());
index.php | user_caption_params | Filter |  | $params = CPGPluginAPI::filter('user_caption_params', array('{USER_NAME}' => $user['user_name'], '{USER_ID}' => $user['user_id'], '{ALBUMS}' => $albums_txt, '{PICTURES}' => $pictures_txt, ) );
index.php | plugin_block | Filter | filters main page blocks | $matches = CPGPluginAPI::filter('plugin_block', $matches);
index.php | main_page_layout | Filter | Modifies page layout elements | $elements = CPGPluginAPI::filter('main_page_layout', $elements);
pluginmgr.php | plugin_configure | Action | executes when plugin_install returns an integer; returns bool/integer | CPGPluginAPI::action('plugin_configure',$installed,CPG_EXEC_NEW);
pluginmgr.php | plugin_cleanup | Action | executes when plugin_uninstall returns an integer; returns bool/integer | CPGPluginAPI::action('plugin_cleanup',$uninstalled,$plugin_id);
profile.php | profile_add_data | Filter | Plugin filter to be called before creating the form | CPGPluginAPI::filter('profile_add_data', array ( 0 => $display_profile_form_param, 1 => $form_data ));
register.php | captcha_register_print | Filter | filters $captcha_print when CAPTCHA is enabled and allows you to override the standard CAPTCHA for registrations | $captcha_print = CPGPluginAPI::filter('captcha_register_print',$captcha_print);
register.php | captcha_register_validate | Filter | filters $error when CAPTCHA is enabled and allows you to override the standard CAPTCHA validation for registrations | $error = CPGPluginAPI::filter('captcha_register_validate', $error);
register.php | register_form_create | Filter | Add more fields to the registration form | $form_data = CPGPluginAPI::filter('register_form_create', $form_data);
register.php | register_form_submit | Action | Perform an action corresponding to the submit registration form data | CPGPluginAPI::action('register_form_submit', $user_array);
register.php | register_user_activation | Action | Perform an action when the user account is activated | CPGPluginAPI::action('register_user_activation', $act_key);
reviewcom.php | ip_information | Filter | Filters additional information to an IP address (empty out of the box). Use this hook to add information after the output of an IP address. | list($row['ip_detail']) = CPGPluginAPI::filter('ip_information', array('', $row['msg_raw_ip']));
search.php | search_form | Filter | Add or remove content to/from the search form | $text = CPGPluginAPI::filter('search_form', $text);
stat_details.php | ip_information | Filter | Filters additional information to an IP address (empty out of the box). Use this hook to add information after the output of an IP address. | list($row['ip_detail']) = CPGPluginAPI::filter('ip_information', array('', $row[$value]));
thumbnails.php | post_breadcrumb | Action | only on thumbnails.php and displayimage.php | CPGPluginAPI::action('post_breadcrumb',null);
upload.php | upload_options | Filter | modify or add upload methods which can be selected from the configuration panel or upload form (if allowed) - see details and examples below | $upload_choices = CPGPluginAPI::filter('upload_options',$upload_choices);
upload.php | upload_form | Action | used to display alternate upload form - see details and examples below | CPGPluginAPI::action('upload_form',array($upload_form,$upload_select));
upload.php | upload_process | Action | used to processs alternate upload form - see details and examples below | CPGPluginAPI::action('upload_process',$upload_form);
upload.php | upload_swf_pre_move | Action | executed before a file is moved to its final location | CPGPluginAPI::action('upload_swf_pre_move', $path_to_image);
usermgr.php | usermgr_header | Filter |  | echo CPGPluginAPI::filter('usermgr_header','');
usermgr.php | usermgr_footer | Filter |  | echo CPGPluginAPI::filter('usermgr_footer','');
include/functions.inc.php | gallery_header | Filter | shows just above the gallery, defined by {GALLERY} in template.html | $template_header = CPGPluginAPI::filter('gallery_header', $template_header);
include/functions.inc.php | gallery_footer | Filter | shows just below the gallery, defined by {GALLERY} in template.html | $template_footer = CPGPluginAPI::filter('gallery_footer', $template_footer);
include/functions.inc.php | thumb_data | Filter | filters $pic_row when get_pic_url is called... usually this is called before any html output is created so you can use this to change a lot of data | $pic_row = CPGPluginAPI::filter('thumb_data',$pic_row);
include/functions.inc.php | picture_url | Filter | filters $pic_row when get_pic_url is called... usually this is called before any html output is created so you can use this to change a lot of data | $pic_row = CPGPluginAPI::filter('picture_url', $pic_row);
include/functions.inc.php | template_html | Filter | filters the template html | $template = CPGPluginAPI::filter('template_html',$template);
include/functions.inc.php | page_meta | Filter | filters header meta data for {META} | $template_header = str_replace('{META}', '{META}'.CPGPluginAPI::filter('page_meta',''), $template_header);
include/functions.inc.php | thumb_caption | Filter | executed before the more specific "thumb_caption_*" plugins | $rowset = CPGPluginAPI::filter('thumb_caption',$rowset);
include/functions.inc.php | thumb_caption_regular | Filter | executed after the more general "thumb_caption" plugin | $rowset = CPGPluginAPI::filter('thumb_caption_regular',$rowset);
include/functions.inc.php | thumb_caption_lastcom | Filter | executed after the more general "thumb_caption" plugin | $rowset = CPGPluginAPI::filter('thumb_caption_lastcom',$rowset);
include/functions.inc.php | thumb_caption_lastcomby | Filter | executed after the more general "thumb_caption" plugin | $rowset = CPGPluginAPI::filter('thumb_caption_lastcomby',$rowset);
include/functions.inc.php | thumb_caption_lastup | Filter | executed after the more general "thumb_caption" plugin | $rowset = CPGPluginAPI::filter('thumb_caption_lastup',$rowset);
include/functions.inc.php | thumb_caption_lastupby | Filter | executed after the more general "thumb_caption" plugin | $rowset = CPGPluginAPI::filter('thumb_caption_lastupby',$rowset);
include/functions.inc.php | thumb_caption_topn | Filter | executed after the more general "thumb_caption" plugin | $rowset = CPGPluginAPI::filter('thumb_caption_topn',$rowset);
include/functions.inc.php | thumb_caption_toprated | Filter | executed after the more general "thumb_caption" plugin | $rowset = CPGPluginAPI::filter('thumb_caption_toprated',$rowset);
include/functions.inc.php | thumb_caption_lasthits | Filter | executed after the more general "thumb_caption" plugin | $rowset = CPGPluginAPI::filter('thumb_caption_lasthits',$rowset);
include/functions.inc.php | thumb_caption_random | Filter | executed after the more general "thumb_caption" plugin | $rowset = CPGPluginAPI::filter('thumb_caption_random',$rowset);
include/functions.inc.php | thumb_caption_search | Filter | executed after the more general "thumb_caption" plugin | $rowset = CPGPluginAPI::filter('thumb_caption_search',$rowset);
include/functions.inc.php | thumb_caption_lastalb | Filter | executed after the more general "thumb_caption" plugin | $rowset = CPGPluginAPI::filter('thumb_caption_lastalb',$rowset);
include/functions.inc.php | thumb_caption_favpics | Filter | executed after the more general "thumb_caption" plugin | $rowset = CPGPluginAPI::filter('thumb_caption_favpics',$rowset);
include/functions.inc.php | thumb_html_title | Filter | allows to modify the thumb html title using data from $row | list($pic_title) = CPGPluginAPI::filter('thumb_html_title', array($pic_title, $row));
include/functions.inc.php | thumb_strip_html_title | Filter | allows to modify the thumb html title using data from $row for filmstrip thumbs | list($pic_title) = CPGPluginAPI::filter('thumb_strip_html_title', array($pic_title, $row));
include/functions.inc.php | meta_album | Filter | executed before meta albums are retrieved, giving the possibility to add or filter meta albums. See below for more info. | $meta_album_params = CPGPluginAPI::filter('meta_album', $meta_album_passto);
include/functions.inc.php | meta_album_get_pic_pos | Filter | determines the position of the a file within a meta album. | $pos = CPGPluginAPI::filter('meta_album_get_pic_pos', $album);
include/functions.inc.php | replace_forbidden_conditions | Filter | allows to modify the conditions if special chars in file names are replaced by transliteraion and/or in general | $condition = CPGPluginAPI::filter('replace_forbidden_conditions', $condition);
include/functions.inc.php | token_criteria | Filter | allows to modify the token criteria array. You can add new criteria or remove existing criteria if you don't want to use them to create the token | $token_criteria_array = CPGPluginAPI::filter('token_criteria', $token_criteria_array);
include/functions.inc.php | bbcode | Filter | with this hook, you can modify the comment that has been submitted and add your custom bbcodes. (Only available when a '[' has been found in the comment) | $text = CPGPluginAPI::filter('bbcode', $text);
include/init.inc.php | page_start | Action | add/modify/delete init settings before they get to the page | CPGPluginAPI::action('page_start',null);
include/mailer.inc.php | cpg_mail_to_email | Filter | Modify recipients' addresses when sending e-mails | $to = CPGPluginAPI::filter('cpg_mail_to_email', $to);
include/mailer.inc.php | cpg_mail_sender_email | Filter | Modify sender's addresses when sending e-mails | $sender_email = CPGPluginAPI::filter('cpg_mail_sender_email', $sender_email);
include/picmgmt.inc.php | add_file_data | Filter | available in picmgmt.php, called right before a new image's data is written to the database | $CURRENT_PIC_DATA = CPGPluginAPI::filter('add_file_data',$CURRENT_PIC_DATA);
include/picmgmt.inc.php | add_file_data_success | Action | called right after a new file's data is written to the database. $CURRENT_PIC_DATA holds the pid of new file along with other data. | $CURRENT_PIC_DATA = CPGPluginAPI::action('add_file_data_success', $CURRENT_PIC_DATA);
include/picmgmt.inc.php | image_sharpen | Filter | called while uploading pictures. Toggles $sharpen, to e.g. enable image sharpening for intermediate pictures if thumbnail sharpening is enabled in the first place. | list($sharpen) = CPGPluginAPI::filter('image_sharpen', array($sharpen, $new_size));
include/plugin_api.inc.php | page_html | Filter | filters the final output html | function& cpg_filter_page_html( &$html ) { return CPGPluginAPI::filter('page_html',$html); } from include/init.inc.php // Start output buffering ob_start('cpg_filter_page_html');
include/plugin_api.inc.php | page_end | Filter | executes when the script has output the page to the browser. Note: Working directory of the script can change inside the shutdown function under some web servers, e.g. Apache. | register_shutdown_function('cpg_action_page_end');
include/plugin_api.inc.php | plugin_install | Filter | executes when the plugin is installed returns true/false/integer | $installed = CPGPluginAPI::action('plugin_install',true,CPG_EXEC_NEW);
include/plugin_api.inc.php | plugin_wakeup | Filter | when initialized | if (!($thisplugin->awake = CPGPluginAPI::action('plugin_wakeup',true)))
include/plugin_api.inc.php | plugin_sleep | Filter | when shutdown | register_shutdown_function(array('CPGPluginAPI','sleep'));
include/smilies.inc.php | smilies_display smilies_process | Filter | filters $smilies_display & $smilies_process, can be used to add/remove smilies. | $smilies_display = CPGPluginAPI::filter('smilies_display',$smilies_display);<br /> $smilies_process = CPGPluginAPI::filter('smilies_process',$smilies_process);
include/themes.inc.php themes/xxx/theme.php | theme_add_comment theme_edit_comment | Filter | filters $template_add_your_comment & $template_image_comments, can be used to display extra data when comments are displayed (like bbcode buttons). | $template_add_your_comment = CPGPluginAPI::filter('theme_add_comment', $template_add_your_comment);<br /> $template_image_comments = CPGPluginAPI::filter('theme_edit_comment', $template_image_comments);
include/themes.inc.php themes/xxx/theme.php | file_data | Filter | filters $pic_row when get_pic_url is called... usually this is called before any html is created so you can use this to change a lot of data | $CURRENT_PIC_DATA = CPGPluginAPI::filter('file_data',$CURRENT_PIC_DATA);
include/themes.inc.php themes/xxx/theme.php | html_image_reduced_overlay | Filter | filters $pic_html when the html to display a reduced image with transparant overlay is created. | $pic_html = CPGPluginAPI::filter('html_image_reduced_overlay',$pic_html);
include/themes.inc.php themes/xxx/theme.php | html_image_reduced | Filter | filters $pic_html when the html to display a reduced image is created. | $pic_html = CPGPluginAPI::filter('html_image_reduced',$pic_html);
include/themes.inc.php themes/xxx/theme.php | html_image_overlay | Filter | filters $pic_html when the html to display an image with transparant overlay is created. | $pic_html = CPGPluginAPI::filter('html_image_overlay',$pic_html);
include/themes.inc.php themes/xxx/theme.php | html_image | Filter | filters $pic_html when the html to display an image is created. | $pic_html = CPGPluginAPI::filter('html_image',$pic_html);
include/themes.inc.php themes/xxx/theme.php | html_document | Filter | filters $pic_html when the html to display a document is created. | $pic_html = CPGPluginAPI::filter('html_document',$pic_html);
include/themes.inc.php themes/xxx/theme.php | html_other_media | Filter | filters $pic_html when the html to display other media (video, flash, ...) is created. | $pic_html = CPGPluginAPI::filter('html_other_media',$pic_html);
include/themes.inc.php themes/xxx/theme.php | fullsize_html | Filter | filters $fullsize_html when viewing fullsize pictures. | $fullsize_html = CPGPluginAPI::filter('fullsize_html', $fullsize_html);
include/themes.inc.php themes/xxx/theme.php | javascript_includes | Filter | filters $JS['includes'] before the js files will be added to the html output. | $JS['includes'] = CPGPluginAPI::filter('javascript_includes',$JS['includes']);
include/themes.inc.php themes/xxx/theme.php | admin_menu | Filter | filters $admin_menu which allows to add a button to it. (See below how to do that) | $admin_menu = CPGPluginAPI::filter('admin_menu',$html);
include/themes.inc.php themes/xxx/theme.php | sys_menu | Filter | filters $sys_menu_buttons which allows to add a button to it. (See below how to do that) | $sys_menu_buttons = CPGPluginAPI::filter('sys_menu',$sys_menu_buttons);
include/themes.inc.php themes/xxx/theme.php | sub_menu | Filter | filters $sub_menu_buttons which allows to add a button to it. (See below how to do that) | $sub_menu_buttons = CPGPluginAPI::filter('sub_menu',$sub_menu_buttons);
include/themes.inc.php themes/xxx/theme.php | captcha_comment_print | Filter | filters $template_add_your_comment when CAPTCHA is enabled and allows you to override the standard CAPTCHA for comments | $template_add_your_comment = CPGPluginAPI::filter('captcha_comment_print', $template_add_your_comment);
include/themes.inc.php themes/xxx/theme.php | theme_display_thumbnails_params | Filter | filters $template_thumbnail_view which allows you to modify the thumbnail output or add things beneath the thumbails. | $params = CPGPluginAPI::filter('theme_display_thumbnails_params', $params);
include/themes.inc.php themes/xxx/theme.php | theme_thumbnails_wrapper_start | Action | Allows plugin authors to output content before the thumbnail table starts, which is particularly helpfull top start a <form>-tag. | CPGPluginAPI::action('theme_thumbnails_wrapper_start', null);
include/themes.inc.php themes/xxx/theme.php | theme_thumbnails_footer | Filter | Allows plugin authors to output content after the last row of thumbnails, before the closing table tag. Can be used to add a footer row of the table | $footer = CPGPluginAPI::filter('theme_thumbnails_footer', $footer); echo $footer;
include/themes.inc.php themes/xxx/theme.php | theme_thumbnails_wrapper_end | Action | Output content after the closing tag of the thumbnail table | CPGPluginAPI::action('theme_thumbnails_wrapper_end', null);
include/themes.inc.php themes/xxx/theme.php | theme_thumbnails_title | Filter | filters the $param array which allows you to modify the title row of the thumbnails table. | $params = CPGPluginAPI::filter('theme_thumbnails_title', $param);
include/themes.inc.php themes/xxx/theme.php | theme_thumbnails_album_types | Filter | filters the $album_types array which allows you to add new 'album' types. Useful for custom meta albums that don't link to files, but to thumbnail pages. | $album_types = CPGPluginAPI::filter('theme_thumbnails_album_types', $album_types);
include/themes.inc.php themes/xxx/theme.php | theme_pageheader_params | Filter | filters $template_vars for the pageheader function. Allows you to modify the entire pageheader output, e.g. page title, charset definition, meta tags. | $params = CPGPluginAPI::filter('theme_pageheader_params', $template_vars);
include/themes.inc.php themes/xxx/theme.php | ip_information | Filter | Filters additional information to an IP address (empty out of the box). Use this hook to add information after the output of an IP address. | list($row['ip_detail']) = CPGPluginAPI::filter('ip_information', array('', $row['msg_hdr_ip']));

Back to top

## Plugin Hooks Alphabetically

A | add_file_data add_file_data_success admin_menu after_delete_file (delete.php) after_delete_file (editpics.php) after_edit_file (editpics.php) after_edit_file (edit_one_pic.php) anycontent
B | bbcode before_delete_file (delete.php) before_delete_file (editpics.php)
C | captcha_comment_print captcha_comment_validate captcha_contact_print captcha_contact_validate captcha_register_print captcha_register_validate cpg_mail_sender_email cpg_mail_to_email
F | file_data file_info fullsize_html
G | gallery_footer gallery_header
H | html_document html_image html_image_overlay html_image_reduced html_image_reduced_overlay html_other_media
I | image_sharpen ip_information (banning.php) ip_information (db_ecard.php) ip_information (reviewcom.php) ip_information (stat_details.php) ip_information (include/themes.inc.php)
J | javascript_includes
M | main_page_layout meta_album meta_album_get_pic_pos
P | page_end page_html page_meta page_start picture_url plugin_block plugin_cleanup plugin_configure plugin_install plugin_sleep plugin_wakeup post_breadcrumb (displayimage.php) post_breadcrumb (thumbnails.php) profile_add_data
R | register_form_create register_form_submit register_user_activation replace_forbidden_conditions
S | search_form smilies_display smilies_process sub_menu sys_menu
T | template_html theme_add_comment theme_display_thumbnails_params theme_edit_comment theme_pageheader_params theme_thumbnails_album_types theme_thumbnails_footer theme_thumbnails_title theme_thumbnails_wrapper_end theme_thumbnails_wrapper_start thumb_caption thumb_caption_favpics thumb_caption_lastalb thumb_caption_lastcom thumb_caption_lastcomby thumb_caption_lasthits thumb_caption_lastup thumb_caption_lastupby thumb_caption_random thumb_caption_regular thumb_caption_search thumb_caption_topn thumb_caption_toprated thumb_data thumb_html_title thumb_strip_html_title token_criteria
U | upload_form upload_options upload_process user_caption_params usermgr_footer usermgr_header upload_html_pre_move upload_swf_pre_move

Back to top

## Plugin Hooks by Hook Type

There currently are two different types of plugin hooks: actions and filters:

### Action

The first type of hook is an action hook. Basically this allows for actions related to the plugin such as the following two hooks.

    CPGPluginAPI::action('plugin_configure',$installed,CPG_EXEC_NEW);
    CPGPluginAPI::action('plugin_cleanup',$uninstalled,$plugin_id);

These next two hooks are useful for running code that does not require anything to be exported. These hooks have access to the global variables and functions inside of Coppermine. These hooks will most likely be used to execute code that does not require an output.

    CPGPluginAPI::action('page_start',null);
    CPGPluginAPI::action('page_end',null);

These two hooks provide the ability to add a custom CAPTCHA validation. The third validation function is a filter, so don't forget to provide that one as well.

    CPGPluginAPI::action('captcha_comment_validate', null);
    CPGPluginAPI::action('captcha_contact_validate', null);

These two hooks allow plugin authors to output content before the thumbnail table starts and right after the closing tag of the thumbnail table.

    CPGPluginAPI::action('theme_thumbnails_wrapper_start', null);
    CPGPluginAPI::action('theme_thumbnails_wrapper_end', null);

### Filter

This group of plugin hooks is designed to manipulate data that will be used. Normally this involves adding or removing data from the variable submitted to the filter. This data can also be simply read from the variable.

This first group of filters are used in a variety of places and are each unique.

    $info = CPGPluginAPI::filter('file_info',$info);
    $params = CPGPluginAPI::filter('user_caption_params', array('{USER_NAME}' => $user['user_name'],
    $matches = CPGPluginAPI::filter('plugin_block', $matches);
    $anycontent = CPGPluginAPI::filter('anycontent',ob_get_contents());
    $template = CPGPluginAPI::filter('template_html',$template);
    $template_header = str_replace('{META}','{META}'.CPGPluginAPI::filter('page_meta',''),$template_header);

This group of filters is very specific for manipulating the data of the thumbnails. These are named according to what they modify and are extremely obvious.

$rowset = CPGPluginAPI::filter('thumb_caption',$rowset);
$rowset = CPGPluginAPI::filter('thumb_caption_regular',$rowset);
$rowset = CPGPluginAPI::filter('thumb_caption_lastcom',$rowset);
$rowset = CPGPluginAPI::filter('thumb_caption_lastcomby',$rowset);
$rowset = CPGPluginAPI::filter('thumb_caption_lastup',$rowset);
$rowset = CPGPluginAPI::filter('thumb_caption_lastupby',$rowset);
$rowset = CPGPluginAPI::filter('thumb_caption_topn',$rowset);
$rowset = CPGPluginAPI::filter('thumb_caption_toprated',$rowset);
$rowset = CPGPluginAPI::filter('thumb_caption_lasthits',$rowset);
$rowset = CPGPluginAPI::filter('thumb_caption_random',$rowset);
$rowset = CPGPluginAPI::filter('thumb_caption_search',$rowset);
$rowset = CPGPluginAPI::filter('thumb_caption_lastalb',$rowset);
$rowset = CPGPluginAPI::filter('thumb_caption_favpics',$rowset);
list($pic_title) = CPGPluginAPI::filter('thumb_html_title', array($pic_title, $row));
list($pic_title) = CPGPluginAPI::filter('thumb_strip_html_title', array($pic_title, $row));
$pic_row = CPGPluginAPI::filter('thumb_data',$pic_row);
$params = CPGPluginAPI::filter('theme_display_thumbnails_params', $params);
$footer = CPGPluginAPI::filter('theme_thumbnails_footer', $footer);
$params = CPGPluginAPI::filter('theme_thumbnails_title', $param);

These two filters are used specifically to manipulate the data of a picture.

$CURRENT_PIC_DATA = CPGPluginAPI::filter('add_file_data',$CURRENT_PIC_DATA);
$CURRENT_PIC_DATA = CPGPluginAPI::filter('file_data',$CURRENT_PIC_DATA);

These six filters allow you to modify the output html to display media.

$pic_html = CPGPluginAPI::filter('html_image_reduced_overlay',$pic_html);
$pic_html = CPGPluginAPI::filter('html_image_reduced',$pic_html);
$pic_html = CPGPluginAPI::filter('html_image_overlay',$pic_html);
$pic_html = CPGPluginAPI::filter('html_image',$pic_html);
$pic_html = CPGPluginAPI::filter('html_document',$pic_html);
$pic_html = CPGPluginAPI::filter('html_other_media',$pic_html);

If you want to do something (like converting the video to flv, taking a backup of file to remote server etc..) after a file is uploaded then this hook can be used.

$CURRENT_PIC_DATA = CPGPluginAPI::action('add_file_data_success', $CURRENT_PIC_DATA);

The breadcrumb plugin:

CPGPluginAPI::action('post_breadcrumb',null);

This plugin is very powerful because it gives access to the entire body of HTML that will be then directly returned to the user. This filter can be used to remove parts of code or modify links for example.

return CPGPluginAPI::filter('page_html',$html);

These two filters relate to headers.

echo CPGPluginAPI::filter('usermgr_header','');
$template_header .= CPGPluginAPI::filter('gallery_header','');

These two filters relate to footers.

echo CPGPluginAPI::filter('usermgr_footer','');
$template_footer = CPGPluginAPI::filter('gallery_footer','').substr($template, $gallery_pos);

These two action hooks are meant for cleanup purposes. If there is any additional data related to a file and you want that data to be removed when a file is deleted then use these hooks.

CPGPluginAPI::action('before_delete_file', $pic);
CPGPluginAPI::action('after_delete_file', $pic);

This filter is a special one to add or modify meta albums

$meta_album_params = CPGPluginAPI::filter('meta_album', $meta_album_passto);
It works like this:

    <?php
    $meta_album_passto = array (
            'album' => $album,
            'limit' => $limit,
            'set_caption' => $set_caption,
    );

    $meta_album_params = CPGPluginAPI::filter('meta_album', $meta_album_passto);
    if ($meta_album_params['album_name']) {
            $album_name = $meta_album_params['album_name'];
            $count = $meta_album_params['count'];
            $rowset = $meta_album_params['rowset'];
            return $rowset;
    }

A plugin needs three input variables to do its thing: `$album`, `$limit`, `$set_caption` and it needs to modify three variables: `$album_name`, `$count`, and `$rowset` (and remember that `$rowset` is a multi-dimensional array itself)

These filters allow you to add buttons to the different menus.

$admin_menu = CPGPluginAPI::filter('admin_menu',$html);
$sys_menu_buttons = CPGPluginAPI::filter('sys_menu',$sys_menu_buttons);
$sub_menu_buttons = CPGPluginAPI::filter('sub_menu',$sub_menu_buttons);
To add a button to the admin menu you can do the following:

    <?php
    $thisplugin->add_filter('admin_menu','add_admin_button');

    function add_admin_button($admin_menu){
        $new_button = '<div class="admin_menu admin_float"><a href="./menu_link.php" title="menu link">MENU LINK</a></div>';
        $look_for = '<!-- END export -->';
        $admin_menu = str_replace($look_for, $look_for . $new_button, $admin_menu);

        return $admin_menu;
    }

For the sys & sub menus you have to take another approach:

    <?php
    $thisplugin->add_filter('sub_menu','add_sub_button');

    function add_sub_button($menu) {
        $new_button = array();
        $new_button[0][0] = 'MENU LINK';
        $new_button[0][1] = 'menu link';
        $new_button[0][2] = './menu_link.php';
        $new_button[0][3] = 'class_name';
        $new_button[0][4] = '::';
        $new_button[0][5] = 'rel="nofollow"';

        array_splice($menu, count($menu)-1, 0, $new_button);

        return $menu;
    }

These four hooks can be used to add a custom CAPTCHA validation that overrides the one built into Coppermine.

$template_add_your_comment = CPGPluginAPI::filter('captcha_comment_print', $template_add_your_comment);
$captcha_print = CPGPluginAPI::filter('captcha_register_print',$captcha_print);
$captcha_print = CPGPluginAPI::filter('captcha_contact_print',$captcha_print);
$error = CPGPluginAPI::filter('captcha_register_validate', $error);

This hook can be used to modify the elements of the main page. Use it to allow differences in page layout (from home page) when visitor clicks on "Album list".

$elements = CPGPluginAPI::filter('main_page_layout', $elements);

Use this hook to add information after the output of an IP address (only for the admin).

$row['ip_detail'] = CPGPluginAPI::filter('ip_information', $row['ip_addr']);

Back to top

## Plugin Hook Examples

### Adding an upload method

To add an upload method that administrators and users (if allowed) can use, use these 3 plugin hooks in concert:

    $thisplugin->add_filter('upload_options','myfunction_add_upload_option');
    $thisplugin->add_action('upload_form','myfunction_display_upload_form');
    $thisplugin->add_action('upload_process','myfunction_process_upload_form');

All 3 hooks are called from upload.php. The first 'upload_options' allows you to add your upload method to the dropdown list displayed on the configuration panel and on the upload page (if allowed on the configuration panel). Here are the relevant lines from upload.php:

    // Set up an array of choices for the upload method
    $upload_choices = array(
        'swfupload'   => $lang_upload_php['upload_swf'],
        'html_single' => $lang_upload_php['upload_single'],
    );
    // Filter upload choices to allow plugins to add upload methods
    $upload_choices = CPGPluginAPI::filter('upload_options',$upload_choices);

The key for your upload method must be a simple key (with no spaces or special characters) that can be used as a GET parameter to select your upload form. The value that corresponds to this key is the label shown on the dropdown list. Here's an example of a plugin function that uses this hook to add an upload choice to the dropdown box:

    function myfunction_add_upload_option($upload_choices)
    {
        $more_upload_choices = array('alt_upload' => 'Alternate Upload Mechanism');
        return array_merge($upload_choices, $more_upload_choices);
    }

The next hook is 'upload_form' used to display the upload form for you upload method. It is called whether or not your method is chosen, so you need to check this first, and return if your upload method is not chosen. It is expected that you will display your upload form and then exit. Here are the relevant lines that call this hook:

        // Call active plugins for alternate upload forms
        CPGPluginAPI::action('upload_form',array($upload_form,$upload_select));

An array of 2 elements is passed with the hook call. The first element is $upload_form which is the choice of upload method. The second element is a dropdown list of all the upload methods which you should display with your upload form to be consistent with the default upload forms. In your upload form, you need to include two hidden inputs: 'method' and 'plugin_process'. The input 'method' must match the key provided in the 'upload_options' hook function. The input 'plugin_process' must have a value of '1' to signal upload.php that it must process your upload form. The two required inputs are shown here:

    <input type="hidden" name="method" value="alt_upload" />
    <input type="hidden" name="plugin_process" value="1" />

Here is a complete example of a plugin function that displays an upload form:

    function myfunction_display_upload_form($upload_settings)
    {
        list($upload_form, $upload_select) = $upload_settings;
        if ($upload_form != 'alt_upload') {
            return;
        }
        pageheader('Alternate Upload Form');
        starttable('100%', cpg_fetch_icon('upload',2).'Upload Here'.$upload_select, 2);
        echo <<< EOT
        <tr>
            <td>
                <form name="altuploadform" id="altuploadform" method="post" action="upload.php" enctype="multipart/form-data">
                    <input type="hidden" name="method" value="alt_upload" />
                    <input type="hidden" name="plugin_process" value="1" />
                    <input type="submit" name="submit" value="submit" />
                </form>
            </td>
        </tr>

    EOT;
        endtable();
        pagefooter();
        exit;
    }

The last plugin hook is 'upload_process' and is used to process the upload form. As with 'upload_form', it is called whether or not your upload form is used, so you need to check this first. Here are the relevant lines from the hook call:

        // Call active plugins for alternate upload forms
        CPGPluginAPI::action('upload_process',$upload_form);

As with 'upload_form', $upload_form is the choice of upload method. Check this for your upload method, then respond appropriately. You should also exit once you have processed your upload form. Here is an example plugin function:

    function myfunction_process_upload_form($upload_form)
    {
        if ($upload_form != 'alt_upload') {
            return;
        }
        pageheader('Alternate Upload Form');
        starttable('100%', cpg_fetch_icon('upload',2).'Upload Here', 2);
        echo <<< EOT
        <tr>
            <td>
                Alternate Upload Form Processed.
            </td>
        </tr>

    EOT;
        endtable();
        pagefooter();
        exit;
    }

Back to top

### Add tags for thumbnails display

To add tags that will be processed in $template_thumbnail_view in the function theme_display_thumbnails (in theme.php), use the filter hook 'theme_display_thumbnails_params':

    $params = CPGPluginAPI::filter('theme_display_thumbnails_params', $params);

Here's an example of a plugin function that adds more thumbnail information that can be tagged in $template_thumbnail_view:

    function myfunction_add_params($params)
    {
        global $thumb;
        $more_params = array(
            '{PID}'         => $thumb['pid'],
            '{TITLE}'       => $thumb['title'],
            '{DESCRIPTION}' => $thumb['description'],
            '{PWIDTH}'      => $thumb['pwidth'],
            '{PHEIGHT}'     => $thumb['pheight'],
            '{FILEPATH}'    => $thumb['filepath'],
            '{FILENAME}'    => $thumb['filename'],
            '{FILESIZE}'    => $thumb['filesize'],
        );
        return array_merge($params,$more_params);
    }

To manipulate the title row of the thumbnail table, use

    $param = CPGPluginAPI::filter('theme_thumbnails_title', $param);

This plugin hook has been added in cpg1.5.3 only - plugins that rely on the existence of this hook must set the minimum requirements accordingly.

To add the new tags to $template_thumbnail_view in your plugin, you can override the theme template by using the 'page_start' hook. Some users may have a theme that uses this template and in that case, your plugin documentation should list the new tags your plugin uses so the user can add these tags to their theme template. You would also need to disable your plugin from overriding this template. Ideally, this would be done on your plugin configuration panel.