From ed672aaf7c24047b6925c4674a3ca4bb12bd778f Mon Sep 17 00:00:00 2001 From: Sukhdeep Singh Date: Tue, 25 Jul 2017 21:33:04 -0400 Subject: [PATCH] Revert "Updated Typescript to support canonical imports (#1840)" This reverts commit ab1829c3a405cc46b2b2afdf69345866cc31d378. --- client/typescript/fine-uploader.d.ts | 5206 +++++++++++------------ client/typescript/fine-uploader.test.ts | 39 +- docs/features/modules.jmd | 52 +- 3 files changed, 2540 insertions(+), 2757 deletions(-) diff --git a/client/typescript/fine-uploader.d.ts b/client/typescript/fine-uploader.d.ts index 27bfc8655..011a6bddc 100644 --- a/client/typescript/fine-uploader.d.ts +++ b/client/typescript/fine-uploader.d.ts @@ -2,2300 +2,2973 @@ // Project: http://fineuploader.com/ // Definitions by: Sukhdeep Singh +/** + * The FineUploader namespace contains all the methods, options, events and types + */ +declare namespace FineUploader { -declare module "fine-uploader/lib/core" { - - - export class FineUploaderBasic { - + /* ========================================================== CORE & UI ===================================================================== */ + /** + * type for `resizeInfo` object + */ + interface ResizeInfo { /** - * The FineUploader Core only constructor + * The original `File` or `Blob` object, if available. */ - constructor(fineuploaderOptions?: CoreOptions); - + blob?: File | Blob; /** - * FineUploader's Promise implementation + * Desired height of the image after the resize operation. */ - Promise(): void; - + height?: number; /** - * 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 + * The original HTMLImageElement object, if available. */ - addFiles(files: File[] - | HTMLInputElement[] - | Blob[] - | BlobWrapper - | HTMLCanvasElement[] - | CanvasWrapper - | FileList, params?: any, endpoint?: string): void; - + image?: HTMLImageElement; /** - * Submit one or more canned/initial files to the uploader - * - * @param any[] initialFiles : An array of objects that describe files already on the server + * `HTMLCanvasElement` element containing the original image data (not resized). */ - addInitialFiles(initialFiles: any[]): void; - + sourceCanvas?: HTMLCanvasElement; /** - * Cancel the queued or currently uploading item which corresponds to the id - * - * @param number id : The file's id + * `HTMLCanvasElement` element containing the `HTMLCanvasElement` that should contain the resized image. */ - cancel(id: number): void; - + targetCanvas?: HTMLCanvasElement; /** - * Cancels all queued or currently uploading items + * Desired width of the image after the resize operation. */ - cancelAll(): void; + width?: number; + } + /** + * Callback type for `customResizer` parameter + */ + interface CustomResizerCallBack { /** - * Clears the internal list of stored items. Only applies when autoUpload is false + * 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 */ - clearStoredFiles(): void; + (resizeInfo: ResizeInfo): PromiseOptions; + } + /** + * A BlobWrapper object type + */ + interface BlobWrapper { /** - * Attempts to continue a paused upload - * - * @param number id : A file id - * @returns boolean : `true` if attempt was successful. + * the bytes of the `Blob` object being uploaded */ - continueUpload(id: number): boolean; - + blob?: Blob; /** - * Send a delete request to the server for the corresponding file id - * - * @param number id : The file's id + * the name of the `Blob` */ - deleteFile(id: number): void; + name?: string; + } + /** + * A CanvasWrapper Object type + */ + interface CanvasWrapper { /** - * 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. + * the `` to be converted to a file & then uploaded */ - drawThumbnail(id: number, targetContainer: HTMLElement, maxSize?: number, fromServer?: boolean, customResizer?: CustomResizerCallBack): PromiseOptions; - + canvas?: HTMLCanvasElement; /** - * 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. + * the name to assign to the created file */ - getButton(id: number): HTMLElement; - + name?: string; /** - * 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 + * `1`-`100` value indicating the desired quality of the converted file (only for `image/jpeg`) */ - getFile(id: number): File | Blob; - + quality?: number; /** - * 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). + * MIME type of the file to create from this `` */ - getEndpoint(id?: number): string | string[]; + type?: MimeType; + } + /** + * Resumable file object type + */ + interface ResumableFileObject { /** - * 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 + * filename */ - getInProgress(): number; - + name?: string; /** - * 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. + * the unique id */ - getName(id: number): string; - + uuid?: number; /** - * 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 + * the index of the part where the resume will start from */ - getNetUploads(): number; + partIdx?: number; + } + /** + * Resumable file object type for S3 + */ + interface S3ResumableFileObject extends ResumableFileObject { /** - * 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 + * The associated object's S3 key */ - getParentId(scaledFileId: number): number; + key?: string; + } + /** + * Resumable file object type for Azure + */ + interface AzureResumableFileObject extends ResumableFileObject { /** - * Returns the number of remaining allowed items that may be submitted for upload based on `validation.itemLimit`. + * The associated file's blob name in Azure Blob Storage */ - getRemainingAllowedItems(): number; + key?: string; + } + /** + * type for getUploads method's filter parameter + */ + interface UploadFilter { /** - * Returns an array of potentially resumable items - * - * @returns ResumableFileObject[] : An array of resumable items + * the id of the file */ - getResumableFilesData(): ResumableFileObject[] | ResumableFileObject; - + id?: number | number[]; /** - * 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 + * the uuid of the file */ - getSize(id: number): number; - + uuid?: number | number[]; /** - * 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 of the file */ - getUploads(filter?: UploadFilter): FoundUploadItems | FoundUploadItems[]; + status?: string | string[]; + } + /** + * type for getUploads method's return object + */ + interface FoundUploadItems extends UploadFilter { /** - * 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 + * the name of the file */ - getUuid(id: number): string; - + name?: string; /** - * 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 + * the size of the file */ - log(message: string, level?: string): void; + size?: string; + } + /** + * ScaleImageOptions + */ + interface ScaleImageOptions { /** - * Attempts to pause an in-progress upload - * - * @param number id : The file id - * @returns boolean : `true` if the attempt was successful. `false` otherwise + * required */ - pauseUpload(id: number): boolean; - + maxSize: number; /** - * 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. + * @default `true` */ - removeFileRef(id: number): void; - + orient?: boolean; /** - * Reset Fine Uploader + * defaults to the type of the reference image */ - reset(): void; - + type?: string; /** - * Attempt to upload a specific item again - * - * @param number id : The file id + * number between `0` and `100` + * + * @default `80` */ - retry(id: number): void; - + quality?: number; /** - * 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 + * @default `false` */ - scaleImage(id: number, options: ScaleImageOptions): PromiseOptions; - + includeExif?: boolean; /** - * 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 + * 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. */ - setCustomHeaders(customHeaders: any, id?: number): void; + customResizer?: CustomResizerCallBack; + } - /** - * 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 - */ - setEndpoint(path: string, identifier?: number | HTMLElement): void; + /** + * formatFileName function type + */ + interface FormatFileNameFuncton { + (fileOrBlobName: string): String | void; + } + /** + * BlobsOptions + */ + interface BlobsOptions { /** - * 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 + * The default name to be used for nameless `Blob`s + * + * @default `Misc data` */ - setDeleteFileCustomHeaders(customHeaders: any, id?: number): void; + defaultName?: string; + } + /** + * CameraOptions + */ + interface CameraOptions { /** - * 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 + * `null` allows camera access on the default button in iOS. + * + * Otherwise provide an extra button container element to target + * + * @default `null` */ - setDeleteFileEndpoint(path: string, identifier?: number | HTMLElement): void; - + button?: HTMLElement; /** - * 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 + * Enable or disable camera access on iOS (iPod, iPhone, and iPad) devices. + * + * ###Note: + * Enabling this will disable multiple file selection + * + * @default `false` */ - setDeleteFileParams(params: any, id?: number): void; + ios?: boolean; + } + /** + * ConcurrentOptions + */ + interface ConcurrentOptions { /** - * Change the `validation.itemLimit` option set during construction/initialization - * - * @param number newItemLimit : The new file count limit + * Allow multiple chunks to be uploaded simultaneously per file + * + * @default `false` */ - setItemLimit(newItemLimit: number): void; + enabled?: boolean; + } + /** + * ChunkingOptions + */ + interface ChunkingOptions { /** - * Bind a `
` to Fine Uploader dynamically - * - * @param HTMLFormElement | string formElementOrId : A form element or a form element's ID + * concurrent Chunking options */ - setForm(formElementOrId: HTMLFormElement | string): void; - + concurrent?: ConcurrentOptions; /** - * Change the name of a file - * - * @param number id: The file id - * @param string name : The new file name + * Enable or disable splitting the file separate chunks. Each chunks is sent in a separate requested + * + * @default `false` */ - setName(id: number, name: string): void; - + enabled?: boolean; /** - * 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 + * 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` */ - setParams(params: any, id?: number): void; - + mandatory?: boolean; /** - * 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. + * The maximum size of each chunk, in bytes + * + * @default `2000000` */ - setStatus(id: number, newStatus: string): void; - + partSize?: number; /** - * Change the UUID of a file - * - * @param number id : The file id - * @param string uuid : The new file UUID + * ParamNamesOptions */ - setUuid(id: number, uuid: string): void; - + paramNames?: ParamNamesOptions; /** - * Begin uploading all queued items. Throws a `NoFilesError` if there are no items to upload + * SuccessOptions */ - uploadStoredFiles(): void; - - - /* ====================================== UTILITY METHODS ======================================= */ + success?: SuccessOptions; + } + /** + * ParamNamesOptions + */ + interface ParamNamesOptions { /** - * 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 + * Name of the parameter passed with a chunked request that specifies the size in bytes of the associated chunk + * + * @default `'qqchunksize'` */ - children(element: HTMLElement): HTMLElement[]; - + chunkSize?: string; /** - * 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 + * Name of the parameter passed with a chunked request that specifies the starting byte of the associated chunk + * + * @default `'qqpartbyteoffset'` */ - contains(element: HTMLElement): boolean; - + partByteOffset?: string; /** - * 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 + * Name of the parameter passed with a chunked request that specifies the index of the associated partition + * + * @default `'qqpartindex'` */ - hasAttribute(attributeName: string): boolean; - + partIndex?: string; /** - * Clears all text for this element + * Name of the parameter passed with a chunked request that specifies the total number of chunks associated with the `File` or `Blob` + * + * @default `'qqtotalparts'` */ - clearText(): void; - + totalParts?: string; /** - * Inserts the element directly before the passed element in the DOM. - * - * @param HTMLElement element : the `element` before which an element has to be inserted + * Sent with the first request of the resume with a value of `true` + * + * @default `'qqresume'` */ - insertBefore(element: HTMLElement): void; - + resuming?: string; /** - * Removes the element from the DOM. + * totalFileSize + * + * @default `'qqtotalfilesize'` */ - remove(): void; + totalFileSize?: string; + } + /** + * SuccessOptions + */ + interface SuccessOptions { /** - * Sets the inner text for this element. - * - * @param string text : The text to set + * 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` */ - setText(text: string): void; + endpoint?: string; + } + /** + * CorsOptions + */ + interface CorsOptions { /** - * Add a class to this element. - * - * @param string className : The name of the class to add to the element + * Enable or disable cross-origin requests from IE9 and older where XDomainRequest must be used + * + * @default `false` */ - addClass(className: string): void; - + allowXdr?: boolean; /** - * 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 + * Enable or disable cross-domain requests + * + * @default `false` */ - css(styles: any): this; - + expected?: boolean; /** - * 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 + * Enable or disable sending credentials along with each cross-domain request. Ignored if allowXdr is true and IE9 is being used + * + * @default `false` */ - getByClass(className: string): HTMLElement[]; + sendCredentials?: boolean; + } + /** + * DeleteFileOptions + */ + interface DeleteFileOptions { /** - * 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 + * Any additional headers to attach to all delete file requests + * + * @default `{}` */ - hasClass(className: string): boolean; - + customHeaders?: any; /** - * Hide this element. - * - * @returns Object : Returns the current context to allow method chaining + * Enable or disable deletion of uploaded files + * + * @default `false` */ - hide(): this; - + enabled?: boolean; /** - * 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 + * The endpoint to which delete file requests are sent. + * + * @default `'/server/upload'` */ - removeClass(className: string): this; - + endpoint?: string; /** - * 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 + * Set the method to use for delete requests. + * + * Accepts `'POST'` or `'DELETE'` + * + * @default `'DELETE'` */ - attach(event: string, handler: () => any | void): () => any | void; - + method?: string; /** - * 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 + * Any additional parameters to attach to delete file requests + * + * @default `{}` */ - detach(event: string, originalHandler: () => any | void): this; + params?: any; + } + /** + * ExtraButtonsOptions + */ + interface ExtraButtonsOptions { /** - * 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` + * The container element for the upload button + * + * @default `undefined` */ - bind(oldFunc: () => any | void, context: any): () => any; - + element: HTMLElement; /** - * 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. + * 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'` */ - each(iterable: any[] | any, callback: (index: number, item: any) => any | void): () => any | void; - + fileInputTitle?: string; /** - * 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 + * `true` to allow folders to be selected, `false` to allow files to be selected. + * + * @default `false` */ - extend(firstObj: any, secondObj: any, extendNested?: boolean): any; - + folders?: boolean; /** - * 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 + * Specify to override the default `multiple` value + * + * @default `true` */ - format(message: string): string; - + multiple?: boolean; /** - * 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 + * Specify to override the default `validation` option specified. + * + * Any `validation` properties not specified will be inherited from the default `validation` option + * + * @default `validation` */ - getExtension(filename: string): string; + validation?: any; + } + /** + * FormOptions + */ + interface FormOptions { /** - * Returns a version4 uuid - * - * @returns string : A version 4 unique identifier + * This can be the ID of the or a reference to the element + * + * @default `'qq-form'` */ - getUniqueId(): string; - + element?: string | HTMLElement; /** - * 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 + * If Fine Uploader is able to attach to a form, this value takes the place of the base `autoUpload` option + * + * @default `false` */ - indexOf(array: any[], item: any, startingIndex?: number): number; - + autoUpload?: boolean; /** - * Check if the parameter is function - * - * @param Object func : The object to test - * @returns boolean : Whether the parameter is a function or not + * 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` */ - isFunction(func: any): boolean; + interceptSubmit?: boolean; + } + /** + * Messages + */ + interface Messages { /** - * Check if the parameter is object - * - * @param Object obj : The thing to test - * @returns boolean : Whether the parameter is a object or not + * Text passed to the error event handler if a submitted item is zero bits + * + * @default `'{file} is empty, please select files again without it.'` */ - isObject(obj: any): boolean; - + emptyError?: string; /** - * Check if the parameter is string - * - * @param Object str : The object to test - * @returns boolean : Whether the parameter is a string or not + * Text passed to the error event handler if an image is too tall + * + * @default `'Image is too tall.'` */ - isString(str: any): boolean; - + maxHeightImageError?: string; /** - * 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 + * Text passed to the error event handler if an image is too wide + * + * @default `'Image is too wide.'` */ - log(logMessage: string, logLevel?: string): void; - + maxWidthImageError?: string; /** - * Prevent the browser's default action on an event - * - * @param string event : The name of the default event to prevent + * Text passed to the error event handler if an image is not tall enough + * + * @default `'Image is not tall enough.'` */ - preventDefault(event: string): void; - + minHeightImageError?: string; /** - * 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 + * Text passed to the error event handler if an image is not wide enough + * + * @default `'Image is not wide enough.'` */ - toElement(str: string): HTMLElement; - + minWidthImageError?: string; /** - * 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 + * Text passed to the error event handler if the item is too small + * + * @default `'{file} is too small, minimum file size is {minSizeLimit}.'` */ - trimstr(str: string): string; - - - /* ====================================== END - UTILITY METHODS ================================= */ - - - } - - /* ====================================== Misc Options and Wrappers ==================================== */ - - /** - * Callback type for `customResizer` parameter - */ - export interface CustomResizerCallBack { + minSizeError?: string; /** - * 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 + * Text passed to the error event handler if any empty array of items is submitted + * + * @default `'No files to upload.'` */ - (resizeInfo: ResizeInfo): PromiseOptions; - } - - /** - * The FineUploader namespace contains all the methods, options, events and types - - /* ========================================================== CORE & UI ===================================================================== */ - /** - * type for `resizeInfo` object - */ - export interface ResizeInfo { + noFilesError?: string; /** - * The original `File` or `Blob` object, if available. + * 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.'` */ - blob?: File | Blob; + onLeave?: string; /** - * Desired height of the image after the resize operation. + * 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.'` */ - height?: number; + retryFailTooManyItemsError?: string; /** - * The original HTMLImageElement object, if available. + * Text passed to the error event handler if a submitted item is too large. + * + * @default `'{file} is too large, maximum file size is {sizeLimit}.'` */ - image?: HTMLImageElement; + sizeError?: string; /** - * `HTMLCanvasElement` element containing the original image data (not resized). + * 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}.'` */ - sourceCanvas?: HTMLCanvasElement; + tooManyItemsError?: string; /** - * `HTMLCanvasElement` element containing the `HTMLCanvasElement` that should contain the resized image. + * Text passed to the error event handler if an invalid file type is detected + * + * @default `'{file} has an invalid extension. Valid extension(s): {extensions}.'` */ - targetCanvas?: HTMLCanvasElement; + typeError?: string; /** - * Desired width of the image after the resize operation. + * 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.'` */ - width?: number; + unsupportedBrowserIos8Safari?: string; } + /** + * PasteOptions + */ + interface PasteOptions { + /** + * The default name given to pasted images + * + * @default `'pasted_image'` + */ + defaultName?: string; + /** + * Enable this feature by providing any HTMLElement here + * + * @default `null` + */ + targetElement?: HTMLElement; + } /** - * type for getUploads method's filter parameter + * ResumeOptions */ - export interface UploadFilter { + interface ResumeOptions { /** - * the id of the file + * The number of days before a persistent resume record will expire + * + * @default `7` */ - id?: number | number[]; + recordsExpireIn?: number; /** - * the uuid of the file + * Enable or disable the ability to resume failed or stopped chunked uploads + * + * @default `false` */ - uuid?: number | number[]; + enabled?: boolean; /** - * status of the file + * paramNames.resuming - Sent with the first request of the resume with a value of `true`. + * + * @default `'qqresume'` */ - status?: string | string[]; + paramNames?: ParamNamesOptions; } /** - * type for getUploads method's return object + * RetryOptions */ - export interface FoundUploadItems extends UploadFilter { + interface RetryOptions { /** - * the name of the file + * The number of seconds to wait between auto retry attempts + * + * @default `5` */ - name?: string; + autoAttemptDelay?: number; /** - * the size of the file + * Enable or disable retrying uploads that receive any error response + * + * @default `false` */ - size?: string; + enableAuto?: boolean; + /** + * The maximum number of times to attempt to retry a failed upload + * + * @default `3` + */ + maxAutoAttempts?: number; + /** + * 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'` + */ + preventRetryResponseProperty?: string; } /** - * ScaleImageOptions + * RequestOptions */ - export interface ScaleImageOptions { + interface RequestOptions { /** - * required + * Additional headers sent along with each upload request */ - maxSize: number; + customHeaders?: any; /** - * @default `true` + * The endpoint to send upload requests to + * + * @default `'/server/upload'` */ - orient?: boolean; + endpoint?: string; /** - * defaults to the type of the reference image + * The name of the parameter passed if the original filename has been edited or a `Blob` is being sent + * + * @default `'qqfilename'` */ - type?: string; + filenameParam?: string; /** - * number between `0` and `100` - * - * @default `80` + * Force all uploads to use multipart encoding + * + * @default `true` */ - quality?: number; + forceMultipart?: boolean; /** - * @default `false` + * 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'` */ - includeExif?: boolean; + inputName?: string; /** - * 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. + * 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'` */ - customResizer?: CustomResizerCallBack; - } - - export interface PromiseOptions { + method?: string; /** - * 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 + * The parameters that shall be sent with each upload request */ - then(successCallback: Function, failureCallback: Function): PromiseOptions; - + params?: any; /** - * 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 + * 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` */ - done(callback: Function): PromiseOptions; - + paramsInBody?: boolean; /** - * 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 + * The name of the parameter the uniquely identifies each associated item. The value is a Level 4 UUID + * + * @default `'qquuid'` */ - success(param: any): PromiseOptions; - + uuidName?: string; /** - * 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 + * The name of the parameter passed that specifies the total file size in bytes + * + * @default `'qqtotalfilesize'` */ - failure(param: any): PromiseOptions; + totalFileSizeName?: string; } /** - * A BlobWrapper object type + * SizeOptions */ - export interface BlobWrapper { + interface SizeOptions { /** - * the bytes of the `Blob` object being uploaded + * name property will be appended to the file name of the scaled file */ - blob?: Blob; + name?: string; /** - * the name of the `Blob` + * maximum size */ - name?: string; + maxSize?: number; + /** + * MIME type + */ + type?: string; } /** - * A CanvasWrapper Object type + * ScalingOptions */ - export interface CanvasWrapper { + interface ScalingOptions { /** - * the `` to be converted to a file & then uploaded - */ - canvas?: HTMLCanvasElement; + * 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; /** - * the name to assign to the created file + * 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` */ - name?: string; + defaultQuality?: number /** - * `1`-`100` value indicating the desired quality of the converted file (only for `image/jpeg`) + * 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` */ - quality?: number; + defaultType?: string; /** - * MIME type of the file to create from this `` + * 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'` */ - type?: MimeType; - } - - /** - * Resumable file object type - */ - export interface ResumableFileObject { + failureText?: string; /** - * filename + * 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` */ - name?: string; + includeExif?: boolean; /** - * the unique id + * 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` */ - uuid?: number; + orient?: boolean; /** - * the index of the part where the resume will start from + * Set this to `false` if you don't want to original file to be uploaded as well + * + * @default `true` */ - partIdx?: number; + sendOriginal?: boolean; + /** + * An array containing size objects that describe scaled versions of each submitted image that should be generated and uploaded + * + * @default `[]` + */ + sizes?: SizeOptions; } - - /* ====================================== Core Options ==================================== */ - /** - * Contains Core options + * SessionOptions */ - export interface CoreOptions { + interface SessionOptions { /** - * Set to false if you want to be able to upload queued items later by calling the `uploadStoredFiles()` method - * - * @default `true` + * 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 `{}` */ - autoUpload?: boolean; + customHeaders?: any; /** - * Specify an element to use as the 'select files' button. Cannot be a `