JavaScript SDK (library)

The best way to use File Uploader in your own application is JavaScript library option. All users of the JavaScript version receives a special edition of File Uploader, that is different from other versions in that offers an API (Application Programming Interface) to invoke the widget. This allows you to invoke File Uploader from any place of your application, for example, you can bind File Uploader to the file selection button so that a user could specify a file by transparently uploading it the server.

The widget can be invoked using the API with various settings using various API methods.

Installing

Include the link to the script to the body of your HTML website (usually in the <head> section). For example:

<script src="/scripts/jsplus_file_uploader/uploader.js"></script>

Done. Now you can use the window.FileUploader that encapsulates all methods and classes of the API for file uploading, the uploader dialog invocation methods (only in Full edition) or generation of HTML code based on selected file and template, for instance:

window.FileUploader.someApiFunction(...);

Note that when you use this way to interact with the File Uploader, the window.FileUploader variable receives its value with a little delay compared to page loading. This is because the script is loaded asynchronously, and in your code you need to control if this variable is initialized already. In the nearest future, to make working with File Uploader API even more convenient, we plan to implement including using a module manager (like RequireJS).

Examples of use

All examples are written on TypeScript. It differs from JavaScript of the latest versions in that it has typing. Converting these examples to JavaScript is trivial.

Quick uploading of files

Quick uploading implies uploading of files bypassing the dialog: files are opened using the open file dialog, uploading goes without selecting options and selected images are embedded instantly (in this example - adding the HTML code to the existing content).

FileUploader.<a href="api#fastSelectAndUploadAndRender">fastSelectAndUploadAndRender</a>(
    'image', // use preset name
    {
        urlUploader: "http://mywebsite.com/scripts/jsplus_file_uploader/php/uploader.php",
        urlFiles: "http://mywebsite.com/images/",
        presets: [FileUploader.defaultPresetImage]
    },
    (file: File[]) => {
        // On files selected
    },
    (html: string) => {
        // On files commited and rendered by template of preset
        divContent.innerHTML += html;
    },
    (msg: string) => {
        // On error
        FileUploader.Dialog.showError(msg);
    }
)

If you already have links to File objects you need to upload (for example if you called the selectFiles function or if you have a field where a user specified those files), you can upload them to the server skipping the file selection step. Also, in this example you can process information on uploaded files without the built-in template.

FileUploader.fastUpload(
    'file', // use preset name
    {
        urlUploader: "http://mywebsite.com/scripts/jsplus_file_uploader/php/uploader.js",
        urlFiles: "http://mywebsite.com/images/",
        presets: [FileUploader.defaultPresetFile]
    },
    files,
    (files: ServerFile[]) => {
        // On files uploaded
        console.log("Uploaded " + files.length + " files");
        for (const i in files)
            console.log("File #" + i + ": " + files[i].getUrl());
    },
    (msg: string) => {
        // On error
        FileUploader.Dialog.showError(msg);
    }
)

Advanced upload management implies using event listeners on every step of uploading. You can use the UploaderFlow class to control the uploading process. If you overload this class and redefine some of its functions, you receive full control over the uploading process. In the end, the API functions discussed above use this method inside them, so they offer faster invocation for the cost of flexibility. And you can achieve full flexibility if you work with this class manually.

