How to Hook into the Media Upload Popup Interface

What is the media upload popup interface?

That is simply the popup window that appears when we click on the Add Media button (for adding images and video) while in the Edit Post screen.

The same interface is also currently being used for –

• Setting featured images in posts, and
• Setting header images in a theme.

It can also be very useful in a plugin. For example, my Shiba Gallery plugin uses the Media Upload Interface to assign a default picture for posts and pages that do not have a user assigned featured image.

Shiba Gallery Set Default Image Page

Here, we consider how to use the Media Upload Interface in our own plugin or theme.

1. Add Thickbox

The first step is to enable pop-up capability for the relevant plugin page(s). For example, my Shiba Gallery Plugin uses the interface in the Media >> Shiba Gallery page. Therefore, I enable pop-ups by adding the thickbox functionality to that page.

// Add to admin_menu action
		
// Add a new submenu
$my_page = add_media_page(__('Shiba Gallery', 'shiba_gallery'), __('Shiba Gallery', 'shiba_gallery'), 'administrator', 'shiba_gallery', 'my_plugin_page' );
add_action("admin_print_scripts-{$my_page}", 'my_plugin_page_scripts');
add_action("admin_print_styles-{$my_page}", 'my_plugin_page_styles');

function my_plugin_page_styles() {
	wp_enqueue_style('thickbox');
}
 
function my_plugin_page_scripts() {
	wp_enqueue_script('thickbox');
}

2. Associate Media Upload Interface with a Button or Link

Next, we want to add a button or link in our plugin page that calls up the Media Upload Interface.

<?php
$image_library_url = get_upload_iframe_src( 'image', null, 'library' );
$image_library_url = remove_query_arg( array('TB_iframe'), $image_library_url );
$image_library_url = add_query_arg( array( 'context' => 'shiba-gallery-default-image', 'TB_iframe' => 1 ), $image_library_url );
?>
        
<p>
<a title="Set default image" href="<?php echo esc_url( $image_library_url ); ?>" id="set-default-image" class="button thickbox">Set Default Image</a>
</p> 

Line 8 associates the interface with a button. Alternatively, we can make it into a regular link by simply setting our link class to –

class="thickbox"

Clicking on the 'Set Default Image' link brings up the Media Upload pop-up menu.

3. Set Our Own Tabs

Great! Now we have the Media Upload Interface associated to our own plugin page. However, we need to customize it to suit our needs.

First, let us make things simple and only enable the library tab.

add_filter('media_upload_tabs', 'my_plugin_image_tabs', 10, 1);

function my_plugin_image_tabs($_default_tabs) {
	unset($_default_tabs['type']);
	unset($_default_tabs['type_url']);
	unset($_default_tabs['gallery']);
		
	return($_default_tabs);	
}

The original $_default_tabs array looks like this –

Array
(
    [type] => From Computer
    [type_url] => From URL
    [library] => Media Library
    [gallery] => Gallery
)

Customize tabs to only show Media Library.

4. Set Our Own Action

However, when we expand an image, we still get the default ‘Insert into Post’ button. To customize this action button, we need to hook into the attachment_fields_to_edit and media_send_to_editor filters.

• The attachment_fields_to_edit filter allows us to customize the button itself.
• The media_send_to_editor filter allows us to specify what steps to take when the image action button gets pressed.

add_filter('attachment_fields_to_edit', 'my_plugin_action_button', 20, 2);
add_filter('media_send_to_editor', 'my_plugin_image_selected', 10, 3);

function my_plugin_action_button($form_fields, $post) {

        $send = "<input type='submit' class='button' name='send[$post->ID]' value='" . esc_attr__( 'Use as Default' ) . "' />";

	$form_fields['buttons'] = array('tr' => "\t\t<tr class='submit'><td></td><td class='savesend'>$send</td></tr>\n");
	$form_fields['context'] = array( 'input' => 'hidden', 'value' => 'shiba-gallery-default-image' );
	return $form_fields;
}

function my_plugin_image_selected($html, $send_id, $attachment) {
	?>
	<script type="text/javascript">
	/* <![CDATA[ */
	var win = window.dialogArguments || opener || parent || top;
				
	win.jQuery( '#default_image' ).val('<?php echo $send_id;?>');
	// submit the form
	win.jQuery( '#shiba-gallery_options' ).submit();
	/* ]]> */
	</script>
	<?php
	exit();
}

Line 17 – Get the parent window (i.e. the Shiba Gallery Options window and not the pop-up).

Line 19 – Fill the default_image input attribute of our parent form with the image id selected in our media pop-up window.

Line 21 – Submit our parent form.

Line 25 – Exit so that we only perform our specified actions and none other.

And just like that, we have changed our default image.

Success! We have changed our default image by using the Media Upload Interface.

5. Only Apply Customization on Our Plugin Pop-up Window

There is still one fly left in the ointment. If we follow the process above, our customization will be applied every time the Media Upload Interface is used. This messes up our ability to insert images into posts, or to set featured images.

Therefore, we only want to apply our customization where it is relevant. To do this, we check to see that we are in the right context before adding in our customization filters.

// Add to admin_menu
if (check_upload_image_context('shiba-gallery-default-image')) {
        add_filter('media_upload_tabs', 'my_plugin_image_tabs', 10, 1);
        add_filter('attachment_fields_to_edit', 'my_plugin_action_button', 20, 2);
        add_filter('media_send_to_editor', 'my_plugin_image_selected', 10, 3);
}


function add_my_context_to_url($url, $type) {
	if ($type != 'image') return $url;
	if (isset($_REQUEST['context'])) {
		$url = add_query_arg('context', $_REQUEST['context'], $url);
	}
	return $url;	
}
	
function check_upload_image_context($context) {
	if (isset($_REQUEST['context']) && $_REQUEST['context'] == $context) {
		add_filter('media_upload_form_url', array($this, 'add_my_context_to_url'), 10, 2);
		return TRUE;
	} 
	return FALSE;
}

Related Articles

Expand the WordPress Media Library Admin Panel

How to add options to the WordPress Media Library panel. This tutorial was written based on WordPress 2.8. The same concepts will apply to WordPress 2.9, but some alterations are may be needed for handling new media actions.

WordPress Page Redirect

How to redirect a page in WordPress. We consider wp_redirect, wp_redirect filter, PHP redirect, and Javascript redirect.

Shiba Media Library 1.0

This plugin tries to simplify some of the image attachment functions in the existing WordPress Media Library. There are several key limitations in the current WordPress (2.8) Media Library including - Awkward to attach groups of images to a post. Difficult to detach images from posts other than through deletion. Difficult to re-attach images to a different post. Unable to attach images to multiple posts. This simple plugin addresses the first three issues. How to Get Shiba Media [...]