WordPress Media Uploader

Inpired on amostajo/wordpress-media-uploader, this jquery library converts any DOM element into a media uploader input.

The Media Uploader will pop-up WordPress Media Library, and will allow to upload and or select uploaded media from the library.

Content:

• Install
• Basic usage
  • Enqueue
  • Via HTML
  • Via Javascript
• Options
  • HTML attributes
  • target
    • after
    • inside
    • DOM selector
  • mediaFilter
  • mediaMap
  • mediaLoad
• Events
• Methods
• Templating

Install

Via npm:

npm install wp-media-uploader

Or download release and add it into your project.

Basic usage

Enqueue

First enqueue script and media dependnecies:

// (1) Make sure WP media gallery is enqueued
wp_enqueue_media();

// (2) Enqueue "Wordpress Media Uploader"
wp_enqueue_script(
    'wp-media-uploader',
    PATH_TO_FILE . '/jquery.wp-media-uploader.min.js',
    [ 'jquery', 'jquery-ui-core' ],
    '1.0.0',
    true
);

If you want the plugin to load select attachments and render them for you, add wp-api as dependency:

// (1) Make sure WP media gallery is enqueued
wp_enqueue_media();

// (2) Enqueue "Wordpress Media Uploader"
wp_enqueue_script(
    'wp-media-uploader',
    PATH_TO_FILE . '/jquery.wp-media-uploader.min.js',
    [ 'jquery', 'jquery-ui-core', 'wp-api' ],
    '1.0.0',
    true
);

Via HTML

Instantiate via HTML by adding attribute role="media-uploader", additionally, you can configure all options via data attributes:

<a role="media-uploader"
    data-editor="my-editor"
>
    Add Media
</a>

Via Javascript

To instantiate via Javascript, first add an element in the DOM:

<a id="my-uploader">Add Media</a>

Then call to wp_media_uploader jQuery plugin:

$( '#my-uploader' ).wp_media_uploader( options );

Options

The following is the list of available jQuery plugin options:

| Option | Type | Description | | --- | --- | --- | | name | string | Input name. Required if this will be used inside a form. | | value | string | Input value. Values separated by commas when using the multiple option. | | editor | string | Editor ID. Default: the plugin will assign a unique ID | | target | string | Expected values after, inside or a DOM selector. This identifies where the selected will be rendered. Default: after | | render | bool | Flag that indicates if selected results should be rendered inside target or not. Default: true | | multiple | bool | Flag that indicates if multiple selection is allowed. Default: false | | clearOnSelection | bool | Flag that indicates if results in target should be cleared once a new selection is made, if set to false, results will be appended. The plugin will force this option to true when the multiple option is set to false. Default: true | | title | string | Title to display on top of the media uploader modal. | | buttonText | string | Selection button text to display inside the media uploader modal. | | mimeType | string | Expected values image, video or empty. | | size | string | The image size to use when rendering an image (for example: thumbnail, large or other). | | allowClose | bool | Wether or not to allow modal to close after selection. | | success | function | Function to use once a selection is made and after rendering. | | mediaFilter | function | Function to use to filter selected attachments before rendering. | | mediaMap | function | Function to use to map selected attachments before rendering. | | idValue | bool | Whether or not to use the attachment ID as the input value instead of a url. Default: true | | showInput | bool | Whether or not to display the input. Default: false | | inputCssClass | string | The CSS class(es) to assign to the input. | | targetCssClass | string | The CSS class(es) to assign to the target. | | templateImage | string | HTML or a DOM selector. Template to use for image-based attachments. Default: the plugin will use an internal template | | templateVideo | string | HTML or a DOM selector. Template to use for video-based attachments. Default: the plugin will use an internal template | | templateFile | string | HTML or a DOM selector. Template to use for file-based attachments. Default: the plugin will use an internal template | | templateEmbed | string | HTML or a DOM selector. Template to use for embed-based attachments (Simple Post Gallery plugin). Default: the plugin will use an internal template | | mediaLoad | string | Expectes the name of a global (window) function or empty. This is the callable that will be used to load the media when the plugin is ready. Default: the plugin will user WordPress rest api (if avialable) to load the attachment (Only supports ID values). |

HTML attributes

The following lists the HTML attributes and their javascript option counter-part:

| HTML attrbutes | Option | Value type | | --- | --- | --- | | value | value | string | | name | name | string | | multiple | multiple | int (values 1 or 0) | | data-editor | editor | string | | data-target | target | string | | data-render | render | int (values 1 or 0) | | data-clear-on-selection | clearOnSelection | int (values 1 or 0) | | data-title | title | string | | data-button | mimeType | string | | data-type | size | string | | data-size | size | string | | data-allow-close | allowClose | int (values 1 or 0) | | data-id-value | idValue | int (values 1 or 0) | | data-show-input | showInput | int (values 1 or 0) | | data-input-class | inputCssClass | string | | data-target-class | targetCssClass | string | | data-media-load | mediaLoad | string | | data-template-image | templateImage | string | | data-template-video | templateVideo | string | | data-template-file | templateFile | string | | data-template-embed | templateEmbed | string |

