Uploading Widget JavaScript API — Upload dialog and panel
On this page
- We’ve built the next version of the File Uploader.
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 Uploadign Widget in the instruction JS code snippets and CSS tricks.
Discover more customization examples.
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. |