Welcome to MediaPress uploader events life cycle guide. The guide is aimed at developer who want to create their own uploading experience with MediaPress.
MediaPress uses plupload.Uploader for uploading files. It is the same library used by WordPress(and bundled with it). We have a Container class mpp.Uploader. The various instances of mpp.Uploader allows us uploading files.
Note:- All the events listed on this page are fired by the MediaPress uploader(mpp.Uploader) on the document object.
List of stages where you can hook into.
For all the events listed on this page, Any bound event listener callback will receive the Event object as the first parameter(You will ignore it most of the time) and an instance of mpp.Uploader as the second parameter. Rest of the parameters are determined by the events you need to hook to. Also, the events are triggered on document object. The event listeners should be bound to the document object to correctly intercept the event.
On File Selection:-
As soon as the user selects file(s), the files are added to our upload queue. mpp.Uploader triggers two events after the file selection.
- mpp:uploader:file.added :- It is fired when a file is added to the upload queue. It fires for each file of the selection(in case of multiple selection)
- mpp:uploader:files.added :- this event is fired when all the files from the selection have been added to the upload queue successfully.
mpp:uploader:file.added :-
A listener bound to this event will receive 3 arguements
- Event object.
- mpp.Uploader instance
- file Backbone.Model instance
Example:- Attaching a listener using javascript.
1 2 3 | $(document).on('mpp:uploader:file.added', function (event, mpp_uploader, file) { console.log( "File: "+ file.name + " successfully added to the queue"); }); |
If you want to know which uploader triggered it( e.g are we working with activity upload or gallery upload or shortcode upload etc), Please see the guide to determine it.
mpp:uploader:files.added :-
It is fired when all the selected files are added to the upload queue. A listener bound to this event will receive the following arguements
- Event object
- mpp.Uploader object
- plupload.Uploader instance
Example:-
1 2 3 | $(document).on('mpp:uploader:file.added', function (event, mpp_uploader, uploader) { console.log( "All files in current selection added to the queue"); }); |
On Upload Start:-
Before the upload starts for each of the file, following event is triggered
- mpp:uploader:before.upload
The bound listener will receive following arguements
- Event Object
- mpp.Uploader instance
- plupload.Uploader instance
- file Backbone.Model instance
You can use this hook to stop uploading a file.
Example:-
1 2 3 | $(document).on('mpp:uploader:before.upload', function (event, mpp_uploader, uploader, file) { console.log( "We are about to start uploading" + file.name ); }); |
On Upload Progress:-
If you need to hook to upload progress and do something, you can use the event:-
- mpp:uploader:upload.progress
The bound listener will receive following arguments:-
- Event object
- mpp.Uploader instance
- attachment :- Backbone Model object containing details about the uploading file.
The event gives you access to mpp.Uploader and the attachment object. On attchment, you can check for the ‘loaded’, ‘percent’ properties to check for the upload progress.
Example:-
1 2 3 | $(document).on('mpp:uploader:upload.progress', function (event, mpp_uploader, attachment) { // do something. }); |
On Upload Success:-
Whena file uploads successfully, the following event is fired for it
- mpp:uploader:upload.success
This even fires for each file individually.
The listener attached to this event will receive following argumenets
- Event object
- mpp.Uploader instance
- attachment :- Backbone Model object containing details about the uploading file.
Example:-
1 2 3 | $(document).on('mpp:uploader:upload.success', function (event, mpp_uploader, attachment) { console.log( attachment ); }); |
On All Upload Complete:-
When all files from the current queue get uploaded, the uploader fires the event:-
- mpp:uploader:upload.complete
A listener attached to it receives 4 arguements
- Event object
- mpp.Uploader instance
- plupload.Uploader instance
- Backbone collection of files.
Example:-
1 2 3 | $(document).on('mpp:uploader:upload.complete', function (event, mpp_uploader, uploader, files) { // do something here. }); |
On Error:-
For all type of error(Possibly a file selection error or upload failure error), MediaPress triggers ‘mpp:uploader:error‘ .
The listener attached to this event receives 4 arguements
- Event object
- mpp.Uploader instance
- message string
- data object
- file object
Example:-
1 2 3 | $(document).on('mpp:uploader:error', function (event, mpp_uploader, message, data, file) { // do something here. }); |
Uploader Type Check:-
In all the listeners, you receive the instance of current MediaPress uploader as second argument. You don’t need to worry about uploader check if you want to do some action on all the uploads irrespective of whether it is being uploaded.
There may be a time when you will want to determine whcih uploader was used(was it a gallery upload or was it happening on activity?) . Before we determine it, You will need to know the kind of mpp.Uploader instances which are used by MediaPress.
In MediaPress, we create multiple instance of the mpp.Uploader for uploading to activity, single gallery, using shortcode, cover upload. Here are the list of the instance object.
- mpp.activity_uploader :- our activity uploader.
- mpp.guploader :- Gallery uploader
- mpp.shortcode_uploader :- Shortcode uploader
- mpp.cover_uploader :- cover uploader
In order to determine the type of uploader, compare the 2nd arguement with one of the above. For example, if I want to check for upload complete from activity, I will do it like below:-
1 2 3 4 5 6 | $(document).on('mpp:uploader:upload.complete', function (event, mpp_uploader, uploader, files ) { // did it happen from activity uploader? if ( mpp_uploader === mpp.activity_uploader ) { console.log(" All files uploaded from activity"); } }); |
Further reading.
- plupload.Uploader
- jQuery.trigger