Option: target

This option allows you to define where is the selection going to be rendered.

after

Note: This is the default value.

Target set to after will make the plugin generate a unique container that will be placed right after the uploader. Selection will be rendered inside the generated <div>:

$( '#my-uploader' ).wp_media_uploader();

<button id="my-uploader">Add Media</button>
<!-- Generated "div" target will be placed here -->

inside

Target set to inside will make the plugin render the selection inside its own HTML element:

$( '#my-uploader' ).wp_media_uploader( {
    target: 'inside',
} );

<div id="my-uploader">
    Click to add media here
    <!-- Selection will be rendered here. the text "Click to add media here" will be cleared upon selection -->
</div>

selector

Target set to a DOM selector will allow you to determine where to render the selection:

$( '#my-uploader' ).wp_media_uploader( {
    target: '#my-container',
} );

<button id="my-uploader">Add Media</button>
<div id="my-container"></div>

Option: mediaFilter

This option allows you to filter attachments before they are rendered, for example, the next snippet filters and returns only attachments with url property:

$( '#my-uploader' ).wp_media_uploader( {
    mediaFilter: function( attachment ) {
        return attachment.url !== undefined;
    },
} );

Option: mediaMap

This option allows you to map and modify attachments before they are rendered, for example, the next snippet maps and returns a modified attachment:

$( '#my-uploader' ).wp_media_uploader( {
    mediaMap: function( attachment ) {
        attachment.is_invalid = isNaN( attachment.id );
        attachment.id = 55;
        return attachment;
    },
} );

Option: mediaLoad

This option allows you to set your own custom global function that will handle the initial attachments load, by default the plugin uses wp.api @ media endpoint; the next snippet uses a custom api endpoint to retrieve the attachments:

$( '#my-uploader' ).wp_media_uploader( {
    value: '45,65,77', // IDs separated by comma
    mediaLoad: 'custom_load_media',
} );

/**
 * @param {object} uploader The uploader instance.
 * @param {array}  values   The collection of values.
 */
window.custom_load_media = function( uploader, values )
{
    // Verify
    if ( wp === undefined || wp.api === undefined )
        return;
    // Disable uploader (to prevent selection during loading)
    uploader.$el.prop( 'disabled', true );
    uploader.$el.addClass( 'loading' );
    uploader.$el.attr( 'disabled', 'disabled' );
    // Make request
    wp.apiRequest( {
        path: 'custom_namespace/v1/custom_endpoint',
        method: 'GET',
        data: {
            values: values,
        },
    } )
    .then( function( data ) {
        var attachments = [];
        // Process data
        for ( var i in data ) {
            // This is the minumin media properties expected to fill
            var media = {
                _model: undefined,
                id: data[i].id,
                type: data[i].type,
                url: data[i].url,
            };
            if ( data[i].alt_text )
                media.alt = data[i].alt_text;
            if ( uploader.options.size
                && data[i].sizes
                && data[i].sizes[uploader.options.size]
            )
                media.url = data[i].sizes[uploader.options.size];
            attachments.push( media );
        }
        uploader.render( attachments );
        // Enable uploader
        uploader.$el.prop( 'disabled', false );
        uploader.$el.removeAttr( 'disabled' );
        uploader.$el.removeClass( 'loading' );
    } );
}

You can also stop the plugin from loading media by sending and empty string as parameter. For instance, this is useful if you plan to add load the attachment with PHP.

$( '#my-uploader' ).wp_media_uploader( {
    value: '45,65,77',
    mediaLoad: '',
    target: '#my-container'
} );

<a id="my-uploader">Add Media</a>
<div id="my-container">
    <?php if ( $attachment ) : ?>
        <div id="<?php echo esc_attr( $attachment->ID ) ?>" class="attachment">
            <!-- custom template-->
        </div>
    <?php endif ?>
</div>

IMPORTANT: If you will load the attachment(s) via PHP, make sure the markup is wrapped inside a div with the following attributes id="{attachment_id}" and class="attachment".

Events

List of events:

| Event | Parameters | Description | | --- | --- | --- | | uploader:ready | values, uploader | Triggered when the plugin has initialized and it is ready. | | uploader:open | uploader | Triggered after WordPress media modal is called and opened. | | uploader:render.before | uploader | Triggered before rendering. | | uploader:render.after | uploader | Triggered after rendering. | | uploader:render | | Triggered after rendering (no parameters). | | uploader:attachments | array, uploader | Triggered after attachments have been selected, filtered and mapped. Before rendering. | | uploader:selection | array, uploader | Triggered after rendering. The array is the raw collection of models returned by WordPress media uploader modal and not the list of attachements proccessed by the plugin. | | uploader:clear | | Triggered after selection has been cleared. Also triggers uploader:attachments and uploader:selection. |

