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