JavaScript / TypeScript API

Users of the JavaScript version of Uploader and owners of SaaS/OEM licenses can invoke the widget using Application Programming Interface (API). This way to invoke the widget well fits all non-standard cases when you need to invoke File Uploader not from a CKEditor plugin or another plugin, but from your own application or script on the website.

Please learn how to load a library, and then use this article as a guide on available API classes and methods.

Overview

The library contains a number of methods to invoke file selection, upload them and render. Many of them are merged into composite methods to make things more convenient for a programmer. This is to avoid callback hell.

Also, there are two classes that allow you to program absolutely arbitrary way to upload files to the server. Other uploading functions are merely convenient wrappings for these classes that are helpful to implement standard behaviours.

API methods table

Uploading files

All file uploading functions are asynchronous. This means that among other arguments they accept two callbacks: onOk and onFail.

The onOk receives control is uploading finished successfully. The parameter passed to this function depends on the type of the called API function. Specifically, functions with the "render" suffix will pass the ready HTML code to embed. Other functions will pass the ServerFile array of structure that will contain raw data about uploaded files (URL, size and so on). See the exact list of input parameters of the callback in the description of each particular function.

The onFail receives control if an error occurred on any step. This callback always accepts one input argument - the localized text of the error message.

The callback onSelected is called when a browser windows was opened to select files if the file selection was successful.

Quick uploading without opening the File Uploader dialog

The specifics of quick uploading is that a user cannot specify any settings for uploaded files during the uploading process - only select a list of files on his computer. Then, the files are uploaded using settings specified in the argument that has the Parameters type: the Preset will be taken from there using the name specified in presetName, and UserOptions will be default for the preset used.