Event usage

$( '#my-uploader' ).on( event, handler );

Examples:

$( '#my-uploader' ).on( 'uploader:ready', function() {
    alert( 'Ready!' );
} );

$( '#my-uploader' ).on( 'uploader:attachments', function( event, attachments, uploader ) {
    console.log( attachments );
    uploader.$el.hide();
} );

Methods

List of methods:

| Method | Parameters | Description | | --- | --- | --- | | destroy | | Destroys plugin instance. | | clear | | Clears current selection. |

Usage example:

$( '#my-uploader' ).wp_media_uploader( 'destroy' );

Templating

Templating using external selector

The best way to explain templating is with a case scenario.

The following snippets will customize the plugin to use jquery-ui-sortable to enabled sorting inside the target, to allow sorting ofrendered results using drag-and-drop. The image template will be replaced to add an extra remove button, so selected media can be removed from selection.

(1) Enqueue sortable and add WP.API dependency

The following sample, will enqueue the plugin, plus wordpress media, jquery-ui-sortable and wp-api.

wp_enqueue_media();
wp_enqueue_script(
    'wp-media-uploader',
    PATH_TO_FILE . '/jquery.wp-media-uploader.min.js',
    [ 'jquery', 'jquery-ui-core', 'jquery-ui-sortable', 'wp-api' ],
    '1.0.0',
    true
);

(2) Uploader initialized via HTML

The following sample will initialize the uploader input via HTML. The PHP value passed as attribute is validated first, to see if is an array or not, and if so, the value is passed as a comma separated list. sortable css class will be added to the generated target. The template inside #gallery-image will be used to render all selected images. data-clear-on-selection will allow for new selection to be appended to the target.

<div id="gallery" class="gallery-container">
    <button role="media-uploader"
        id="gallery"
        type="button"
        class="button"
        name="gallery"
        value="<?php echo esc_attr( is_array( $gallery ) ? implode( ',', $gallery ) : $gallery ) ?>"
        multiple="multiple"
        data-type="image"
        data-editor="gallery"
        data-clear-on-selection="0"
        data-target-css="sortable"
        data-template-image="#gallery-image"
    ><?php echo __( 'Add Media' ) ?></button>
</div>
<script id="gallery-image" type="text/template">
    <div class="attachment">
        <img><input type="text"/>
        <span class="remove">&times;</span>
    </div>
</script>

(3) Init sortable on ready event

The following sample will initialize sortable once the plugin is ready and has generated the target <div>.

$( '#my-uploader' ).on( 'uploader:ready', function( event, uploader ) {
    if ( uploader.$target.hasClass( 'sortable' ) )
        uploader.$target.sortable();
} );

(4) Add remove behavior

The following sample will allow to remove attachments.

$( document ).on( 'click', '.attachment .remove', function( event ) {
    event.preventDefault();
    if ( confirm( 'Do you really want to remove this item?' ) ) {
        $( this ).closest( '.attachment' ).remove();
    }
} );

Templating using attributes

Another way of templating is by using the data-template-image, data-template-video, data-template-file, and data-template-embed attributes.

The plugin will look for the following selectors inside the template to append data:

| Selector | Behavior | | --- | --- | | input | The plugin will add the media's value in the value attribute of the input element. The plugin will add the name attribute with the respective name. | | .inject-media-id | The plugin will put the media's ID inside the element with this selector. | | .inject-media-url | The plugin will put the media's URL inside the element with this selector. | | .inject-media-filename | The plugin will put the media's filename inside the element with this selector. | | img | ONLY FOR IMAGE AND EMBED The plugin will add the media's URL in the src attribute of the element. If the media has an alt text, the plugin will add the media's alt text in the alt attribute of the element. | | source | ONLY FOR VIDEO The plugin will add the media's URL in the src attribute of the element. |

Any template passed through as an attribute must be wrapped in an extra <div> wrapper element. For example:

<div><div class="attachment type-file"><span class="inject-media-filename"></span><input type="hidden"/></div><div>

Above, the template is wrapped in a <div> which holds another <div> with the CSS classes attachment type-file, this second <div> is the one that will be used for rendering. Additionally, the media's filename will be injected inside the <span> with the class inject-media-filename and will add the media's value as an attribute on the input element.

There rendered output will look like this:

<div class="attachment type-file" id="123"><span class="inject-media-filename">filename.jpg</span><input type="hidden" value="123"/></div>

Finally, this is how uploader initialization will look like:

<div role="media-uploader"
    name="test"
    multiple="multiple"
    data-editor="test"
    data-template-file='<div><div class="attachment type-file"><span class="inject-media-filename"></span><input type="hidden"/></div><div>'
><?php echo __( 'Add Media' ) ?></div>

License

MIT - (c) 2022 10 Quality Studio.