How to Integrate WordPress Media Uploader in Your Plugin

If you are a WordPress plugin author, sometimes you might need to upload images to your plugins by using the WordPress built-in media uploader.

For example, let’s assume that you want to create a WordPress plugin for an image slider. To make it very easy to configure, it is desirable that you add an option which allows the user to upload the slider images in a user-friendly manner instead of constraining him to copy them to a specific folder on a server machine.

At the same time, you want the media uploader used by your plugin to display only the images that were uploaded for the plugin, not all the images uploaded to WordPress.

Below are the steps that must be taken to integrate the media uploader in your plugin.

Creating the Plugin Infrastructure

The name of our slideshow plugin will be “Simple Slideshow”. First, we must create a folder named simple-slideshow in the WordPress plugin directory. In this folder, we will create a file, simple-slideshow.php, which will contain the logic of our plugin.

Registering the Plugin in the WordPress Left Menu

To add our plugin to the left administration menu, the following lines must be added to the beginning of the simple-slideshow.php file:

add_action("admin_menu", "sss_add_menu");
function sss_add_menu()
{
    add_menu_page('Simple SlideShow', 'Simple SlideShow', 'administrator', 'simple_slideshow',
       'sss_display_admin_content', get_template_directory_uri() . '/images/favicon.ico');
}

If the plugin has configurable parameters, we must register them. Let’s suppose that we have a single configurable parameter which can be changed from the GUI. This parameter represents the sliding effect (sliding_effect).

add_action('admin_init', 'sss_init_menu');
function sss_init_menu()
{
    if (isset($_REQUEST['page']) && $_REQUEST['page'] == 'simple_slideshow') {
       register_setting('simple-slideshow-settings-group', 'sliding_effect');
    }
}

Below is the function that renders the plugin’s admin page. This function is called by WordPress during the process page flow.

function sss_display_admin_content()
{
    echo '<div class="wrap">';
    echo '<h2>Simple Slideshow</h2>';
    echo '<form id="simple_slideshow_form" action="options.php" method="post">';
   settings_fields('simple-slideshow-settings-group');
    echo '<input type="hidden" id="page_id" name="page" value="' . $_REQUEST['page'] . '"/>';
    echo '<h3>Generic Settings</h3>';
    echo '<table class="form-table">';

    $default_sliding_value = 'fade';
    $sliding_possible_values = array("Fade" => "fade", "Slide" => "slide");
    $sliding_field_value = get_option('sliding_effect');
    if (!isset($sliding_field_value) || empty($sliding_field_value)) {
       $sliding_field_value = $default_sliding_value;
    }

    echo '<tr valign="top">';
    echo '<th scope="row">Sliding Effect</th>';
    echo '<td>';
    echo '<select id="sliding_effect" name="sliding_effect" >';
    foreach ($sliding_possible_values as $key => $value) {
       if ($value == $sliding_field_value) {
           echo '<option value="' . $value . '" selected="selected">' . $key . '</option>';
       } else {
           echo '<option value="' . $value . '">' . $key . '</option>';
       }
    }
    echo '</select>';
    echo '</td>';
    echo '</tr>';

    echo '</table>';

    echo '<p class="submit">';
    echo '<input type="submit" class="button-primary" value="' . __('Save Changes') . '"/>';
    echo '</p>';
    echo '<input type="hidden" id="page_id" name="page" value="' . $_REQUEST['page'] . '"/>';
    echo '</form>';


    echo '<h3>Upload Images</h3>';
    echo '<table class="form-table">';

    echo '<tr valign="top">';
    echo '<td>';
    echo '<input id="sss_upload_image_button" value="Open Image Gallery" type="button" class="button"/>';
    echo '</td></tr>';
    echo '</table><br/>';
    echo '</div>';
}

Registering the Scripts and the Stylesheets for Our Plugin

The next step is to register the media uploader scripts and stylesheets. To do this, we need the following scrips and stylesheets:

Scripts:

• media-upload (WP script)
• thickbox (WP script)
• media-uploader-functions (custom script)
• media-uploader-script (custom script)

CSS:

• thickbox (WP CSS)

To register these scripts, we must add two actions to the simple-slideshow.php file: admin_print_scripts (registers and enqueues the scripts) and admin_print_styles (registers and enqueues the stylesheets).

add_action('admin_print_scripts', 'sss_register_plugin_scripts');
add_action('admin_print_styles', 'sss_register_plugin_styles');
function sss_register_plugin_scripts()
{
    wp_enqueue_script('media-upload');
    wp_enqueue_script('thickbox');
   wp_register_script('sss-media-uploader-functions', WP_PLUGIN_URL . '/simple-slideshow/js/media.uploader.functions.js');
   wp_register_script('sss-media-uploader-script', WP_PLUGIN_URL . '/simple-slideshow/js/media.uploader.js',
       array('jquery', 'media-upload', 'thickbox', 'sss-media-uploader-functions'));
   wp_enqueue_script('sss-media-uploader-script');
}

