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

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.

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.

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.	$row['ip_detail'] = CPGPluginAPI::filter('ip_information', $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.	$line['ip_detail'] = CPGPluginAPI::filter('ip_information', $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);
delete.php	before_delete_file	Filter	Plugin filter to be called before deleting a file	CPGPluginAPI::filter('before_delete_file', $pic);
delete.php	after_delete_file	Filter	Plugin filter to be called after a file is deleted	CPGPluginAPI::filter('after_delete_file', $pic);
displayimage.php	file_info	Filter	filters file information array	$info = CPGPluginAPI::filter('file_info',$info);
displayimage.php	post_breadcrumb	Filter	only on thumbnails.php and displayimage.php	CPGPluginAPI::filter('post_breadcrumb',null);
editpics.php	before_delete_file	Filter	Plugin filter to be called before deleting a file	CPGPluginAPI::filter('before_delete_file', $pic);
editpics.php	after_delete_file	Filter	Plugin filter to be called after a file is deleted	CPGPluginAPI::filter('after_delete_file', $pic);
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	Filter	Perform an action corresponding to the submit registration form data	CPGPluginAPI::filter('register_form_submit', $user_array);
register.php	register_user_activation	Filter	Perform an action when the user account is activated	CPGPluginAPI::filter('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.	$ip_address_output = $row['msg_raw_ip'] . CPGPluginAPI::filter('ip_information', $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.	print ' '. $row[$value] . CPGPluginAPI::filter('ip_information', $row[$value]) . $LINEBREAK;
thumbnails.php	post_breadcrumb	Filter	only on thumbnails.php and displayimage.php	CPGPluginAPI::filter('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);
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	$pic_title = CPGPluginAPI::filter('thumb_html_title', array($pic_title, $row)); $pic_title = (is_array($pic_title)) ? $pic_title[0] : $pic_title;
include/functions.inc.php	thumb_strip_html_title	Filter	allows to modify the thumb html title using data from $row for filmstrip thumbs	$pic_title = CPGPluginAPI::filter('thumb_strip_html_title', array($pic_title, $row)); $pic_title = (is_array($pic_title)) ? $pic_title[0] : $pic_title;
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	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	Filter	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::filter('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.	$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.	$ip = $row['msg_hdr_ip'] . CPGPluginAPI::filter('ip_information', $row['msg_hdr_ip']);

Plugin Hooks Alphabetically

A	add_file_data add_file_data_success admin_menu after_delete_file (delete.php) after_delete_file (editpics.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.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
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

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);
$pic_title = CPGPluginAPI::filter('thumb_html_title', $row);
$pic_title = CPGPluginAPI::filter('thumb_strip_html_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_picture_image_reduced_overlay',$pic_html);
$pic_html = CPGPluginAPI::filter('html_picture_image_reduced',$pic_html);
$pic_html = CPGPluginAPI::filter('html_picture_image_overlay',$pic_html);
$pic_html = CPGPluginAPI::filter('html_picture_image',$pic_html);
$pic_html = CPGPluginAPI::filter('html_picture_document',$pic_html);
$pic_html = CPGPluginAPI::filter('html_picture_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::filter('add_file_data_success',$CURRENT_PIC_DATA);

The breadcrumb plugin:

CPGPluginAPI::filter('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 filters 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::filter('before_delete_file', $pic);
CPGPluginAPI::filter('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']);

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;
}

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.

$LastChangedDate: 2010-08-06 11:59:36 +0200 (Fr, 06 Aug 2010) $ $Revision: 7805 $