Tutorial: Writing a WordPress Plugin Using the Media Upload Tab

Since the introduction of WordPress 3.3 inserting media into a post has been reduced to the clicking of a single button, the Upload/Insert button.

A single click of this button allows you to upload any type of media that you desire and easily insert it into your post. WordPress plugins can take advantage of this functionality by integrating with the upload button providing a seamless experience for their users. The following tutorial assumes you are familiar with the basics of writing a wordpress plugin. If you are not check out the tutorial from wordpress.

To begin with you need to have a new tab displaying alongside all of the other media tabs in the uploader. This is accomplished by adding the following bit of code into your plugin and then calling it by adding a filter to media_upload_tabs

//Assign a name to your tab
function upload_test_media_menu($tabs) {
	$tabs['test_upload']='Test Upload';
	return $tabs;
}
 
//Needed script to make sure wordpresses media upload scripts are inplace
wp_enqueue_script('media-upload');
 
//Adds your tab to the media upload button
add_filter('media_upload_tabs', 'upload_test_media_menu');

If this is done correctly then the a tab with the name of Test Upload will appear next to all of the other tabs.

Our only problem now is that if we click on that test upload button we get a completely blank section.

To fix this we need to add a function that creates the iframe that the plugin will render in and add the tabs to the top of the frame. First we will render the iframe.

//This is our form for the plugin
function upload_test_upload_form () {
	media_upload_header();
	?>
	<div class="test-form">
	Here's some stuff in our plugin
	</div> 	
 
<?php }
 
//Returns the iframe that your plugin will be returned in
function upload_test_menu_handle() {
	return wp_iframe('upload_test_upload_form');
}

As you can see in our code example the function upload_test_upload_form is what is actually writing out what will eventually be our form. The first thing we want to do is call the function media_upload_header() This is a built in WordPress function that will create the other tabs in the media upload section. After that we have our divs and some text just so we can make sure the plugin is rendering properly.

From there our function is turned into an iframe in upload_test_menu_handle. We call the build in wordpress function wp_iframe to return an iframe with our form within it. From here we are going to call the menu handle when the Upload Media tab is clicked. This is accomplished by adding an action to the tab we just created.

//Adds your menu handle to when the media upload action occurs
add_action('media_upload_test_upload', 'upload_test_menu_handle');

As you can see in the code  our menu handle is attached to the action media_upload_test_upload This action name is determined by the name of the tab that you created earlier, in this case test_upload.

Right now our plugin should look like this.

We can check to make sure that we rendering the plugin properly by verifying that the text within our divs has appeared. However the problem right now is that our plugin does not look very good. We can only see the one tab up at the top and the others do not appear to be present at all. We can double check if this is just a styling issue by popping open which ever inspector you like and looking at <div id='media-upload-header'>

As you can see all of the other tabs are present in the DOM, they just are not rendering properly. We can fix this later with some css, simply enqueue this style to your plugin, all of these css rules were taken from the WordPress css for menu tabs.

div#media-upload-header, div#plugin-information-header {
background-color: #F9F9F9;
border-bottom-color: #DFDFDF;
}
div#media-upload-header {
margin: 0;
padding: 5px 5px 0;
font-weight: bold;
position: relative;
border-bottom-width: 1px;
border-bottom-style: solid;
}
 
body#media-upload ul#sidemenu {
font-weight: normal;
margin: 0 5px;
left: 0;
bottom: -1px;
float: none;
overflow: hidden;
}
#sidemenu{
margin: -30px 15px 0 315px;
list-style: none;
position: relative;
float: right;
padding-left: 10px;
font-size: 12px;
}
 
#sidemenu li {
display: inline;
line-height: 200%;
list-style: none;
text-align: center;
white-space: nowrap;
margin: 0;
padding: 0;
}
 
#sidemenu a {
background-color: #F9F9F9;
border-color: #F9F9F9;
border-bottom-color: #DFDFDF;
}
 
#sidemenu a {
padding: 0 7px;
display: block;
float: left;
line-height: 28px;
border-top-width: 1px;
border-top-style: solid;
border-bottom-width: 1px;
border-bottom-style: solid;
}

Of course the problem is right now our plugin doesn’t actually do anything. Let’s fix this by adding some form elements that will later be used to insert a piece of shortcode into the WordPress editor. Note that you can use this same code to add anything you would like into the editor as long as it can be translated into a string but for now lets just add a shortcode.

function upload_test_upload_form () {
	media_upload_header();
	?>
	<div class="test-form">
		<input type='text' id='name' />
		<input id='insert_shortcode' type='button' class='button' value='Insert Shortcode'>
	</div> 	
<?php }

Note that we have added a text field and a button that inserts the shortcode into our code. Make note that the button has a class of button. This is important if you want to use WordPress styling on the button.

So now we have a plugin with all the basic pieces. However it doesn’t actually do anything. To do this we must attach javascript to the button that inserts the piece of shortcode.

First we eneque the javascript file that we wish to add to our plugin then we call the function at the beginning of the plugin form. (We can also add our css at this point) We will also add JQuery to our plugin to make our lives a lot easier. (Explanation of how to enque a javascript file is beyond the scope of this tutorial, an explanation can be found here)

/Adds your scripts to your plugin
function upload_test_scripts() {
    //Adds css
    $myStyleUrl = plugins_url('upload-media.css', __FILE__);
    wp_register_style('myStyleSheets', $myStyleUrl);
    wp_enqueue_style( 'myStyleSheets');
 
    //Adds JQuery
    wp_deregister_script('jquery');
    wp_register_script( 'jquery', 'http://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js');
    wp_enqueue_script( 'jquery' );
 
    //Adds your custom script
    wp_deregister_script( 'upload-media-script' );
    wp_register_script( 'upload-media-script', '/wp-content/plugins/upload-media/upload-media.js');
    wp_enqueue_script( 'upload-media-script' );
}

We also need to create our javascript file and make it so that there is something in it. In our case we are just going to check that the file was added properly by having a console.log fire when we load the iframe.

(function ($) {
    $(function () {
        console.log('Our Plugin Works')
    });
})(jQuery);

If you have added your code correctly you should see something like this.

Now to get our plugin to do something useful.

First we need to write the insertShortcode function. All this function does is create our shortcode and then uses WordPress’s built in function to insert it into the editor. We then need to bind this function to the Insert Shortcode Button.

(function ($) {
	insertShortcode = function(name) {
			var win = window.dialogArguments || opener || parent || top;
			var shortcode='[testcode name='+name+']';
			win.send_to_editor(shortcode);
		}
 
	$(function () {
		$('#insert_shortcode').bind('click',function() {
				var name = $('#name').val();
				insertShortcode(name);
		});
	});
})(jQuery);

That’s it! Try it out. You should be able to enter some text into the field and have it be inserted into the post via the insert shortcode button.

To access all of the code that was created in this tutorial go to my github to get the plugin or download the zip.