* but this model class will tie it together as well as let you perform
* actions in a logical way.
*
+ * A simple example:
+ *
+ * var file = new OO.ui.SelectFileWidget(),
+ * button = new OO.ui.ButtonWidget( { label: 'Save' } ),
+ * upload = new mw.Upload;
+ *
+ * button.on( 'click', function () {
+ * upload.setFile( file.getValue() );
+ * upload.setFilename( file.getValue().name );
+ * upload.upload();
+ * } );
+ *
+ * $( 'body' ).append( file.$element, button.$element );
+ *
+ * You can also choose to {@link #uploadToStash stash the upload} and
+ * {@link #finishStashUpload finalize} it later:
+ *
+ * var file, // Some file object
+ * upload = new mw.Upload,
+ * stashPromise = $.Deferred();
+ *
+ * upload.setFile( file );
+ * upload.uploadToStash().then( function () {
+ * stashPromise.resolve();
+ * } );
+ *
+ * stashPromise.then( function () {
+ * upload.setFilename( 'foo' );
+ * upload.setText( 'bar' );
+ * upload.finishStashUpload().then( function () {
+ * console.log( 'Done!' );
+ * } );
+ * } );
+ *
* @constructor
- * @param {Object} apiconfig Passed to the constructor of mw.Api.
+ * @param {Object|mw.Api} [apiconfig] A mw.Api object (or subclass), or configuration
+ * to pass to the constructor of mw.Api.
*/
function Upload( apiconfig ) {
- this.api = new mw.Api( apiconfig );
+ this.api = ( apiconfig instanceof mw.Api ) ? apiconfig : new mw.Api( apiconfig );
this.watchlist = false;
this.text = '';
/**
* Set the text of the file page, to be created on file upload.
+ *
* @param {string} text
*/
UP.setText = function ( text ) {
/**
* Set the filename, to be finalized on upload.
+ *
* @param {string} filename
*/
UP.setFilename = function ( filename ) {
* Sets the filename based on the filename as it was on the upload.
*/
UP.setFilenameFromFile = function () {
- if ( this.file.nodeType && this.file.nodeType === Node.ELEMENT_NODE ) {
+ var file = this.getFile();
+ if ( file.nodeType && file.nodeType === Node.ELEMENT_NODE ) {
// File input element, use getBasename to cut out the path
- this.setFilename( this.getBasename( this.file.value ) );
- } else if ( this.file.name && this.file.lastModified ) {
+ this.setFilename( this.getBasename( file.value ) );
+ } else if ( file.name && file.lastModified ) {
// HTML5 FileAPI File object, but use getBasename to be safe
- this.setFilename( this.getBasename( this.file.name ) );
+ this.setFilename( this.getBasename( file.name ) );
}
};
/**
* Set the file to be uploaded.
+ *
* @param {HTMLInputElement|File} file
*/
UP.setFile = function ( file ) {
/**
* Set whether the file should be watchlisted after upload.
+ *
* @param {boolean} watchlist
*/
UP.setWatchlist = function ( watchlist ) {
/**
* Set the edit comment for the upload.
+ *
* @param {string} comment
*/
UP.setComment = function ( comment ) {
/**
* Get the text of the file page, to be created on file upload.
+ *
* @return {string}
*/
UP.getText = function () {
/**
* Get the filename, to be finalized on upload.
+ *
* @return {string}
*/
UP.getFilename = function () {
/**
* Get the file being uploaded.
+ *
* @return {HTMLInputElement|File}
*/
UP.getFile = function () {
/**
* Get the boolean for whether the file will be watchlisted after upload.
+ *
* @return {boolean}
*/
UP.getWatchlist = function () {
/**
* Get the current value of the edit comment for the upload.
+ *
* @return {string}
*/
UP.getComment = function () {
/**
* Gets the base filename from a path name.
+ *
* @param {string} path
* @return {string}
*/
/**
* Gets the state of the upload.
+ *
* @return {mw.Upload.State}
*/
UP.getState = function () {
* Get the imageinfo object for the finished upload.
* Only available once the upload is finished! Don't try to get it
* beforehand.
+ *
* @return {Object|undefined}
*/
UP.getImageInfo = function () {
/**
* Upload the file directly.
+ *
* @return {jQuery.Promise}
*/
UP.upload = function () {
var upload = this;
- if ( !this.file ) {
+ if ( !this.getFile() ) {
return $.Deferred().reject( 'No file to upload. Call setFile to add one.' );
}
- if ( !this.filename ) {
+ if ( !this.getFilename() ) {
return $.Deferred().reject( 'No filename set. Call setFilename to add one.' );
}
this.state = Upload.State.UPLOADING;
- return this.api.upload( this.file, {
- watchlist: ( this.watchlist === true ) ? 1 : undefined,
- comment: this.comment,
- filename: this.filename,
- text: this.text
+ return this.api.upload( this.getFile(), {
+ watchlist: ( this.getWatchlist() ) ? 1 : undefined,
+ comment: this.getComment(),
+ filename: this.getFilename(),
+ text: this.getText()
} ).then( function ( result ) {
upload.state = Upload.State.UPLOADED;
upload.imageinfo = result.upload.imageinfo;
/**
* Upload the file to the stash to be completed later.
+ *
* @return {jQuery.Promise}
*/
UP.uploadToStash = function () {
var upload = this;
- if ( !this.file ) {
+ if ( !this.getFile() ) {
return $.Deferred().reject( 'No file to upload. Call setFile to add one.' );
}
- if ( !this.filename ) {
+ if ( !this.getFilename() ) {
this.setFilenameFromFile();
}
this.state = Upload.State.UPLOADING;
- this.stashPromise = this.api.uploadToStash( this.file, {
- filename: this.filename
+ this.stashPromise = this.api.uploadToStash( this.getFile(), {
+ filename: this.getFilename()
} ).then( function ( finishStash ) {
upload.state = Upload.State.STASHED;
return finishStash;
/**
* Finish a stash upload.
+ *
* @return {jQuery.Promise}
*/
UP.finishStashUpload = function () {
upload.state = Upload.State.UPLOADING;
return finishStash( {
- watchlist: ( upload.watchlist === true ) ? 1 : undefined,
+ watchlist: ( upload.getWatchlist() ) ? 1 : undefined,
comment: upload.getComment(),
filename: upload.getFilename(),
text: upload.getText()