-
-
Notifications
You must be signed in to change notification settings - Fork 3.3k
FAQ
I try to keep this FAQ as complete as possible. If you think that there is something missing, please contact me.
This is most likely due to the autoDiscover feature of Dropzone.
When Dropzone starts, it scans the whole document, and looks for elements with the dropzone
class. It then creates an instance of Dropzone for every element found. If you, later on, create a Dropzone instance yourself, you'll create a second Dropzone which causes this error.
So you can either:
- Turn off autoDiscover globally like this:
Dropzone.autoDiscover = false;
, or - Turn off autoDiscover of specific elements like this:
Dropzone.options.myAwesomeDropzone = false;
You don't have to create an instance of Dropzone programmatically in most situations! It's recommended to leave autoDiscover enabled, and configure your Dropzone in the
init
option of your configuration.
There is a maxFileSize
option in Dropzone which defaults to 256
(MB). Increase this to upload files bigger than that. If your files upload fine but aren't stored on the server, then it's due to your server configuration. Most servers limit the file upload size as well. Please check with the appropriate documentation.
There is a maxThumbnailFilesize
option in Dropzone which defaults to 10
(MB) to prevent the browser from downsizing images that are too big. Increase this to create thumbnails of bigger files.
At the moment there isn't a single event to do that, but you can listen to the complete
event, which fires every time a file completed uploading, and see if there are still files in the queue or being processed.
There is a queuecomplete
event now that fires when all files in the queue have been uploaded.
Very often you have to do some verification on the server to check if the file is actually valid. If you want Dropzone to display any error encountered on the server, all you have to do, is send back a proper HTTP status code in the range of 400 - 500.
In most frameworks those error codes are generated automatically when you send back an error to the client. In PHP (for example) you can set it with the header
command.
Dropzone will then know that the file upload was invalid, and will display the returned text as error message.
If the Content-Type of your response is text/plain
, you can just return the text without any further markup. If the Content-Type is application/json
, Dropzone will use the error
property of the provided object. Eg.: { "error": "File could not be saved." }
Starting with Dropzone version 3.5.0, there is an option that will handle all this for you: addRemoveLinks
. This will add an <a class="dz-remove">Remove file</a>
element to the file preview that will remove the file, and it will change to Cancel upload if the file is currently being uploaded (this will trigger a confirmation dialog).
You can change those sentences with the dictRemoveFile
, dictCancelUpload
and dictCancelUploadConfirmation
options.
If you still want to create the button yourself, you can do so like this:
<form action="/target-url" id="my-dropzone" class="dropzone"></form>
<script>
// myDropzone is the configuration for the element that has an id attribute
// with the value my-dropzone (or myDropzone)
Dropzone.options.myDropzone = {
init: function() {
this.on("addedfile", function(file) {
// Create the remove button
var removeButton = Dropzone.createElement("<button>Remove file</button>");
// Capture the Dropzone instance as closure.
var _this = this;
// Listen to the click event
removeButton.addEventListener("click", function(e) {
// Make sure the button click doesn't submit the form:
e.preventDefault();
e.stopPropagation();
// Remove the file preview.
_this.removeFile(file);
// If you want to the delete the file on the server as well,
// you can do the AJAX request here.
});
// Add the button to the file preview element.
file.previewElement.appendChild(removeButton);
});
}
};
</script>
If your Dropzone element is a <form>
element, all hidden input fields will automatically be submitted as POST data along with the file upload.
Example:
<form action="/" class="dropzone">
<input type="hidden" name="additionaldata" value="1" />
<!-- If you want control over the fallback form, just add it here: -->
<div class="fallback"> <!-- This div will be removed if the fallback is not necessary -->
<input type="file" name="youfilename" />
etc...
</div>
</form>
To use the information sent back from the server, use the success
event, like this:
Dropzone.options.myDropzone = {
init: function() {
this.on("success", function(file, responseText) {
// Handle the responseText here. For example, add the text to the preview element:
file.previewTemplate.appendChild(document.createTextNode(responseText));
});
}
};
Although there's no builtin functionality to do that, you can use Dropzone's default event handlers to your advantage.
The concept is, to create a mock file, and call the event handlers addedfile
and thumbnail
to draw the preview.
// Create the mock file:
var mockFile = { name: "Filename", size: 12345 };
// Call the default addedfile event handler
myDropzone.emit("addedfile", mockFile);
// And optionally show the thumbnail of the file:
myDropzone.emit("thumbnail", mockFile, "/image/url");
// Make sure that there is no progress bar, etc...
myDropzone.emit("complete", mockFile);
// If you use the maxFiles option, make sure you adjust it to the
// correct amount:
var existingFileCount = 1; // The number of files already uploaded
myDropzone.options.maxFiles = myDropzone.options.maxFiles - existingFileCount;
If you are unhappy with the way Dropzone asks a user if she wants to cancel or remove a file, and want to use some other way (e.g.: bootstrap's modal), you can simply overwrite the Dropzone.confirm
function.
// accepted and rejected are functions to be called whenever the user response
// has been received.
// rejected is not mandatory! So make sure to check if it exists before
// calling it. Do nothing if it doesn't.
Dropzone.confirm = function(question, accepted, rejected) {
// Do your thing, ask the user for confirmation or rejection, and call
// accepted() if the user accepts, or rejected() otherwise. Make
// sure that rejected is actually defined!
};
You're in luck! Starting with 3.7.0
Dropzone supports the maxFiles
option. Simply set it to the desired quantity and you're good to go. If you don't want the rejected files to be viewed, simply register for the maxfilesexceeded
event, and remove the file immediately:
myDropzone.on("maxfilesexceeded", function(file) { this.removeFile(file); });
If you want to provide a thumbnail for files other than images, you can, by emitting the thumbnail
event yourself.
myDropzone.on("addedfile", function(file) {
if (!file.type.match(/image.*/)) {
// This is not an image, so Dropzone doesn't create a thumbnail.
// Set a default thumbnail:
myDropzone.emit("thumbnail", file, "http://path/to/image");
// You could of course generate another image yourself here,
// and set it as a data url.
}
});
This is a bit tricky. The "problem" is, that the image dimensions are only known after the thumbnail
event fired, which could potentially happen after the file already uploaded since thumbnail creation is queued.
That's why the accept
function (which determines if the file should be rejected) is called before the dimensions are actually known.
Fortunately the accept function is asynchronous, and can "wait" for the thumbnail event. This is why you need to put the accept callback in the file
object so you can reference it after the thumbnail has been generated:
var maxImageWidth = 800,
maxImageHeight = 800;
Dropzone.options.myDropzone = {
// Make sure only images are accepted
acceptedFiles: "image/*",
init: function() {
// Register for the thumbnail callback.
// When the thumbnail is created the image dimensions are set.
this.on("thumbnail", function(file) {
// Do the dimension checks you want to do
if (file.width > maxImageWidth || file.height > maxImageHeight) {
file.rejectDimensions()
}
else {
file.acceptDimensions();
}
});
},
// Instead of directly accepting / rejecting the file, setup two
// functions on the file that can be called later to accept / reject
// the file.
accept: function(file, done) {
file.acceptDimensions = done;
file.rejectDimensions = function() { done("Invalid dimension."); };
// Of course you could also just put the `done` function in the file
// and call it either with or without error in the `thumbnail` event
// callback, but I think that this is cleaner.
}
};