diff --git a/client/typescript/fine-uploader.d.ts b/client/typescript/fine-uploader.d.ts index 011a6bddc..27bfc8655 100644 --- a/client/typescript/fine-uploader.d.ts +++ b/client/typescript/fine-uploader.d.ts @@ -2,2973 +2,2300 @@ // Project: http://fineuploader.com/ // Definitions by: Sukhdeep Singh -/** - * The FineUploader namespace contains all the methods, options, events and types - */ -declare namespace FineUploader { - /* ========================================================== CORE & UI ===================================================================== */ - /** - * type for `resizeInfo` object - */ - interface ResizeInfo { +declare module "fine-uploader/lib/core" { + + + export class FineUploaderBasic { + /** - * The original `File` or `Blob` object, if available. + * The FineUploader Core only constructor */ - blob?: File | Blob; + constructor(fineuploaderOptions?: CoreOptions); + /** - * Desired height of the image after the resize operation. + * FineUploader's Promise implementation */ - height?: number; + Promise(): void; + /** - * The original HTMLImageElement object, if available. + * Submit one or more files to the uploader + * + * @param any[] files : An array of `File`s, ``s, `Blob`s, `BlobWrapper` objects, ``es, or `CanvasWrapper` objects. You may also pass in a `FileList`. + * @param any params : A set of parameters to send with the file to be added + * @param string endpoint : The endpoint to send this file to */ - image?: HTMLImageElement; + addFiles(files: File[] + | HTMLInputElement[] + | Blob[] + | BlobWrapper + | HTMLCanvasElement[] + | CanvasWrapper + | FileList, params?: any, endpoint?: string): void; + /** - * `HTMLCanvasElement` element containing the original image data (not resized). + * Submit one or more canned/initial files to the uploader + * + * @param any[] initialFiles : An array of objects that describe files already on the server */ - sourceCanvas?: HTMLCanvasElement; + addInitialFiles(initialFiles: any[]): void; + /** - * `HTMLCanvasElement` element containing the `HTMLCanvasElement` that should contain the resized image. + * Cancel the queued or currently uploading item which corresponds to the id + * + * @param number id : The file's id */ - targetCanvas?: HTMLCanvasElement; + cancel(id: number): void; + /** - * Desired width of the image after the resize operation. + * Cancels all queued or currently uploading items */ - width?: number; - } + cancelAll(): void; - /** - * Callback type for `customResizer` parameter - */ - interface CustomResizerCallBack { /** - * Contribute this function to manually resize images using alternate 3rd party libraries - * - * @param ResizeInfo resizeInfo : the ResizeInfo object containing all the resize values/options - * @returns Promise : Once the resize is complete, the function must return a promise + * Clears the internal list of stored items. Only applies when autoUpload is false */ - (resizeInfo: ResizeInfo): PromiseOptions; - } + clearStoredFiles(): void; - /** - * A BlobWrapper object type - */ - interface BlobWrapper { /** - * the bytes of the `Blob` object being uploaded + * Attempts to continue a paused upload + * + * @param number id : A file id + * @returns boolean : `true` if attempt was successful. */ - blob?: Blob; + continueUpload(id: number): boolean; + /** - * the name of the `Blob` + * Send a delete request to the server for the corresponding file id + * + * @param number id : The file's id */ - name?: string; - } + deleteFile(id: number): void; - /** - * A CanvasWrapper Object type - */ - interface CanvasWrapper { /** - * the `` to be converted to a file & then uploaded + * Draws a thumbnail + * + * @param number id : The id of the image file + * @param HTMLElement targetContainer : The element where the image preview will be drawn. Must be either an or element + * @param number maxSize : The maximum dimensions (for width and height) you will allow this image to scale to + * @param boolean fromServer : true if the image data will come as a response from the server rather than be generated client-side + * @param CustomResizerCallBack customResizer : Ignored if the current browser does not support image previews. + * If you want to use an alternate library to resize the image, you must contribute a function for this option that returns a `Promise`. + * Once the resize is complete, your promise must be fulfilled. + * You may, of course, reject your returned `Promise` is the resize fails in some way. + * @returns Promise: Fulfilled by passing the container back into the success callback after the thumbnail has been rendered. + * If the thumbnail cannot be rendered, failure callbacks will be invoked instead, passing an object with `container` and `error` properties. */ - canvas?: HTMLCanvasElement; + drawThumbnail(id: number, targetContainer: HTMLElement, maxSize?: number, fromServer?: boolean, customResizer?: CustomResizerCallBack): PromiseOptions; + /** - * the name to assign to the created file + * Returns the button container element associated with a file + * + * @param number id : The file id + * @returns HTMLElement : The button container element associated with a file, or `undefined` if the file was not submitted via a Fine Uploader controlled upload button. */ - name?: string; + getButton(id: number): HTMLElement; + /** - * `1`-`100` value indicating the desired quality of the converted file (only for `image/jpeg`) + * Returns the file identified by the id. File API browsers only + * + * @param number id : The file id + * @returns File | Blob : A `File` or `Blob` object */ - quality?: number; + getFile(id: number): File | Blob; + /** - * MIME type of the file to create from this `` + * Returns the endpoint associated with a particular file, or the current catch-all endpoint for all files (if no ID is specified). + * + * @param number id : The ID of the associated file + * @return string | string[] : endpoint associated with a particular file, or the current catch-all endpoint for all files (if no ID is specified). */ - type?: MimeType; - } + getEndpoint(id?: number): string | string[]; - /** - * Resumable file object type - */ - interface ResumableFileObject { /** - * filename + * Returns the number of items that are either currently uploading or waiting for an available connection (`qq.status.QUEUED`). + * + * If called inside of a cancel event handler, then this method will return a value that includes the upload associated with the cancel event handler. + * This is because the upload will not be canceled until the event handler returns. + * + * @returns number : The number of items that are currently uploading or queued */ - name?: string; + getInProgress(): number; + /** - * the unique id + * Returns the name of the file with the associated id + * + * @param number id : The file id + * @returns string : Returns the name of the file identified by the id. */ - uuid?: number; + getName(id: number): string; + /** - * the index of the part where the resume will start from + * Get the number of items that have been successfully uploaded and have not been deleted + * + * @returns number : The number of items that have been successfully uploaded and not deleted */ - partIdx?: number; - } + getNetUploads(): number; - /** - * Resumable file object type for S3 - */ - interface S3ResumableFileObject extends ResumableFileObject { /** - * The associated object's S3 key + * Get the ID of the parent file for this scaled file + * + * @param number scaledFileId : The ID of a scaled image file + * @returns number : Returns the ID of the scaled image's parent file. `null` if this is not a scaled image or a parent cannot be located */ - key?: string; - } + getParentId(scaledFileId: number): number; - /** - * Resumable file object type for Azure - */ - interface AzureResumableFileObject extends ResumableFileObject { /** - * The associated file's blob name in Azure Blob Storage + * Returns the number of remaining allowed items that may be submitted for upload based on `validation.itemLimit`. */ - key?: string; - } + getRemainingAllowedItems(): number; - /** - * type for getUploads method's filter parameter - */ - interface UploadFilter { /** - * the id of the file + * Returns an array of potentially resumable items + * + * @returns ResumableFileObject[] : An array of resumable items */ - id?: number | number[]; + getResumableFilesData(): ResumableFileObject[] | ResumableFileObject; + /** - * the uuid of the file + * Returns the size of the item with the associated id + * + * @param number id : The file id + * @returns number : The size of the file with the corresponding id */ - uuid?: number | number[]; + getSize(id: number): number; + /** - * status of the file + * Return information about all the items that have been submitted to the uploader + * + * @param UploadFilter filter : An object which indicates which keys and values must be present in an upload to be returned + * @return FoundUploadItems | FoundUploadItems [] : A list of items or a single item that has been filtered/found. + * This returns an array only when there is a potential for the operation to return more than one file in the result set. + * This excludes queries for a specific, single ID or UUID. All other queries will return an array */ - status?: string | string[]; - } + getUploads(filter?: UploadFilter): FoundUploadItems | FoundUploadItems[]; - /** - * type for getUploads method's return object - */ - interface FoundUploadItems extends UploadFilter { /** - * the name of the file + * Returns the UUID of the item with the associated id + * + * @param number id : The file id + * @returns string : A level 4 UUID which identifies the corresponding file */ - name?: string; + getUuid(id: number): string; + /** - * the size of the file + * Output a message to the console, if possible + * + * @param string message : The message to print + * @param string level : The level to output the message at */ - size?: string; - } + log(message: string, level?: string): void; - /** - * ScaleImageOptions - */ - interface ScaleImageOptions { /** - * required + * Attempts to pause an in-progress upload + * + * @param number id : The file id + * @returns boolean : `true` if the attempt was successful. `false` otherwise */ - maxSize: number; + pauseUpload(id: number): boolean; + /** - * @default `true` + * Remove internal reference to the associated Blob/File object. + * + * For Blobs that are created via JavaScript in the browser, this will free up all consumed memory. */ - orient?: boolean; + removeFileRef(id: number): void; + /** - * defaults to the type of the reference image + * Reset Fine Uploader */ - type?: string; + reset(): void; + /** - * number between `0` and `100` - * - * @default `80` + * Attempt to upload a specific item again + * + * @param number id : The file id */ - quality?: number; + retry(id: number): void; + /** - * @default `false` + * Generates a scaled version of a submitted image file + * + * @param number id : The id of the image file + * @param ScaleImageOptions option : Information about the scaled image to generate + * @returns PromiseOptions : Fulfilled by passing the scaled image as a `Blob` back into the success callback after the original image has been scaled. + * If the scaled image cannot be generated, the failure callback will be invoked instead */ - includeExif?: boolean; + scaleImage(id: number, options: ScaleImageOptions): PromiseOptions; + /** - * Ignored if the current browser does not support image previews. - * - * If you want to use an alternate library to resize the image, you must contribute a function for this option that returns a `Promise`. - * - * Once the resize is complete, your promise must be fulfilled. - * You may, of course, reject your returned `Promise` is the resize fails in some way. + * Set custom headers for an upload request. Pass in a file id to make the headers specific to that file + * + * @param any customHeaders : The custom headers to include in the upload request. Fine Uploader may also send some other required headers + * @param number id : The file id */ - customResizer?: CustomResizerCallBack; - } - - /** - * formatFileName function type - */ - interface FormatFileNameFuncton { - (fileOrBlobName: string): String | void; - } + setCustomHeaders(customHeaders: any, id?: number): void; - /** - * BlobsOptions - */ - interface BlobsOptions { /** - * The default name to be used for nameless `Blob`s - * - * @default `Misc data` + * Modify the location where upload requests should be directed. Pass in a file id to change the endpoint for that specific item + * + * @param string path : A valid URI where upload requests will be sent + * @param number | HTMLElement identifier : An integer or HTMLElement corresponding to a file */ - defaultName?: string; - } + setEndpoint(path: string, identifier?: number | HTMLElement): void; - /** - * CameraOptions - */ - interface CameraOptions { /** - * `null` allows camera access on the default button in iOS. - * - * Otherwise provide an extra button container element to target - * - * @default `null` + * Set custom headers for a delete file request. Pass in a file id to make the headers specific to that file + * + * @param any customHeaders : The custom headers to include in the upload request. Fine Uploader may also send some other required headers + * @param number id : The file id */ - button?: HTMLElement; + setDeleteFileCustomHeaders(customHeaders: any, id?: number): void; + /** - * Enable or disable camera access on iOS (iPod, iPhone, and iPad) devices. - * - * ###Note: - * Enabling this will disable multiple file selection - * - * @default `false` + * Modify the location where delete requests should be directed. Pass in a file id to change the endpoint for that specific item + * + * @param string path : A valid URI where delete requests will be sent + * @param number | HTMLElement identifier : An integer or HTMLElement corresponding to a file */ - ios?: boolean; - } + setDeleteFileEndpoint(path: string, identifier?: number | HTMLElement): void; - /** - * ConcurrentOptions - */ - interface ConcurrentOptions { /** - * Allow multiple chunks to be uploaded simultaneously per file - * - * @default `false` + * Set the parameters for a delete request. Pass in a file id to make the parameters specific to that file + * + * @param any params : The parameters to include in the delete request + * @param number id : The file id */ - enabled?: boolean; - } + setDeleteFileParams(params: any, id?: number): void; - /** - * ChunkingOptions - */ - interface ChunkingOptions { - /** - * concurrent Chunking options - */ - concurrent?: ConcurrentOptions; /** - * Enable or disable splitting the file separate chunks. Each chunks is sent in a separate requested - * - * @default `false` + * Change the `validation.itemLimit` option set during construction/initialization + * + * @param number newItemLimit : The new file count limit */ - enabled?: boolean; + setItemLimit(newItemLimit: number): void; + /** - * Ensure every file is uploaded in chunks, even if the file can only be split up into 1 chunk. - * - * Does not apply if chunking is not possible in the current browser - * - * @default `false` + * Bind a `
` to Fine Uploader dynamically + * + * @param HTMLFormElement | string formElementOrId : A form element or a form element's ID */ - mandatory?: boolean; + setForm(formElementOrId: HTMLFormElement | string): void; + /** - * The maximum size of each chunk, in bytes - * - * @default `2000000` + * Change the name of a file + * + * @param number id: The file id + * @param string name : The new file name */ - partSize?: number; + setName(id: number, name: string): void; + /** - * ParamNamesOptions + * Set the parameters for an upload request. Pass in a file id to make the parameters specific to that file + * + * @param any params : The parameters to include in the upload request + * @param number id : The file id */ - paramNames?: ParamNamesOptions; + setParams(params: any, id?: number): void; + /** - * SuccessOptions + * Modify the status of an file. + * The status values correspond to those found in the qq.status object. + * Currently, the following status values may be set via this method: + * - qq.status.DELETED + * - qq.status.DELETE_FAILED + * + * @param number id : The file id + * @param string newStatus : The new qq.status value. */ - success?: SuccessOptions; - - } + setStatus(id: number, newStatus: string): void; - /** - * ParamNamesOptions - */ - interface ParamNamesOptions { /** - * Name of the parameter passed with a chunked request that specifies the size in bytes of the associated chunk - * - * @default `'qqchunksize'` + * Change the UUID of a file + * + * @param number id : The file id + * @param string uuid : The new file UUID */ - chunkSize?: string; + setUuid(id: number, uuid: string): void; + /** - * Name of the parameter passed with a chunked request that specifies the starting byte of the associated chunk - * - * @default `'qqpartbyteoffset'` + * Begin uploading all queued items. Throws a `NoFilesError` if there are no items to upload */ - partByteOffset?: string; + uploadStoredFiles(): void; + + + /* ====================================== UTILITY METHODS ======================================= */ + + /** - * Name of the parameter passed with a chunked request that specifies the index of the associated partition - * - * @default `'qqpartindex'` + * Returns an array of all immediate children of this element. + * + * @param HTMLElement element : An HTMLElement or an already wrapped qq object + * @returns HTMLElement[] : An array of HTMLElements who are children of the `element` parameter */ - partIndex?: string; + children(element: HTMLElement): HTMLElement[]; + /** - * Name of the parameter passed with a chunked request that specifies the total number of chunks associated with the `File` or `Blob` - * - * @default `'qqtotalparts'` + * Returns true if the element contains the passed element. + * + * @param HTMLElement element : An HTMLElement or an already wrapped qq object + * @returns boolean : The result of the contains test */ - totalParts?: string; + contains(element: HTMLElement): boolean; + /** - * Sent with the first request of the resume with a value of `true` - * - * @default `'qqresume'` + * Returns `true` if the attribute exists on the element and the value of the attribute is not 'false' case-insensitive. + * + * @param string attributeName : An attribute to test for + * @returns boolean : The result of the `hasAttribute` test */ - resuming?: string; + hasAttribute(attributeName: string): boolean; + /** - * totalFileSize - * - * @default `'qqtotalfilesize'` + * Clears all text for this element */ - totalFileSize?: string; - } + clearText(): void; - /** - * SuccessOptions - */ - interface SuccessOptions { /** - * Endpoint to send a POST after all chunks have been successfully uploaded for each file. - * - * Required if the `concurrent.enabled` option is set - * - * @default `null` + * Inserts the element directly before the passed element in the DOM. + * + * @param HTMLElement element : the `element` before which an element has to be inserted */ - endpoint?: string; - } + insertBefore(element: HTMLElement): void; - /** - * CorsOptions - */ - interface CorsOptions { /** - * Enable or disable cross-origin requests from IE9 and older where XDomainRequest must be used - * - * @default `false` + * Removes the element from the DOM. */ - allowXdr?: boolean; + remove(): void; + /** - * Enable or disable cross-domain requests - * - * @default `false` + * Sets the inner text for this element. + * + * @param string text : The text to set */ - expected?: boolean; + setText(text: string): void; + /** - * Enable or disable sending credentials along with each cross-domain request. Ignored if allowXdr is true and IE9 is being used - * - * @default `false` + * Add a class to this element. + * + * @param string className : The name of the class to add to the element */ - sendCredentials?: boolean; - } + addClass(className: string): void; - /** - * DeleteFileOptions - */ - interface DeleteFileOptions { /** - * Any additional headers to attach to all delete file requests - * - * @default `{}` + * Add CSS style(s) to this element. + * + * @param Object styles : An object with styles to apply to this element + * @returns Object : Returns the current context to allow method chaining */ - customHeaders?: any; + css(styles: any): this; + /** - * Enable or disable deletion of uploaded files - * - * @default `false` + * Returns an array of all descendants of this element that contain a specific class name. + * + * @param string className : The name of the class to look for in each element + * @returns HTMLElement[] : An array of `HTMLElements */ - enabled?: boolean; + getByClass(className: string): HTMLElement[]; + /** - * The endpoint to which delete file requests are sent. - * - * @default `'/server/upload'` + * Returns `true` if the element has the class name + * + * @param string className : The name of the class to look for in each element + * @returns boolean : Result of the `hasClass` test */ - endpoint?: string; + hasClass(className: string): boolean; + /** - * Set the method to use for delete requests. - * - * Accepts `'POST'` or `'DELETE'` - * - * @default `'DELETE'` + * Hide this element. + * + * @returns Object : Returns the current context to allow method chaining */ - method?: string; + hide(): this; + /** - * Any additional parameters to attach to delete file requests - * - * @default `{}` + * Remove the provided class from the element. + * + * @param string className : The name of the class to look for in each element + * @returns Object : Returns the current context to allow method chaining */ - params?: any; - } + removeClass(className: string): this; - /** - * ExtraButtonsOptions - */ - interface ExtraButtonsOptions { /** - * The container element for the upload button - * - * @default `undefined` + * Attach an event handler to this element for a specific DOM event. + * + * @param string event : A valid `DOM Event` + * @param function handler : A function that will be invoked whenever the respective event occurs + * @returns function : Call this function to detach the event */ - element: HTMLElement; + attach(event: string, handler: () => any | void): () => any | void; + /** - * This value will be used when creating the `title` attribute for the underlying ``. - * - * If not provided, the `text.fileInputTitle` option will be used instead - * - * @default `'file input'` + * Detach an already attached event handler from this element for a specific DOM event + * + * @param string event : A valid `DOM Event` + * @param function originalHandler : A function that will be detached from this event + * @returns Object : Call this function to detach the event */ - fileInputTitle?: string; + detach(event: string, originalHandler: () => any | void): this; + /** - * `true` to allow folders to be selected, `false` to allow files to be selected. - * - * @default `false` + * Shim for `Function.prototype.bind` + * + * Creates a new function that, when called, has its `this` keyword set to the provided context. + * Pass comma-separated values after the `context` parameter for all arguments to be passed into the new function (when invoked). + * You can still pass in additional arguments during invocation. + * + * @param function oldFunc : The function that will be bound to + * @param Object context : The context the function will assume + * @returns function : A new function, same as the old one, but bound to the passed in `context` */ - folders?: boolean; + bind(oldFunc: () => any | void, context: any): () => any; + /** - * Specify to override the default `multiple` value - * - * @default `true` + * Iterates through a collection, passing the key and value into the provided callback. `return false;` to stop iteration. + * + * @param Array or Object : + * @param function callback : A function that will be called for each item returned by looping through the iterable. This function takes an index and an item. */ - multiple?: boolean; + each(iterable: any[] | any, callback: (index: number, item: any) => any | void): () => any | void; + /** - * Specify to override the default `validation` option specified. - * - * Any `validation` properties not specified will be inherited from the default `validation` option - * - * @default `validation` + * Shallowly copies the parameters of secondobj to firstobj. if extendnested is true then a deep-copy is performed. + * + * @param Object firstObj : The object to copy parameters to + * @param Object secondObj : The object to copy parameters from + * @param boolean extendNested : If `true` then a deep-copy is performed, else a shallow copy + * @returns Object : The new object created by the extension */ - validation?: any; - } + extend(firstObj: any, secondObj: any, extendNested?: boolean): any; - /** - * FormOptions - */ - interface FormOptions { /** - * This can be the ID of the or a reference to the element - * - * @default `'qq-form'` + * Returns a string, swapping argument values with the associated occurrence of `{}` in the passed string + * + * @param string message : the string to be formatted + * @returns string : the formatted string */ - element?: string | HTMLElement; + format(message: string): string; + /** - * If Fine Uploader is able to attach to a form, this value takes the place of the base `autoUpload` option - * - * @default `false` + * Return the extension for the filename, if any + * + * @param string filename : The file's name to rip the extension off of + * @returns string : The extension name */ - autoUpload?: boolean; + getExtension(filename: string): string; + /** - * Set this to `false` if you do not want Fine Uploader to intercept attempts to submit your form. - * - * By default, Fine Uploader will intercept submit attempts and instead upload all submitted files, including data from your form in each upload request - * - * @default `true` + * Returns a version4 uuid + * + * @returns string : A version 4 unique identifier */ - interceptSubmit?: boolean; - } + getUniqueId(): string; - /** - * Messages - */ - interface Messages { /** - * Text passed to the error event handler if a submitted item is zero bits - * - * @default `'{file} is empty, please select files again without it.'` + * Returns the index of `item` in the `Array` starting the search from `startingindex` + * + * @param any[] array : the array to search in + * @param Object item : the item to search for + * @param number startingIndex : the index to search from + * @returns number : The index of `item` in the array */ - emptyError?: string; + indexOf(array: any[], item: any, startingIndex?: number): number; + /** - * Text passed to the error event handler if an image is too tall - * - * @default `'Image is too tall.'` + * Check if the parameter is function + * + * @param Object func : The object to test + * @returns boolean : Whether the parameter is a function or not */ - maxHeightImageError?: string; + isFunction(func: any): boolean; + /** - * Text passed to the error event handler if an image is too wide - * - * @default `'Image is too wide.'` + * Check if the parameter is object + * + * @param Object obj : The thing to test + * @returns boolean : Whether the parameter is a object or not */ - maxWidthImageError?: string; + isObject(obj: any): boolean; + /** - * Text passed to the error event handler if an image is not tall enough - * - * @default `'Image is not tall enough.'` + * Check if the parameter is string + * + * @param Object str : The object to test + * @returns boolean : Whether the parameter is a string or not */ - minHeightImageError?: string; + isString(str: any): boolean; + /** - * Text passed to the error event handler if an image is not wide enough - * - * @default `'Image is not wide enough.'` + * Log a message to the console. no-op if console logging is not supported. shim for `console.log` + * + * @param string logMessage : The message to log + * @param string logLevel : The logging level, such as 'warn' and 'info'. If `null`, then 'info' is assumed */ - minWidthImageError?: string; + log(logMessage: string, logLevel?: string): void; + /** - * Text passed to the error event handler if the item is too small - * - * @default `'{file} is too small, minimum file size is {minSizeLimit}.'` + * Prevent the browser's default action on an event + * + * @param string event : The name of the default event to prevent */ - minSizeError?: string; + preventDefault(event: string): void; + /** - * Text passed to the error event handler if any empty array of items is submitted - * - * @default `'No files to upload.'` + * Creates and returns a new
element + * + * @param string str : Valid HTML that can be parsed by a browser. + * @returns HTMLElement : An newly created `HTMLElement` from the input */ - noFilesError?: string; + toElement(str: string): HTMLElement; + /** - * Text displayed to the user when they attempt to leave the page while uploads are still in progress - * - * @default `'The files are being uploaded, if you leave now the upload will be canceled.'` + * Removes whitespace from the ends of a string. Shim for `String.prototype.trim` + * + * @param string str : The string to remove whitespace from + * @returns string : The new string sans whitespace */ - onLeave?: string; + trimstr(str: string): string; + + + /* ====================================== END - UTILITY METHODS ================================= */ + + + } + + /* ====================================== Misc Options and Wrappers ==================================== */ + + /** + * Callback type for `customResizer` parameter + */ + export interface CustomResizerCallBack { /** - * Text passed to the error event handler if a retry attempt is declared a failed due to a violation of the `validation.itemLimit` rule - * - * @default `'Retry failed - you have reached your file limit.'` + * Contribute this function to manually resize images using alternate 3rd party libraries + * + * @param ResizeInfo resizeInfo : the ResizeInfo object containing all the resize values/options + * @returns Promise : Once the resize is complete, the function must return a promise */ - retryFailTooManyItemsError?: string; + (resizeInfo: ResizeInfo): PromiseOptions; + } + + /** + * The FineUploader namespace contains all the methods, options, events and types + + /* ========================================================== CORE & UI ===================================================================== */ + /** + * type for `resizeInfo` object + */ + export interface ResizeInfo { /** - * Text passed to the error event handler if a submitted item is too large. - * - * @default `'{file} is too large, maximum file size is {sizeLimit}.'` + * The original `File` or `Blob` object, if available. */ - sizeError?: string; + blob?: File | Blob; /** - * Text passed to the error event handler if a submit is ignored due to a violation of the `validation.itemLimit` rules - * - * @default `'Too many items ({netItems}) would be uploaded. Item limit is {itemLimit}.'` + * Desired height of the image after the resize operation. */ - tooManyItemsError?: string; + height?: number; /** - * Text passed to the error event handler if an invalid file type is detected - * - * @default `'{file} has an invalid extension. Valid extension(s): {extensions}.'` + * The original HTMLImageElement object, if available. */ - typeError?: string; + image?: HTMLImageElement; /** - * Message displayed if the browser is iOS8 Safari and the corresponding workarounds option is not disabled - * - * @default `'Unrecoverable error - this browser does not permit file uploading of any kind due to serious bugs in iOS8 Safari. Please use iOS8 Chrome until Apple fixes these issues.'` + * `HTMLCanvasElement` element containing the original image data (not resized). */ - unsupportedBrowserIos8Safari?: string; - } - - /** - * PasteOptions - */ - interface PasteOptions { + sourceCanvas?: HTMLCanvasElement; /** - * The default name given to pasted images - * - * @default `'pasted_image'` + * `HTMLCanvasElement` element containing the `HTMLCanvasElement` that should contain the resized image. */ - defaultName?: string; + targetCanvas?: HTMLCanvasElement; /** - * Enable this feature by providing any HTMLElement here - * - * @default `null` + * Desired width of the image after the resize operation. */ - targetElement?: HTMLElement; + width?: number; } + /** - * ResumeOptions + * type for getUploads method's filter parameter */ - interface ResumeOptions { + export interface UploadFilter { /** - * The number of days before a persistent resume record will expire - * - * @default `7` + * the id of the file */ - recordsExpireIn?: number; + id?: number | number[]; /** - * Enable or disable the ability to resume failed or stopped chunked uploads - * - * @default `false` + * the uuid of the file */ - enabled?: boolean; + uuid?: number | number[]; /** - * paramNames.resuming - Sent with the first request of the resume with a value of `true`. - * - * @default `'qqresume'` + * status of the file */ - paramNames?: ParamNamesOptions; + status?: string | string[]; } /** - * RetryOptions + * type for getUploads method's return object */ - interface RetryOptions { + export interface FoundUploadItems extends UploadFilter { /** - * The number of seconds to wait between auto retry attempts - * - * @default `5` - */ - autoAttemptDelay?: number; - /** - * Enable or disable retrying uploads that receive any error response - * - * @default `false` - */ - enableAuto?: boolean; - /** - * The maximum number of times to attempt to retry a failed upload - * - * @default `3` + * the name of the file */ - maxAutoAttempts?: number; + name?: string; /** - * This property will be looked for in the server response and, if found and `true`, will indicate that no more retries should be attempted for this item - * - * @default `'preventRetry'` + * the size of the file */ - preventRetryResponseProperty?: string; + size?: string; } /** - * RequestOptions + * ScaleImageOptions */ - interface RequestOptions { + export interface ScaleImageOptions { /** - * Additional headers sent along with each upload request + * required */ - customHeaders?: any; + maxSize: number; /** - * The endpoint to send upload requests to - * - * @default `'/server/upload'` + * @default `true` */ - endpoint?: string; + orient?: boolean; /** - * The name of the parameter passed if the original filename has been edited or a `Blob` is being sent - * - * @default `'qqfilename'` + * defaults to the type of the reference image */ - filenameParam?: string; + type?: string; /** - * Force all uploads to use multipart encoding - * - * @default `true` + * number between `0` and `100` + * + * @default `80` */ - forceMultipart?: boolean; + quality?: number; /** - * The attribute of the input element which will contain the file name. - * - * For non-multipart-encoded upload requests, this will be included as a parameter in the query string of the URI with a value equal to the file name - * - * @default `'qqfile'` + * @default `false` */ - inputName?: string; + includeExif?: boolean; /** - * Specify a method to use when sending files to a traditional endpoint. This option is ignored in older browsers (such as IE 9 and older) - * - * @default `'POST'` + * Ignored if the current browser does not support image previews. + * + * If you want to use an alternate library to resize the image, you must contribute a function for this option that returns a `Promise`. + * + * Once the resize is complete, your promise must be fulfilled. + * You may, of course, reject your returned `Promise` is the resize fails in some way. */ - method?: string; + customResizer?: CustomResizerCallBack; + } + + export interface PromiseOptions { /** - * The parameters that shall be sent with each upload request + * Register callbacks from success and failure. + * + * The promise instance that then is called on will pass any values into the provided callbacks. + * If success or failure have already occurred before these callbacks have been registered, then they will be called immediately after this call has been executed. + * Each subsequent call to then registers an additional set of callbacks. + * + * @param Function successCallback : The function to call when the promise is successfully fulfilled + * @param Function failureCallback : The function to call when the promise is unsuccessfully fulfilled + * @return PromiseOptions : An instance of a promise */ - params?: any; + then(successCallback: Function, failureCallback: Function): PromiseOptions; + /** - * Enable or disable sending parameters in the request body. - * - * If `false`, parameters are sent in the URL. - * Otherwise, parameters are sent in the request body - * - * @default `true` + * Register callbacks for success or failure. + * + * Invoked when the promise is fulfilled regardless of the result. + * The promise instance that done is called on will pass any values into the provided callback. + * Each call to done registers an additional set of callbacks + * + * @param Function callback : The function to call when the promise is fulfilled, successful or not. + * @return PromiseOptions : An instance of a promise */ - paramsInBody?: boolean; + done(callback: Function): PromiseOptions; + /** - * The name of the parameter the uniquely identifies each associated item. The value is a Level 4 UUID - * - * @default `'qquuid'` + * Call this on a promise to indicate success. + * The parameter values will depend on the situation. + * + * @param Object param : The value to pass to the promise's success handler. + * @return PromiseOptions : An instance of a promise */ - uuidName?: string; + success(param: any): PromiseOptions; + /** - * The name of the parameter passed that specifies the total file size in bytes - * - * @default `'qqtotalfilesize'` + * Call this on a promise to indicate failure. + * The parameter values will depend on the situation. + * + * @param Object param : The value to pass to the promise's failure handler. + * @return PromiseOptions : An instance of a promise */ - totalFileSizeName?: string; + failure(param: any): PromiseOptions; } /** - * SizeOptions + * A BlobWrapper object type */ - interface SizeOptions { - /** - * name property will be appended to the file name of the scaled file - */ - name?: string; + export interface BlobWrapper { /** - * maximum size + * the bytes of the `Blob` object being uploaded */ - maxSize?: number; + blob?: Blob; /** - * MIME type + * the name of the `Blob` */ - type?: string; + name?: string; } /** - * ScalingOptions + * A CanvasWrapper Object type */ - interface ScalingOptions { + export interface CanvasWrapper { /** - * Ignored if the current browser does not support image previews. - * - * If you want to use an alternate scaling library, you must contribute a function for this option that returns a Promise. - * Once the resize is complete, your promise must be fulfilled. You may, of course, reject your returned Promise is the resize fails in some way - * - * @default `undefined` - */ - customResizer?: CustomResizerCallBack; - /** - * A value between `1` and `100` that describes the requested quality of scaled images. - * - * Ignored unless the scaled image type target is `image/jpeg` - * - * @default `80` + * the `` to be converted to a file & then uploaded */ - defaultQuality?: number + canvas?: HTMLCanvasElement; /** - * Scaled images will assume this image type if you don't specify a specific type in your size object, or if the type specified in the size object is not valid. - * - * You generally should not use any value other than `image/jpeg` or `image/png` here. - * - * The default value of null will ensure the scaled image type is `PNG`, unless the original file is a `JPEG`, in which case the scaled file will also be a `JPEG`. - * The default is probably the safest option. - * - * @default `null` + * the name to assign to the created file */ - defaultType?: string; + name?: string; /** - * Text sent to your `complete` event handler as an `error` property of the `response` param if a scaled image could not be generated - * - * @default `'failed to scale'` + * `1`-`100` value indicating the desired quality of the converted file (only for `image/jpeg`) */ - failureText?: string; + quality?: number; /** - * Ensure the `EXIF` data from the reference image is inserted into the scaled image. Only applicable when both the reference and the target are type `image/jpeg` - * - * @default `false` + * MIME type of the file to create from this `` */ - includeExif?: boolean; + type?: MimeType; + } + + /** + * Resumable file object type + */ + export interface ResumableFileObject { /** - * Set this to `false` if you do not want scaled images to be re-oriented based on parsed `EXIF` data before they are uploaded - * - * @default `true` + * filename */ - orient?: boolean; + name?: string; /** - * Set this to `false` if you don't want to original file to be uploaded as well - * - * @default `true` + * the unique id */ - sendOriginal?: boolean; + uuid?: number; /** - * An array containing size objects that describe scaled versions of each submitted image that should be generated and uploaded - * - * @default `[]` + * the index of the part where the resume will start from */ - sizes?: SizeOptions; + partIdx?: number; } + + /* ====================================== Core Options ==================================== */ + /** - * SessionOptions + * Contains Core options */ - interface SessionOptions { + export interface CoreOptions { /** - * Any additional headers you would like included with the `GET` request sent to your server. Ignored in `IE9` and `IE8` if the endpoint is cross-origin - * - * @default `{}` + * Set to false if you want to be able to upload queued items later by calling the `uploadStoredFiles()` method + * + * @default `true` */ - customHeaders?: any; + autoUpload?: boolean; /** - * If non-null, Fine Uploader will send a `GET` request on startup to this endpoint, expecting a `JSON` response containing data about the initial file list to populate - * + * Specify an element to use as the 'select files' button. Cannot be a `