2 * Provides an interface for uploading files to MediaWiki.
4 * @class mw.Api.plugin.upload
20 * Get nonce for iframe IDs on the page.
30 * Given a non-empty object, return one of its keys.
36 function getFirstKey( obj
) {
37 for ( var key
in obj
) {
38 if ( obj
.hasOwnProperty( key
) ) {
45 * Get new iframe object for an upload.
48 * @return {HTMLIframeElement}
50 function getNewIframe( id
) {
51 var frame
= document
.createElement( 'iframe' );
58 * Shortcut for getting hidden inputs
63 function getHiddenInput( name
, val
) {
64 return $( '<input>' ).attr( 'type', 'hidden' )
70 * Process the result of the form submission, returned to an iframe.
71 * This is the iframe's onload event.
73 * @param {HTMLIframeElement} iframe Iframe to extract result from
74 * @return {Object} Response from the server. The return value may or may
75 * not be an XMLDocument, this code was copied from elsewhere, so if you
76 * see an unexpected return type, please file a bug.
78 function processIframeResult( iframe
) {
80 doc
= iframe
.contentDocument
|| frames
[ iframe
.id
].document
;
82 if ( doc
.XMLDocument
) {
83 // The response is a document property in IE
84 return doc
.XMLDocument
;
88 // Get the json string
89 // We're actually searching through an HTML doc here --
90 // according to mdale we need to do this
91 // because IE does not load JSON properly in an iframe
92 json
= $( doc
.body
).find( 'pre' ).text();
94 return JSON
.parse( json
);
97 // Response is a xml document
101 function formDataAvailable() {
102 return window
.FormData
!== undefined &&
103 window
.File
!== undefined &&
104 window
.File
.prototype.slice
!== undefined;
107 $.extend( mw
.Api
.prototype, {
109 * Upload a file to MediaWiki.
111 * The file will be uploaded using AJAX and FormData, if the browser supports it, or via an
112 * iframe if it doesn't.
114 * Caveats of iframe upload:
115 * - The returned jQuery.Promise will not receive `progress` notifications during the upload
116 * - It is incompatible with uploads to a foreign wiki using mw.ForeignApi
117 * - You must pass a HTMLInputElement and not a File for it to be possible
119 * @param {HTMLInputElement|File|Blob} file HTML input type=file element with a file already inside
120 * of it, or a File object.
121 * @param {Object} data Other upload options, see action=upload API docs for more
122 * @return {jQuery.Promise}
124 upload: function ( file
, data
) {
125 var isFileInput
, canUseFormData
;
127 isFileInput
= file
&& file
.nodeType
=== Node
.ELEMENT_NODE
;
129 if ( formDataAvailable() && isFileInput
&& file
.files
) {
130 file
= file
.files
[ 0 ];
134 throw new Error( 'No file' );
137 // Blobs are allowed in formdata uploads, it turns out
138 canUseFormData
= formDataAvailable() && ( file
instanceof window
.File
|| file
instanceof window
.Blob
);
140 if ( !isFileInput
&& !canUseFormData
) {
141 throw new Error( 'Unsupported argument type passed to mw.Api.upload' );
144 if ( canUseFormData
) {
145 return this.uploadWithFormData( file
, data
);
148 return this.uploadWithIframe( file
, data
);
152 * Upload a file to MediaWiki with an iframe and a form.
154 * This method is necessary for browsers without the File/FormData
155 * APIs, and continues to work in browsers with those APIs.
157 * The rough sketch of how this method works is as follows:
158 * 1. An iframe is loaded with no content.
159 * 2. A form is submitted with the passed-in file input and some extras.
160 * 3. The MediaWiki API receives that form data, and sends back a response.
161 * 4. The response is sent to the iframe, because we set target=(iframe id)
162 * 5. The response is parsed out of the iframe's document, and passed back
163 * through the promise.
166 * @param {HTMLInputElement} file The file input with a file in it.
167 * @param {Object} data Other upload options, see action=upload API docs for more
168 * @return {jQuery.Promise}
170 uploadWithIframe: function ( file
, data
) {
172 tokenPromise
= $.Deferred(),
174 deferred
= $.Deferred(),
176 id
= 'uploadframe-' + nonce
,
177 $form
= $( '<form>' ),
178 iframe
= getNewIframe( id
),
179 $iframe
= $( iframe
);
181 for ( key
in data
) {
182 if ( !fieldsAllowed
[ key
] ) {
187 data
= $.extend( {}, this.defaults
.parameters
, { action
: 'upload' }, data
);
188 $form
.addClass( 'mw-api-upload-form' );
190 $form
.css( 'display', 'none' )
192 action
: this.defaults
.ajax
.url
,
195 enctype
: 'multipart/form-data'
198 $iframe
.one( 'load', function () {
199 $iframe
.one( 'load', function () {
200 var result
= processIframeResult( iframe
);
201 deferred
.notify( 1 );
204 deferred
.reject( 'ok-but-empty', 'No response from API on upload attempt.' );
205 } else if ( result
.error
) {
206 if ( result
.error
.code
=== 'badtoken' ) {
207 api
.badToken( 'csrf' );
210 deferred
.reject( result
.error
.code
, result
);
211 } else if ( result
.upload
&& result
.upload
.warnings
) {
212 deferred
.reject( getFirstKey( result
.upload
.warnings
), result
);
214 deferred
.resolve( result
);
217 tokenPromise
.done( function () {
222 $iframe
.on( 'error', function ( error
) {
223 deferred
.reject( 'http', error
);
226 $iframe
.prop( 'src', 'about:blank' ).hide();
230 $.each( data
, function ( key
, val
) {
231 $form
.append( getHiddenInput( key
, val
) );
234 if ( !data
.filename
&& !data
.stash
) {
235 throw new Error( 'Filename not included in file data.' );
238 if ( this.needToken() ) {
239 this.getEditToken().then( function ( token
) {
240 $form
.append( getHiddenInput( 'token', token
) );
241 tokenPromise
.resolve();
242 }, tokenPromise
.reject
);
244 tokenPromise
.resolve();
247 $( 'body' ).append( $form
, $iframe
);
249 deferred
.always( function () {
254 return deferred
.promise();
258 * Uploads a file using the FormData API.
262 * @param {Object} data Other upload options, see action=upload API docs for more
263 * @return {jQuery.Promise}
265 uploadWithFormData: function ( file
, data
) {
267 deferred
= $.Deferred();
269 for ( key
in data
) {
270 if ( !fieldsAllowed
[ key
] ) {
275 data
= $.extend( {}, this.defaults
.parameters
, { action
: 'upload' }, data
);
278 if ( !data
.filename
&& !data
.stash
) {
279 throw new Error( 'Filename not included in file data.' );
282 // Use this.postWithEditToken() or this.post()
283 this[ this.needToken() ? 'postWithEditToken' : 'post' ]( data
, {
284 // Use FormData (if we got here, we know that it's available)
285 contentType
: 'multipart/form-data',
286 // No timeout (default from mw.Api is 30 seconds)
288 // Provide upload progress notifications
290 var xhr
= $.ajaxSettings
.xhr();
292 // need to bind this event before we open the connection (see note at
293 // https://developer.mozilla.org/en-US/docs/DOM/XMLHttpRequest/Using_XMLHttpRequest#Monitoring_progress)
294 xhr
.upload
.addEventListener( 'progress', function ( ev
) {
295 if ( ev
.lengthComputable
) {
296 deferred
.notify( ev
.loaded
/ ev
.total
);
303 .done( function ( result
) {
304 deferred
.notify( 1 );
305 if ( result
.upload
&& result
.upload
.warnings
) {
306 deferred
.reject( getFirstKey( result
.upload
.warnings
), result
);
308 deferred
.resolve( result
);
311 .fail( function ( errorCode
, result
) {
312 deferred
.notify( 1 );
313 deferred
.reject( errorCode
, result
);
316 return deferred
.promise();
320 * Upload a file to the stash.
322 * This function will return a promise, which when resolved, will pass back a function
323 * to finish the stash upload. You can call that function with an argument containing
324 * more, or conflicting, data to pass to the server. For example:
326 * // upload a file to the stash with a placeholder filename
327 * api.uploadToStash( file, { filename: 'testing.png' } ).done( function ( finish ) {
328 * // finish is now the function we can use to finalize the upload
329 * // pass it a new filename from user input to override the initial value
330 * finish( { filename: getFilenameFromUser() } ).done( function ( data ) {
331 * // the upload is complete, data holds the API response
335 * @param {File|HTMLInputElement} file
336 * @param {Object} [data]
337 * @return {jQuery.Promise}
338 * @return {Function} return.finishStashUpload Call this function to finish the upload.
339 * @return {Object} return.finishStashUpload.data Additional data for the upload.
340 * @return {jQuery.Promise} return.finishStashUpload.return API promise for the final upload
341 * @return {Object} return.finishStashUpload.return.data API return value for the final upload
343 uploadToStash: function ( file
, data
) {
347 if ( !data
.filename
) {
348 throw new Error( 'Filename not included in file data.' );
351 function finishUpload( moreData
) {
352 return api
.uploadFromStash( filekey
, $.extend( data
, moreData
) );
355 return this.upload( file
, { stash
: true, filename
: data
.filename
} ).then(
356 function ( result
) {
357 filekey
= result
.upload
.filekey
;
360 function ( errorCode
, result
) {
361 if ( result
&& result
.upload
&& result
.upload
.filekey
) {
362 // Ignore any warnings if 'filekey' was returned, that's all we care about
363 filekey
= result
.upload
.filekey
;
364 return $.Deferred().resolve( finishUpload
);
366 return $.Deferred().reject( errorCode
, result
);
372 * Finish an upload in the stash.
374 * @param {string} filekey
375 * @param {Object} data
377 uploadFromStash: function ( filekey
, data
) {
378 data
.filekey
= filekey
;
379 data
.action
= 'upload';
380 data
.format
= 'json';
382 if ( !data
.filename
) {
383 throw new Error( 'Filename not included in file data.' );
386 return this.postWithEditToken( data
).then( function ( result
) {
387 if ( result
.upload
&& result
.upload
.warnings
) {
388 return $.Deferred().reject( getFirstKey( result
.upload
.warnings
), result
).promise();
394 needToken: function () {
401 * @mixins mw.Api.plugin.upload
403 }( mediaWiki
, jQuery
) );