fastSelectAndUploadAndRender(presetName: string, parameters: Parameters, onSelected: (files: File[]): void
Opens a browser file selection dialog, uploads files and generates HTML to embed.
fastSelectAndUpload(presetName: string, parameters: Parameters, onSelected: (files: File[]): void
Opens a browser file selection dialog, upload files and passes the list of structures ServerFile containing information about uploaded files as the only argument of the callback function `onOk`.
fastUploadAndRender(presetName: string, parameters: Parameters, files: File[], onOk: (html: string)
Loads the data passed as the argument to the server (without opening a browser file selection dialog), transforms uploaded files data to the HTML code based on a template, then passes it to the callback function callback `onOk`. The `file` parameter contains an array of `File` objects from the File API.
fastUpload(presetName: string, parameters: Parameters, files: File[], onOk: (files: ServerFile[]): void
Uploads the files passed as the argument to the server. The array of structures ServerFile is passed to the callback `onOk`.

For more in-depth control over the fast uploading process, use the UploaderFlow class. It allows you to modify uploader behaviour on every step.

Uploading files using the File Uploader dialog

Uploading files using the dialog allows doing the same as quick uploading except that the user now can visually control the uploading progress, specify a preset (among those you make available) and so on.

selectAndUploadAndRender(urlUploader: string, urlFiles: string, isMultiple: boolean, defaultPresetName: string, availablePresets: Preset[], onOk: (html: string): void
Displays a standard file selection browser dialog before opening the uploading dialog (the user can later add files from the File Uploader dialog too). The user can select one of available presets on the toolbar, and configure options for it. A string containing the HTML code to embed to the document is passed to the callback function. `urlFiles` is a URL prefix that specifies file location, it is needed for template rendering.
selectAndUpload(urlUploader: string, isMultiple: boolean, defaultPresetName: string, availablePresets: Preset[], onOk: (serverFiles: ServerFile[], preset: Preset): void
The same as above, but returns data before they are rendered as an array of structures ServerFile.
uploadAndRender(urlUploader: string, urlFiles: string, files: File[], isMultiple: boolean, defaultPresetName: string, availablePresets: Preset[], onOk: (html: string): void
Displays the File Uploader dialog omitting the file selection browser dialog. To continue uploading the user has to add files using the toolbar. `urlFiles` is a URL prefix that specifies file location, it is needed for template rendering Even though you specify the list of files in `files`, `isMultiple` still must be specified correctly: this is required because the user can add files in the dialog.
upload(urlUploader: string, files: File[], isMultiple: boolean, defaultPresetName: string, availablePresets: Preset[], onOk: (serverFiles: ServerFile[], preset: Preset): void
The same as above, but files are not rendered by template.

If flexibility of these standard API functions is not enough for your particular scenario, use the UploaderUiFlow class that allows you to control every step of dialog-based uploading. All functions above are just wrappings of this class for the most frequent cases.

Utility functions

selectFiles(isMultiple: boolean, acceptTypes: string, onSelected: (files: File[]): void
Shows a standard file selection browser dialog. If files are selected and "OK" is pressed, the control is passed to the `onSelected` callback. The `isMultiple` parameter allows or disallows uploading multiple files. The `acceptTypes` parameter defines permitted MIME types of files, `null` allows anything, `images/*` permits only images and so on. Actual effect of this function (especially regarding the allowed file types) greatly depends on the browser and the OS the user has.
renderFile(file: ServerFile, urlFiles: string, template: string): string
Generates and returns the HTML code that corresponds to the specified `file`. As a template, the `template` argument is used. Its value corresponds to the option of template in client settings, and so is for the urlFiles argument.
getDefaultUserOptions(preset: Preset): UserOptions
Returns the default user options for the given preset.

Message dialogs

For the sake of unification of the visual interface, File Uploader contains functions to display dialogs with messages. These functions are part of the Dialog subclass, and can be called like this: Dialog.showError(msg).

showError(msg: string): void
Displays an error message.
showWarning(msg: string): void
Displays a warning message.
showInfo(msg: string): void
Displays an information message.

Data structures

Below you will find descriptions of data structures used in File Uploader API. In fact, they are equivalent to settings described on the client configuration page except they are written in TypeScript/JavaScript. Please refer to the settings page to read a more detailed description of each key.

interface Parameters {
    urlUploader: string,
    urlFiles: string,
    presets: Preset[]
}

The object Parameters all main settings of File Uploader are passed in.

interface Preset {
    name: string,
    template: string,
    isImage: boolean,
    hasPreview: boolean,
    acceptTypes: string,
    userOptions: UserOptions
}

Preset is a set of settings applied to file uploading. If files are uploaded using the File Uploader dialog, the user can select one of presets available to him and change user settings specified in the userOptions field.

interface UserOptions {
    presetName?: string,
    files?: FileData[],
    autoRename: boolean,
    imageOptionsFull?: ImageOptions,
    imageOptionsPreview?: ImageOptions
}

UserOptions structure stores user settings for a preset. The user can change them if uploading using the File Uploader dialog is used. Otherwise the uploader uses the default user options for the given preset. Fields files and presetName are not described on the configuration page, because they are added in run-time only (you can process them in run time too by using the UploaderFlow and UploaderFlow classes.

interface FileData {
    name: string,
    newName?: string
}

FileData structure describes an uploaded file that the user decided to keep within the current uploading session. That is, a user can upload several files, but then change his mind and decide to not keep some of them while working with the dialog. In this case such files are not committed from the temporary directory to the destination directory.
If the user want to rename the file for commit, the newName field must be specified for the current file.
This structure is not described on the configuration page, because the default user options cannot describe renaming of specific uploaded files.

interface ImageOptions {
    width: number,
    height: number
    enlarge: boolean
}

ImageOptions contains information on how to scale uploaded images. This structure is used in imageOptionsFull and imageOptionsPreview fields of the UserOptions structure. width and height are target size of the image, enlarge is a flag that permits or forbids scaling up an image above its current resolution.

interface ServerFile {
    name: string;
    isCommited: boolean;
    dir: string;
    bytes: number;
    isImage: boolean;
    width: number;
    height: number;
    errors: string[];
    filePreview: ServerFile;
    fileOriginal: ServerFile;
}

ServerFile is a structure with data of any uploaded file: commited or not, with links to its original and preview.

Constants

defaultPresetImage: Preset
A set of options for image uploading.
defaultPresetPreview: Preset
A set of options for image uploading, preview generation and inserting a preview that links to the full-sized image.
defaultPresetFile: Preset
A set of options to upload arbitrary files.

Additionally

If you are a user of our product, and the described API is not enough to fulfil your needs, please let us know about this. If your suggestion matches our view of the product we will plan it for inclusion to the API in further enhancements.