{"id":13756470,"url":"https://github.com/danielm/uploader","last_synced_at":"2025-05-15T04:04:33.188Z","repository":{"id":13984941,"uuid":"16685880","full_name":"danielm/uploader","owner":"danielm","description":"A lightweight and very configurable jQuery plugin for file uploading using ajax(a sync); includes support for queues, progress tracking and drag and drop.","archived":false,"fork":false,"pushed_at":"2022-01-07T16:25:58.000Z","size":151,"stargazers_count":1169,"open_issues_count":50,"forks_count":382,"subscribers_count":73,"default_branch":"master","last_synced_at":"2025-05-14T04:11:12.547Z","etag":null,"topics":["ajax","dnd","drag","drop","file","forms","javascript","jquery","jquery-plugin","lightweight","multiple","progress","queue","upload","widget"],"latest_commit_sha":null,"homepage":"https://danielmg.org/demo/java-script/uploader","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/danielm.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-02-10T05:54:26.000Z","updated_at":"2025-05-08T13:30:14.000Z","dependencies_parsed_at":"2022-07-31T17:38:53.548Z","dependency_job_id":null,"html_url":"https://github.com/danielm/uploader","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielm%2Fuploader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielm%2Fuploader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielm%2Fuploader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielm%2Fuploader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/danielm","download_url":"https://codeload.github.com/danielm/uploader/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254109829,"owners_count":22016384,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ajax","dnd","drag","drop","file","forms","javascript","jquery","jquery-plugin","lightweight","multiple","progress","queue","upload","widget"],"created_at":"2024-08-03T11:00:44.941Z","updated_at":"2025-05-15T04:04:33.163Z","avatar_url":"https://github.com/danielm.png","language":"JavaScript","readme":"# jQuery Ajax File Uploader Widget\nA jQuery plugin for file uploading using ajax(a sync); includes support for queues, progress tracking and drag and drop.\n\nVery ***configurable*** and easy to adapt to any ***Frontend*** design, and very easy to work along side any backend logic.\n\nThe focus will be ***modern browsers***, but also providing a method to know when the plugin is not supported. The idea is to keep it simple and ***lightweight***.\n\nBasic Javascript knowledge is necessary to setup this plugin: how to set settings, callback events, etc.\n\n- Lightweight: ~8.00 KB \n- Dependencies: just jQuery!\n- License: Released under the [MIT license](LICENSE.txt)\n\n[![Build Status](https://travis-ci.org/danielm/uploader.svg?branch=master)](https://travis-ci.org/danielm/uploader)\n[![npm version](https://badge.fury.io/js/dm-file-uploader.svg)](http://badge.fury.io/js/dm-file-uploader)\n[![Bower version](https://badge.fury.io/bo/dm-file-uploader.svg)](http://badge.fury.io/bo/dm-file-uploader)\n\n## Live DEMOS\nCheck the live Demos here: https://danielmg.org/demo/java-script/uploader\n\n## Table of contents\n\n  * [Installation](#installation)\n  * [Migration from v0.x.x](#migration-from-v0xx)\n  * [Usage](#usage)\n    * [Markup](#example-markup)\n    * [Initialization](#initialization)\n  * [Options](#options)\n  * [Callbacks](#callbacks)\n  * [Methods](#methods)\n\n## Installation\n\n### NPM\n```bash\nnpm install dm-file-uploader --save\n```\n\n### Bower\n```bash\nbower install dm-file-uploader --save\n```\n\n### Download tarball\nYou can download the latest release tarball directly from [releases](https://github.com/danielm/uploader/releases)\n\n### Git\n```bash\ngit clone https://github.com/danielm/uploader.git\n```\n\n## Migration from v0.x.x\n1.x.x got a lot of changes and new features, if you are a previous version user read [CHANGELOG.md](CHANGELOG.md), there you can find the specific details of what was changed or removed.\n\n## Usage\nAs shown in the demos there are many ways to use the plugin, but the basic concepts are:\n- Initialize the plugin on any HTML element such as: \u003ccode\u003e`\u003cdiv /\u003e`\u003c/code\u003e to provide a Drag and drop area.\n- All \u003ccode\u003e`\u003cinput type=\"file\"/\u003e`\u003c/code\u003e inside the main area element will be bound too.\n- Optionally you can bind it directly to the \u003ccode\u003e`\u003cinput /\u003e`\u003c/code\u003e\n\n### Example Markup\nThis is the simple html markup. The file input is optional but it provides an alternative way to select files for the user(check the online demo to se how to hide/style it)\n```html\n\u003cdiv id=\"drop-area\"\u003e\n  \u003ch3\u003eDrag and Drop Files Here\u003ch3/\u003e\n  \u003cinput type=\"file\" title=\"Click to add Files\"\u003e\n\u003c/div\u003e\n```\n\n### Initialization\n```html\n   \u003cscript src=\"/path/to/jquery.dm-uploader.min.js\"\u003e\u003c/script\u003e\n```\n\n```javascript\n$(\"#drop-area\").dmUploader({\n  url: '/path/to/backend/upload.asp',\n  //... More settings here...\n  \n  onInit: function(){\n    console.log('Callback: Plugin initialized');\n  }\n  \n  // ... More callbacks\n});\n```\nDown below there is a detailed list of all available [Options](#options) and [Callbacks](#callbacks).\n\nAdditionally, after initialization you can use any of the available [Methods](#methods) to interact with the plugin.\n\n## Options\n * **queue**: (boolean) ``Default true`` Files will upload one by one.\n \n * **auto**: (boolean) ``Default true`` Files will start uploading right after they are added.\n   If using the ``queue`` system this option means the ``queue`` will start automatically after the first file is added.\n\n   Setting this to `false` will require you to manually start the uploads using the API [Methods](#methods).\n\n * **dnd**: (boolean) ``Default true`` Enables Drag and Drop.\n\n * **hookDocument**: (boolean) ``Default true`` Disables dropping files on $(document).\n\n   **This is necessary** to prevent the Browser from redirecting when dropping files.\n\n   The only reason why you may want to disable it is when using multiple instances of the plugin. If that's the case you only need to use it **once**.\n\n * **multiple**: (boolean) ``Default true`` Allows the user to select or drop multiple files at the same time.\n\n * **url**: (string) ``Default document.URL`` Server URL to handle file uploads (backend logic).\n\n * **method**: (string) ``Default POST`` HTTP method used by the upload request.\n\n * **extraData**: (object/function) Collection of parameters to add in the upload request.\n\n   ```javascript\n   // Example\n   extraData: {\n      \"galleryid\": 666\n   }\n   ```\n\n   If you need a dynamic value this can be set as a `function`. Also, if this function returns `false` nothing will be added.\n\n   ```javascript\n   // Example\n   extraData: function() {\n      return {\n        \"galleryid\": $('#gallery').val()\n      };\n   }\n   ```\n\n * **headers**: (object) Collection of headers to send in the upload request.\n\n   ```javascript\n   // Example\n   headers: {\n      'X-CSRF-TOKEN': $('meta[name=\"csrf-token\"]').attr('content')\n   }\n   ```\n\n * **dataType**: (string) ``Default null`` Response type of the upload request.\n\n   Default is `null` which means jQuery will try to 'guess' depending of what the server returns.\n\n   Other values can be: `xml`, `json`, `script`, `html` or `text`\n\n   Reference: http://api.jquery.com/jquery.ajax/\n\n * **fieldName**: (string) ``Default 'file'`` Field name in the upload request where we 'attach' the file.\n\n   ```php\n   // For example in PHP if using the default value you can access the file by using:\n   var_dump($_FILES['file']);\n   // 'file' correspond to the value of this option.\n   ```\n\n * **maxFileSize**: (integer) ``Default 0`` File validation: Max file size in bytes. Zero means no limit.\n\n   ```javascript\n   maxFileSize: 3000000 // 3 Megs\n   ```\n\n * **allowedTypes**: (string) ``Default \"*\"`` File validation: Regular expression to match file mime-type.\n\n   ```javascript\n   allowedTypes: \"image/*\"\n   ```\n\n * **extFilter**: (array) ``Default null`` File validation: Array of allowed extensions.\n\n   ```javascript\n   extFilter: [\"jpg\", \"jpeg\", \"png\", \"gif\"]\n   ```\n\n## Callbacks\n\n### General purpose\n\n * **onInit**: () Widget it's ready to use.\n\n * **onFallbackMode**: () Triggers only when the browser is not supported by the plugin.\n\n * **onDragEnter**: () User is dragging files over the drop Area.\n\n * **onDragLeave**: () User left the drop Area.\n\n   This also triggers when the files are dropped.\n\n * **onDocumentDragEnter**: () User is dragging files anywhere over the $(document)\n\n * **onDocumentDragLeave**: () User left the $(document) area.\n\n   This also triggers when the files are dropped.\n\n * **onComplete**: () All pending files are completed. \n\n   Only applies when using `queue: true`. See [options](#options).\n\n   Triggers when the queue reaches the end (even if some files were cancelled or gave any error).\n\n### File callbacks\n All these include `id`\n\n `id` (string): Unique ID. Useful to identify the same file in subsequent callbacks.\n\n * **onNewFile**: (id, file) A new file was selected or dropped by the user.\n\n   - `file` (object): File object, use it to access file details such as name, size, etc.\n\n     For [reference click here](https://developer.mozilla.org/en-US/docs/Web/API/File).\n\n   - If multiple are added, this gets called multiple times.\n\n   - File validations were already executed.\n\n   - If a return value is provided and is `=== false` the file will be ignored by the widget.\n\n   - Use this return value to implement your own validators.\n\n * **onBeforeUpload**: (id) Upload request is about to be executed.\n\n * **onUploadProgress**: (id, percent) Got a new upload percentage for the file\n\n   `percent` (integer) : 0-100\n\n * **onUploadSuccess**: (id, data) File was successfully uploaded and got a response form the server\n\n   `data` (object) : Upload request response. The object type of this parameter depends of: `dataType` \n\n   See more in [options](#options).\n\n * **onUploadError**: (id, xhr, status, errorThrown) An error happened during the upload request.\n\n   `xhr` (object) : XMLHttpRequest\n\n   `status` (integer) : Error type, example: \"timeout\", \"error\", \"abort\", and \"parsererror\"\n\n   `errorThrown` (string) : Only when an HTTP error occurs: `Not Found`, `Bad Request`, etc.\n\n   Reference: http://api.jquery.com/jquery.ajax/\n\n * **onUploadComplete**: (id) The upload of the file was complete.\n\n   This triggers right after `onUploadSuccess` or `onUploadError`. In **both** cases.\n\n * **onUploadCanceled**: (id) Upload was cancelled by the user.\n\n   This one triggers when cancelling an upload using one of the API methods.\n\n   See more in [methods](#methods).\n\n### Validation callbacks\n\n * **onFileTypeError**: (file) File type validation failed.\n\n   Triggers when using the setting: `allowedTypes`.\n\n   See more in [options](#options).\n\n * **onFileSizeError**: (file) File size validation failed.\n\n   Triggers when using the setting: `maxFileSize`.\n\n   See more in [options](#options).\n\n * **onFileExtError**: (file) File extension validation failed.\n\n   Triggers when using the setting: `extFilter`.\n\n   See more in [options](#options).\n\n## Methods\n There are a few methods you can use to interact with the widget, some of their behavior may depend on settings.\n\n * **start**: (id) Start the upload. (id is optional)\n\n   Depending on the situation this method may do:\n     - Start the upload of an individual file if an `id` was provided and there isn't a `queue` running.\n     - Retry a failed or a previously cancelled file.\n     - Start the queue if `auto` is set to `false` and no `id` is provided\n     - Start ALL the pending files if `queue` is set to false `false`\n\n    Example:\n\n   ```javascript\n   $(\"#drop-area\").dmUploader(\"start\", id);\n   ```\n\n * **cancel**: (id) Cancel the upload. (id is optional)\n\n   Depending on the situation this method may do:\n     - Cancel a file that is currently uploading if an `id` is provided.\n     - Cancel all currently uploading files if an `id` is NOT provided.\n     - Cancel a pending file, and it it will be skipped by the `queue` if using that option\n     - Stop the current `queue` if using that option, and all current uploads.\n\n   Example:\n\n   ```javascript\n   $(\"#drop-area\").dmUploader(\"cancel\", id);\n   ```\n\n * **reset**: () Resets the plugin\n   \n   - Stops all uploads\n   - Removes all files\n   - Resets queue\n\n   Example:\n\n   ```javascript\n   $(\"#drop-area\").dmUploader(\"reset\");\n   ```\n\n * **destroy**: () Destroys all plugin data\n   \n   - Stops all uploads\n   - Removes all files\n   - Releases all the events, including the ones used by `hookDocument` if using that option\n\n   Example:\n\n   ```javascript\n   // Example\n   $(\"#drop-area\").dmUploader(\"destroy\");\n   ```\n\n","funding_links":[],"categories":["HTML"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanielm%2Fuploader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdanielm%2Fuploader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanielm%2Fuploader/lists"}