JavaScript API — Upload dialog and panel
On this page
Upload dialog is a modal window on top of your page. It contains a set of tabs with different upload sources and file preview. Upload panel is the same thing, just in a non-modal form.
Open Upload dialog
You can use openDialog
to open a standalone upload dialog over your page:
var dialog = uploadcare.openDialog(files, tab, settings);
javascript
Where,
files
, a file, file array or group that will be shown as already uploaded.tab
, a name of a tab opened by default when no predefined files are present.settings
, a settings object.
Open Upload panel
openPanel
is used to open an upload panel at any point on your page:
var panel = uploadcare.openPanel(container, files, tab, settings);
javascript
Where,
container
, a selector or DOM element that will be replaced with an upload panel. This will be put back on your panel resolving.files
, a file, file array or group that will be shown as already uploaded.tab
, a name of a tab opened by default when no predefined files are present.settings
, settings object.
Dialog API
Both dialog and panel instances implement the extended jQuery promise interface showing progress on a user tab.
dialog.done(function(result) {
// Dialog closed and a file or file group is selected.
});
dialog.fail(function(result) {
// Dialog closed and no file or file group was selected.
// The result argument is either null or the last selected file.
});
dialog.always(function() {
// Handles a closing dialog regardless of whether or not files were selected.
});
dialog.progress(function(tabName) {
// tabName is selected. progress() works when you click a tab name on the list.
// Technically, it would work on any dialog progress, i.e. when preview appears.
});
javascript
In addition to the jQuery promise interface, dialog and panel objects have the following properties and methods,
Property | Type | Description |
---|---|---|
| method | Resolve a dialog with currently selected files. |
| method | Close the dialog and discard any file selection. |
| method | Add an array of files to your dialog result set.
Accepts file instance array
or the same arguments as |
| method | Switch your dialog to a tab with a provided name.
The name you provide should be present in the |
| FileCollection | A collection of selected files. Use it to subscribe and change events. See FileCollection API. |
| method | Hide a tab with a provided name. |
| method | Show a tab with a provided name. |
| method | Inquire if a tab with a provided name is visible. |
| callback | Register a callback that will be called when tab visibility gets changed. “hideTab()” and “showTab()” provide tab visibility changes. Another example of changing visibility would be Preview Tab. | The first argument stands for the tab name, and the second is a boolean related to tab visibility. |
You can find code examples for solving typical tasks like a Check if a file was added or removed when working with the File Uploader in the instruction JS code snippets and CSS tricks.
You can find more customization examples here.
FileCollection API
Property | Type | Desciption |
---|---|---|
| Fired when file uploading done. | |
| Fired when file uploading failed. | |
| Fired on file uploading progress tick. | |
| Fired when file added. | |
| Fired when file removed. | |
| Fired when file is replaced with another one. | |
| Fired on files sort. | |
| callback | Add callback to the |
| callback | Add callback to the |
| callback | Add callback to the |
| method | Get array of progresses for all files in the collection. |
| method | Add file to the collection. |
| method | Remove file from the collection. |
| method | Remove all files from the collection. |
| method | Replace file with another one. |
| method | Sort files using given comparator. |
| method | Get file by index. |
| method | Get files count. |