Skip to content

Home

Jump to bottom
Sagid edited this page Feb 19, 2018 · 7 revisions

smartuploader guide

Introduction

The library gives you only one method jQuery.fn.withDropZone which require 3 parameters as well.
The simplest examle of use may looks like

var result = $("`#file_input").withDropZone("#drop_zone", {
  url: '://example.com',
  action: {
    name: "image",
    params: {
      preview: true,
    }
  },
});
// ...
// in button click method
result.upload();
  • The 1st is always input which type is file.
  • The 2nd is drop zone in which user can drop their files.
  • The 3rd is some options for settings up. So it's the main argument you should know and the rest part is dedicated to it.

options parameter

Note: every callback in options has file input as this

Primitive options

  • multiUploading [Boolean: true]. Multiple (true) or single (false) queries

  • url [String] - common url where POST resuest performs (for specific url for each separate file see ajaxSettings)

  • ifWrongFile [String: "show"] should has one of the next values:

    • "show" - show all files (include not valid)
    • "nothing" - totally ignore if there's invalid file
    • "ignore" - ignore only wrong files
    • "error" - ignore and show some error (add error class to drop zone)

  • autoUpload [Boolean: false] uploads files when user drops (or select via file input) files, if it's true, and does nothing otherwise (mutable by result's value).

Validation

These options constraint files:

  • maxFileSize [Number: Number.Infinity]
  • fileNameMatcher [RegExp: /.*/]
  • fileMimeTypeMatcher [RegExp: /.*/]

Example:

// ...
maxFileSize: 5*1024*1024, // 5 mb
fileNameMatcher: /\.(png|gif|jp(e)?g)\Z/,
fileMimeTypeMatcher: /image\/\*/,
// ...

  • validateEach callback which should returns valid status file (true or false).
    Signature: function(fileIndex)

  • validateAll callback which should returns subarray of valid files.
    Signature: function(files)

Example:

// ...
validateEach: function(fileIndex){
  return this.files[fileIndex].name.length < 20   // too long file name
},
validateAll: function(files){
  if (files.length > 5)
    return files.slice(0, 5)  // too many files, upload only the first 5
  return files
},
// ...

Callbacks

  • uploadBegin emits before each file uploads
  • uploadEnd emits after each file finishes uploading
    Signature for both callback should be like this
    function(filename, fileIndex, blob) for multiple upload
    function(filenames, _, blobs) for single upload

  • Note: in case multiple upload off, these two will be called one by one

  • done emits after all files have been uploaded
    Signature: function(filenames)
  • wrapperForInvalidFile should return HTML as wrapper's child for each wrong file
    Signature: function(fileIndex)
    • Example:
//...
wrapperForInvalidFile: function(fileIndex) {
  return `<p>File: "${this.files[fileIndex].name}" doesn't support</p>`
},
// ...
  • action should be object or function that returns object with this signature
    {name: String, rename: String, params: {...}}
    • Where:
      • name is the name of action;
      • rename is function with signature function(filenameWithoutExt, ext, fileIndex), which should return string;
      • params is parameter for appropriate action;

Example for "image" action:

var actionObject = {
  name: "image",
  rename: function(filenameWithoutExt, ext, fileIndex) {
    return filenameWithoutExt + ext;   // ext includes "."
  },
  params: {
    preview: true,
    convertTo: { mimeType: "image/jpeg", maxWidth: 50, maxHeight: 50 }
  }
};

// ...
// for static object
action: actionObject
// ...
// for dynamic object
action: function(fileIndex){
  // here you can change that object or return new one
  return actionObject
}
// ...

  • ajaxSettings - smartuploader calls "jQuery.ajax(obj)", so you can change that "obj" as you want.
    More information https://api.jquery.com/jquery.ajax/

  • formData - before calling jQuery.ajax(obj), smartuploader creates data as FormData. It sets file input's name as a key and file (or blob) as a value. So you can override this behaviour by setting callback that returns FormData's object
    For example:

// ...
// for multiple upload
formData: function(fileIndex, blob, filename) {
  var formData = new FormData;
  formData.set("file", blob, filename);
  formData.set("user_id", "0");  // some extra data
  return formData
}
// ...
// for single upload
formData: function(blobs, filenames) {
  var formData = new FormData;
  for (var i = 0; i < blobs.length; i++)
    formData.append("files", blobs[i], filename[i]);
  formData.set("user_id", "0");  // some extra data
  return formData
}

Note: if there's no convert, file(s) comes instead of blob(s)

  • validateEach - see in validation section
  • validateAll - see in validation section

See more examples

From source https://github.com/kofon95/smartuploader/tree/master/examples

Introduction

Options parameter

More examples

Clone this wiki locally