Wordpress Media Uploader
JQuery plugin for Wordpress that simplifies the development needed to upload media in custom themes and plugins.
Installation
Several installation options are available:
Setup
Enqueue the javascript file and wordpress media:
wp_enqueue_media();
wp_enqueue_script(
'wp-media-uploader',
PATH_TO_FILE . '/wordpress-media-uploader/dist/jquery.wp-media-uploader.min.js',
[ 'jquery', 'jquery-ui-core' ]
);
NOTE: PATH_TO_FILE should be replaced with the path to where Wordpress Media Uploader
is located. You can use the non-minified version too.
NOTE: See wp_enqueue_script codex reference for more options.
Usage
Basic
Here is a simple example of how to call the Media Gallery from an HTML:
<a href="#"
class="insert-media"
data-editor="my-editor"
>
Insert into post
</a>
Notice how the caller has class insert-media
and a unique identifier named at data-editor
(you should change this to your needs). Wordpress will recognize these two properties and open its Media Gallery Uploader on click.
Now lets add the element that will handle the results returned by the uploader and a target where to place the results.
<a href="#"
class="insert-media"
data-editor="my-editor"
>
Insert into post
</a>
<span id="media-caller"></span>
<div id="my-editor-media"></div>
With these in place, let's add the functionality in jQuery:
$("#media-caller").mediaUploader({
editor: "my-editor",
target: "#my-editor-media"
});
Notice how we are indicating which editor
and target
is the gallery uploader targeting to.
Rendering
Let's add a template so results are properly displayed:
<a href="#"
class="insert-media"
data-editor="my-editor"
>
Insert into post
</a>
<span id="media-caller">
<div class="attachment">
<img alt="{{ alt }}" height="45">
<input type="text" value="{{ url }}">
</div>
</span>
<div id="my-editor-media"></div>
Once Wordpress Media Uploader
starts, the template (HTML code) is removed from the caller and stored in a variable within the plugin. It is used then to display any media returned by The Gallery Uploader inside the targeted placeholder.
Available template variables (must be under parenthesis {{}}
):
Variable | Description | Media types |
---|
{{id}} | Attachment ID. | image |
{{url}} | Media url. | image, file |
{{alt}} | Alternative text. | image |
NOTE: When the media returned is an image, the src
attribute is added to the img
tag.
NOTE: When the media returned is a file, the img
tag is removed.
Options
Javascript available options:
Option | Data type | Description |
---|
editor | string | ID of The Media Gallery uploader. |
target | string | Element set as target placeholder for media results. |
render | boolean | Flag that indicates if plugin should render results. Default: true |
template | string | Alternative HTML template. Plugin will use this instead of the one inside the caller. |
clearTarget | boolean | Flag that indicates if plugin should clear the target before rendering results. Default: true |
clearTemplate | boolean | Flag that indicates if plugin should clear the template inside the caller. Default: true |
success | function | Callback function with media results as parameter, called after render process has finished. |
Here an example of how to prevent the plugin from rendering and do some custom logic instead:
$("#media-caller").mediaUploader({
editor: "my-editor",
render: false,
success: function(media) {
$.each(media, function() {
});
}
});
Methods
In order to use public methods. Plugin needs to be stored into a variable.
window.mediaUploader = $("#media-caller").mediaUploader();
Method | Description |
---|
add | Manually adds media to plugin. |
Method add()
mediaUploader.add({
type: 'image',
src: 'http://url.to.media',
id: 707,
alt: 'Image alt'
});
mediaUploader.add([]);
LICENSE
Wordpress Media Uploader is free software distributed under the terms of the MIT license.