function sss_register_plugin_styles()
{
    wp_enqueue_style('thickbox');
}

To make the customized media uploader show only the images uploaded for this plugin, we must create some custom scripts as follows:

media.uploader.functions.js

This script defines the functions that are needed to display the media uploader pop-up. It must be located under the ‘js’ folder in the ‘simple-slideshow’ plugin.

function openMediaUploader() {

// The lines below refresh the page after the media uploader pop-up is closed.

    if ((window.original_tb_remove == undefined) && (window.tb_remove != undefined)) {
       window.original_tb_remove = window.tb_remove;
       window.tb_remove = function () {
           window.original_tb_remove();
           var href = window.location.href;
           var index = href.indexOf("?");
           if (index >= 0) {
               window.location.replace(href.substr(0, index) + "?page=simple_slideshow");
           }
       };
    }

// The line below displays the media uploader pop-up.

    tb_show('', 'media-upload.php?type=image&post_id=1&TB_iframe=true&flash=0&simple_slideshow=true');

/* The following lines append the value ‘&simple_slideshow=true’ to all the links in the media uploader pop-up. Based on this parameter, we can determine if the request came from the pop-up of our media uploader. */

   jQuery('iframe#TB_iframeContent').load(function () {

       jQuery(this).contents().find('#sidemenu li').each(function (i) {
           var tab_link = jQuery(this).children(":first-child");
           var href = tab_link.attr('href');
           if (href.indexOf('simple_slideshow') < 0) {
               tab_link.attr('href', href + '&simple_slideshow=true');
           }
       });

    });
    return false;
}

media.uploader.js

This script is executed after the plugin page is loaded. It defines what action should be performed when the user clicks on the button with an ID of ‘upload_image_button’. In our case, the pop-up will be displayed.

The script must be located in the ‘js’ folder in the ‘simple-slideshow’ plugin.

jQuery(document).ready(function () {

   jQuery('#sss_upload_image_button').click(function () {
       return openMediaUploader();
    });

    window.send_to_editor = function (html) {
       tb_remove();
    };

});

Customizing the Media Uploader Pop-Up

In this section, I will show how to customize the media uploader so that it displays only the images uploaded by us.

Before opening the pop-up, a small piece of JavaScript code is executed in order to rewrite all the URLs from the media upload pop-up. This script adds a custom parameter to the end of each URL, one thing that cannot be done for the Flash uploader. Because of this, I chose to disable the Flash upload mode.

To customize the media uploader, we must add the following filters:

1. flash_uploader – defines the directory to which the files are uploaded.
2. media_upload_tabs – defines which tabs must be displayed in the media uploader. (We will display only the ‘From Computer’ and ‘Gallery’ tabs.)
3. parse_query – redefines the SQL query that must be executed by the media uploader so that it can retrieve from the database the images which must be displayed.

$upload_dir = 'images/sss-images';
$plugin_dir = WP_PLUGIN_DIR . '/simple-slideshow';
$plugin_url = WP_PLUGIN_URL . '/simple-slideshow';

add_filter('flash_uploader', create_function('$a', 'return false;'), 5); //disable the Flash uploader
add_filter('media_upload_tabs', create_function('$a', 'return array(\'type\' => __(\'From Computer\'), \'gallery\' => __(\'Gallery\'));'));

add_filter('upload_dir', 'sss_configure_upload_dir');
function sss_configure_upload_dir($path_data)
{
    global $upload_dir;
    global $plugin_dir;
    global $plugin_url;

    $path_data['path'] = $plugin_dir . "/" . $upload_dir;
    $path_data['url'] = $plugin_url . "/" . $upload_dir;
    $path_data['subdir'] = "/" . $upload_dir;
    $path_data['basedir'] = $plugin_dir;
    $path_data['baseurl'] = $plugin_url;
    return $path_data;
}

add_filter('parse_query', 'sss_customize_media_library_query');
function sss_customize_media_library_query($query)
{
    global $upload_dir;
    $query->query_vars['meta_query'] = array(
       array(
           'value' => $upload_dir,
           'compare' => 'LIKE'
       ));
}

Conclusions

To summarize, we can see that it is relatively simple to integrate the WordPress media uploader pop-up in our plugin and customize it to display only the images uploaded by us. All we have to do is add some filters and register some scripts and stylesheets when the plugin page is loaded.

Using actions and filters, you can easily customize various functionalities offered by WordPress.