The below example shows how you can process data on various steps or if an error occurs (in fact, there are much more options, please refer to the UploaderFlow API class.

class MyUploaderFlow extends UploaderFlow {
    protected getUrlUploader(): string { return "http://mywebsite.com/scripts/jsplus_file_uploader/php/uploader.php"; }
    protected getFilesToUpload(): File[] { return null; }
    protected getPresetData(): Preset { return FileUploader.defaultPresetImage; }
    protected getUserOptionsData(): UserOptions { return FileUploader.getDefaultUserOptions(this.getPresetData()); }

    protected onAfterSelected() { 
        console.log("Files selected:");
        console.log(this.files); 
    }
    protected onAfterInit() { console.log("Upload ID: " + this.uploadId); }
    protected onAfterUpload() { 
        console.log("Files uploaded:");
        console.log(this.serverFilesUploaded); 
    }
    protected onAfterCommit() { 
        console.log("Files commited:");
        console.log(this.serverFilesCommited); 
    }
    protected onAnyFail() { console.log("Error: " +  this.errorMessage; }
}
let flow = new MyUploaderFlow();
flow.run();

Uploading using the dialog

In the File Uploader Full edition you can upload using a dialog that allows a user to add files, change settings, select a preset (from those you provided), rename uploaded files etc.

Selecting, uploading and embedding a set of arbitrary files using a preset (image by default):

FileUploader.selectAndUploadAndRender(
    "http://mywebsite.com/scripts/jsplus_file_uploader/php/uploader.php", // urlUploader
    "http://mywebsite.com/images/", // urlFiles
    true, // isMultiple
    'image', // defaultPresetName
    [
        FileUploader.defaultPresetImage,
        FileUploader.defaultPresetPreview,
        FileUploader.defaultPresetFile
    ], // availablePresets
    (html: string) => {
        // On files commited and rendered
        console.log(html);
    },
    (msg: string) => {
        // On error
        FileUploader.Dialog.showError(msg);
    }
);

Selecting and uploading images with some post-processing. Note that a user can select a preset in the dialog if you provided several presets. The chosen preset can be obtained in the onCommited event.

FileUploader.selectAndUpload(
    "http://mywebsite.com/scripts/jsplus_file_uploader/php/uploader.php", // urlUploader
    "http://mywebsite.com/images/",  // urlFiles
    true // isMultiple
    'image', // defaultPresetName
    [FileUploader.defaultPresetImage], // availablePresets
    (serverFiles: ServerFile[], preset: Preset) => {
        // On files commited
        console.log(preset);
        console.log(serverFiles);
    },
    (msg: string) => {
        // On error
        FileUploader.Dialog.showError(msg);
    }
);

A more advanced way to use this gives you control over each step: examine the UploaderUiFlow class inheriting, create your own class and invoke it. It is this class that the above functions are wrapping up. Any non-standard uploading option can be implemented using this way that provides for maximum flexibility to developers.

Let's say you want to control every step and all errors (that's not the entire list of possibilities, though). The following code should help:

class MyUploaderUiFlow extends UploaderUiFlow {
    protected getUrlUploader(): string { return "http://mywebsite.com/scripts/jsplus_file_uploader/php/uploader.php"; }
    protected getAvailablePresets(): PresetData[] {
        return [
            FileUploader.defaultPresetImage,
            FileUploader.defaultPresetPreview,
        ];
    }
    protected getDefaultPresetName(): string { return "image"; }
    protected getFilesToUpload(): File[] { return []; }
    protected doOpenSelectDialogOnStart(): boolean { return true; }
    protected isSelectMultiple(): boolean { return true; }
    protected getUrlUploader(): string { return "http://mywebsite.com/scripts/jsplus_file_uploader/php/uploader.php"; }

    protected onAfterSelected() { console.log(this.files); }
    protected onAfterInit() { console.log(this.uploadId); }
    protected onAfterCommited() { 
        console.log(this.preset); // preset selected by user
        console.log(this.serverFilesCommited); 
    }
    protected onAnyFail() { console.log(this.errorMessage); }
}
let flow = new MyUploaderUiFlow();
flow.run();

Various useful methods

Opening a standard open dialog to select a list of arbitrary files, then pass the list to your code (without actual uploading).

FileUploader.selectFiles(
    true, // isMultiple
    null, // acceptTypes
    (files: File[]) => {
        // On files selected
        console.log("Selected files:");
        console.log(files);
    }
);

Opening a standard open dialog to pick one image.

FileUploader.selectFiles(
    false, // isMultiple
    "image/*", // acceptTypes
    (files: File[]) => {
        // On files selected
        console.log("Selected file:");
        console.log(files);
    }
);

Just render an uploaded file. This method allows you after uploading files to transform them to HTML using your own template (or one of templates built into presets). In this example we use our own template.

let html = FileUploader.renderFile(files[0], parameters.urlFiles, '<a href="{URL}">{NAME}</a>');