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

Table of Contents

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
addpic.php upload_file_name Filter filters the file name before it will be processed by the replace_forbidden function during batch-add
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.
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.
contact.php captcha_contact_validate Action action when CAPTCHA is enabled and allows you to override the standard CAPTCHA validation for the contact form.
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.
db_input.php comment_update Action Plugin action to be called when comment is updated
db_input.php captcha_comment_validate Action Plugin action to be called if CAPTCHA is enabled - allows you to override the standard CAPTCHA validation for comments
db_input.php comment_add Action Plugin action to be called when comment is added
db_input.php upload_file_name Filter filters the file name before it will be processed by the replace_forbidden function during HTTP flash upload
db_input.php upload_html_pre_move Action executed before a file is moved to its final location
delete.php before_delete_file Action Plugin action to be called before deleting a file
delete.php after_delete_file Action Plugin action to be called after a file is deleted
displayimage.php file_info Filter filters file information array
displayimage.php post_breadcrumb Action only on thumbnails.php and displayimage.php
ecard.php captcha_ecard_print Filter filters $captcha_print when CAPTCHA is enabled and allows you to override the standard CAPTCHA for ecards
ecard.php captcha_ecard_validate Action action when CAPTCHA is enabled and allows you to override the standard CAPTCHA validation for ecards
editpics.php before_delete_file Action Plugin action to be called before deleting a file
editpics.php after_delete_file Action Plugin action to be called after a file is deleted
editpics.php after_edit_file Action executed after a file update is committed
edit_one_pic.php after_edit_file Action executed after a file update is committed
index.php anycontent Filter anycontent (anycontent page + plugin accessible content)
index.php user_caption_params Filter
index.php plugin_block Filter filters main page blocks
index.php main_page_layout Filter Modifies page layout elements
pluginmgr.php plugin_configure Action executes when plugin_install returns an integer; returns bool/integer
pluginmgr.php plugin_cleanup Action executes when plugin_uninstall returns an integer; returns bool/integer
profile.php profile_add_data Filter Plugin filter to be called before creating the form
register.php captcha_register_print Filter filters $captcha_print when CAPTCHA is enabled and allows you to override the standard CAPTCHA for registrations
register.php captcha_register_validate Filter filters $error when CAPTCHA is enabled and allows you to override the standard CAPTCHA validation for registrations
register.php register_form_validate Filter filters $error to validate additional submitted registration form data
register.php register_form_create Filter Add more fields to the registration form
register.php register_form_submit Action Perform an action corresponding to the submit registration form data
register.php register_user_activation Action Perform an action when the user account is activated
reviewcom.php comment_approve Action Plugin action to be called when one or more comments are approved
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.
search.php search_form Filter Add or remove content to/from the search form
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.
thumbnails.php post_breadcrumb Action only on thumbnails.php and displayimage.php
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.php upload_form Action used to display alternate upload form - see details and examples below
upload.php upload_process Action used to processs alternate upload form - see details and examples below
upload.php upload_file_name Filter filters the file name before it will be processed by the replace_forbidden function during simple HTTP upload
upload.php upload_swf_pre_move Action executed before a file is moved to its final location
usermgr.php usermgr_header Filter
usermgr.php usermgr_footer Filter
bridge/coppermine.inc.php authorize_user Action If $USERDATA === false, return false. If user is authorized, return $USERDATA ... otherwise, return false.
include/functions.inc.php gallery_header Filter shows just above the gallery, defined by {GALLERY} in template.html
include/functions.inc.php gallery_footer Filter shows just below the gallery, defined by {GALLERY} in template.html
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
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
include/functions.inc.php template_html Filter filters the template html
include/functions.inc.php page_meta Filter filters header meta data for {META}
include/functions.inc.php pic_data_sort_array Filter provides method to modify/add sorting parameters for pic_data lookup
include/functions.inc.php pic_pos_sort_array Filter provides method to modify/add sorting parameters for pic position lookup
include/functions.inc.php thumb_caption Filter executed before the more specific "thumb_caption_*" plugins
include/functions.inc.php thumb_caption_regular Filter executed after the more general "thumb_caption" plugin
include/functions.inc.php thumb_caption_lastcom Filter executed after the more general "thumb_caption" plugin
include/functions.inc.php thumb_caption_lastcomby Filter executed after the more general "thumb_caption" plugin
include/functions.inc.php thumb_caption_lastup Filter executed after the more general "thumb_caption" plugin
include/functions.inc.php thumb_caption_lastupby Filter executed after the more general "thumb_caption" plugin
include/functions.inc.php thumb_caption_topn Filter executed after the more general "thumb_caption" plugin
include/functions.inc.php thumb_caption_toprated Filter executed after the more general "thumb_caption" plugin
include/functions.inc.php thumb_caption_lasthits Filter executed after the more general "thumb_caption" plugin
include/functions.inc.php thumb_caption_random Filter executed after the more general "thumb_caption" plugin
include/functions.inc.php thumb_caption_search Filter executed after the more general "thumb_caption" plugin
include/functions.inc.php thumb_caption_lastalb Filter executed after the more general "thumb_caption" plugin
include/functions.inc.php thumb_caption_favpics Filter executed after the more general "thumb_caption" plugin
include/functions.inc.php thumb_html_title Filter allows to modify the thumb html title using data from $row
include/functions.inc.php thumb_strip_html_title Filter allows to modify the thumb html title using data from $row for filmstrip thumbs
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.
include/functions.inc.php meta_album_get_pic_pos Filter determines the position of a file within a meta album.
include/functions.inc.php replace_forbidden_conditions Filter allows to modify the conditions if special chars in file names are replaced by transliteration and/or in general
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
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)
include/init.inc.php page_start Action add/modify/delete init settings before they get to the page
include/mailer.inc.php cpg_mail_to_email Filter modify recipients' addresses when sending e-mails
include/mailer.inc.php cpg_mail_sender_email Filter modify sender's addresses when sending e-mails
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
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.
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.
include/plugin_api.inc.php page_html Filter filters the final output html
from include/init.inc.php
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.
include/plugin_api.inc.php plugin_install Filter executes when the plugin is installed returns true/false/integer
include/plugin_api.inc.php plugin_wakeup Filter when initialized
include/plugin_api.inc.php plugin_sleep Filter when shutdown
include/smilies.inc.php smilies_display
smilies_process		 Filter filters $smilies_display & $smilies_process, can be used to add/remove smilies.
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).
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
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.
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.
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.
include/themes.inc.php
themes/xxx/theme.php		 html_image Filter filters $pic_html when the html to display an image is created.
include/themes.inc.php
themes/xxx/theme.php		 html_document Filter filters $pic_html when the html to display a document is created.
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.
include/themes.inc.php
themes/xxx/theme.php		 fullsize_html Filter filters $fullsize_html when viewing fullsize pictures.
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.
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)
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)
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)
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
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.
include/init.inc.php theme_name Filter filters $CONFIG['theme'] which allows you dynamically set the theme to be used.
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 helpful top start a <form>-tag.
include/themes.inc.php
themes/xxx/theme.php		 theme_thumbnails_header Filter Allows plugin authors to output content before the first row of thumbnails, after the opening table tag. Can be used to add a header row to the table.
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 to the table.
include/themes.inc.php
themes/xxx/theme.php		 theme_thumbnails_wrapper_end Action Output content after the closing tag of the thumbnail table
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.
include/themes.inc.php
themes/xxx/theme.php		 theme_album_params Filter filters the $params array which allows you to modify album cells in the index.php pages.
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.
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.
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.

Back to top

Plugin Hooks Alphabetically

A
B
C
F
G
H
I
J
M
P
R
S
T
U

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);
$header = CPGPluginAPI::filter('theme_thumbnails_header', $header);
$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.