1 `django-ajax-uploader` provides a useful class you can use to easily implement ajax uploads.
3 It uses valum's great uploader: https://github.com/valums/file-uploader, and draws heavy inspiration and some code from
4 https://github.com/alexkuhl/file-uploader
6 In short, it implements a callable class, `AjaxFileUploader` that you can use to handle uploads. By default, `AjaxFileUploader` assumes you want to upload to local storage, but you can select any other backend if desired or write your own (see backends section below). Pull requests welcome!
11 Version 0.2.1 is released, and contains:
13 * JSON parsing of `extra_context` now properly handles datetimes. (Thanks to onyxfish)
16 Version 0.2 is released, and contains:
18 * Optional `fileLimit` param for the uploader, to limit the number of allowed files. (Thanks to qnub)
19 * fhahn's `default_storage` backend.
22 Version 0.1.1 is released, and contains:
24 * Support for a CouchDB backend
25 * A backwards-incompatible change to the location of the ajaxuploader static files. I try to avoid backwards incompatibilities, but since /js and /css are the proper conventions and the lib is relatively young, it seemed better to get things right now, instead of waiting. The static files are now at:
26 * `{{STATIC_URL}}ajaxuploader/js/fileuploader.js`
27 * `{{STATIC_URL}}ajaxuploader/css/fileuploader.css`
32 Step 1. Install django-ajax-uploader.
33 -------------------------------------
34 It's in pypi now, so simply:
36 - `pip install ajaxuploader`
38 You may also need to install backend-specific dependences.
40 - For the S3 backend, you will need [boto](https://github.com/boto/boto). ( `pip install boto` )
41 - For the MongoDB GridFS backend, you will need [pymongo](https://github.com/AloneRoad/pymongo) ( `pip install pymongo` )
43 Step 2. (Django 1.3 only)
44 -------------------------
45 For Django 1.3 you will need to have the app in your installed apps tuple for collect static to pick up the files.
47 First Add 'ajaxuploader' to you installed apps in settings.py
59 $ python manage.py collectstatic
62 Step 3. Include it in your app's views and urls.
63 ------------------------------------------------
64 You'll need to make sure to meet the csrf requirements to still make valum's uploader work. Code similar to the following should work:
69 from django.middleware.csrf import get_token
70 from django.shortcuts import render_to_response
71 from django.template import RequestContext
73 from ajaxuploader.views import AjaxFileUploader
77 csrf_token = get_token(request)
78 return render_to_response('import.html',
79 {'csrf_token': csrf_token}, context_instance = RequestContext(request))
81 import_uploader = AjaxFileUploader()
87 url(r'start$', views.start, name="start"),
88 url(r'ajax-upload$', views.import_uploader, name="my_ajax_upload"),
91 Step 4. Set up your template.
92 -----------------------------
93 This sample is included in the templates directory, but at the minimum, you need:
98 <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.6.1/jquery.min.js" ></script>
99 <script src="{{ STATIC_URL }}ajaxuploader/js/fileuploader.js" ></script>
100 <link href="{{ STATIC_URL }}ajaxuploader/css/fileuploader.css" media="screen" rel="stylesheet" type="text/css" />
103 var uploader = new qq.FileUploader({
104 action: "{% url my_ajax_upload %}",
105 element: $('#file-uploader')[0],
107 onComplete: function(id, fileName, responseJSON) {
108 if(responseJSON.success) {
111 alert("upload failed!");
114 onAllComplete: function(uploads) {
115 // uploads is an array of maps
116 // the maps look like this: {file: FileObject, response: JSONServerResponse}
117 alert("All complete!");
120 'csrf_token': '{{ csrf_token }}',
121 'csrf_name': 'csrfmiddlewaretoken',
122 'csrf_xname': 'X-CSRFToken',
129 <div id="file-uploader">
131 <p>Please enable JavaScript to use file uploader.</p>
141 `django-ajax-uploader` can put the uploaded files into a number of places, and perform actions on the files uploaded. Currently,
142 there are backends available for local storage (default), Amazon S3, MongoDB (GridFS), CouchDB, and a locally stored image
143 thumbnail backend. Creating a custom backend is fairly straightforward, and pull requests are welcome.
148 `django-ajax-uploader` has the following backends:
150 ### local.LocalUploadBackend ###
152 Stores the file locally, by default to `{MEDIA_ROOT}/uploads`.
160 * `UPLOAD_DIR` : The directory to store the uploaded file in, within `MEDIA_ROOT`. Defaults to "uploads".
161 * `BUFFER_SIZE`: The size of each chunk to write. Defaults to 10 MB. See the caveat at the bottom before changing it.
165 * `path`: The full media path to the uploaded file.
168 ### mongodb.MongoDBUploadBackend ###
170 Stores the file in MongoDB via GridFS
174 * [pymongo](https://github.com/AloneRoad/pymongo)
178 * `AJAXUPLOAD_MONGODB_HOST`: Specify the host of your MongoDB server. Defaults to localhost if not specified.
179 * `AJAXUPLOAD_MONGODB_PORT`: Specify the port of your MongoDB server. Defaults to 27017 if not specified.
183 * db (required): Specify the database within MongoDB you wish to use
184 * collection (optional): Specify the collection within the db you wish to use. This is optional and will default to `fs` if not specified
192 ### couch.CouchDBUploadBackend ###
194 Stores the file in a CouchDB backend
198 * [couchdb](http://code.google.com/p/couchdb-python/)
202 * `AJAXUPLOAD_COUCHDB_HOST`: Specify the host of your CouchDB server. Defaults to `http://localhost:5984` if not specified.
206 * db (required): Specify the database within CouchDB you wish to use
214 ### s3.S3UploadBackend ###
216 Stores the file in Amazon's S3.
220 * [boto](https://github.com/boto/boto)
224 * `NUM_PARALLEL_PROCESSES` : Uploads to Amazon are parallelized to increase speed. If you have more cores and a big pipe, increase this setting for better performance. Defaults to 4.
225 * `BUFFER_SIZE`: The size of each chunk to write. Defaults to 10 MB.
232 ### thumbnail.ThumbnailUploadBackend ###
234 Stores a thumbnail of the locally, optionally discarding the upload. Subclasses `LocalUploadBackend`.
238 * [sorl-thumbnail](https://github.com/sorl/sorl-thumbnail)
242 * `DIMENSIONS` : A string of the dimensions (WxH) to resize the uploaded image to. Defaults to "100x100"
243 * `KEEP_ORIGINAL`: Whether to keep the originally uploaded file. Defaults to False.
244 * `BUFFER_SIZE`: The size of each chunk to write. Defaults to 10 MB.
248 * `path`: The full media path to the uploaded file.
251 ### default_storage.DefaultStorageUploadBackend ###
253 This backend uses Django's default storage backend (defined by the DEFAULT_FILE_STORAGE setting) to save the uploaded files.
261 * `UPLOAD_DIR` : The directory to store the uploaded file in, within `MEDIA_ROOT`. Defaults to "uploads".
262 * `BUFFER_SIZE`: The size of each chunk to write. Defaults to 10 MB. See the caveat at the bottom before changing it.
266 * `path`: The full media path to the uploaded file.
270 ------------------------
272 The default backend is `local.LocalUploadBackend`. To use another backend, specify it when instantiating `AjaxFileUploader`.
274 For instance, to use `MongoDBUploadBackend`:
279 from ajaxuploader.views import AjaxFileUploader
280 from ajaxuploader.backends.mongodb import MongoDBUploadBackend
283 import_uploader = AjaxFileUploader(backend=MongoDBUploadBackend, db='uploads')
286 To set custom parameters, simply pass them along with instantiation. For example, for larger thumbnails, preserving the originals:
289 from ajaxuploader.backends.thumbnail import ThumbnailUploadBackend
292 import_uploader = AjaxFileUploader(backend=ThumbnailUploadBackend, DIMENSIONS="500x500", KEEP_ORIGINAL=True)
298 To write a custom backend, simply inherit from `backends.base.AbstractUploadBackend` and implement the `upload_chunk` method. All possible methods to override are described below.
300 * `upload_chunk` - takes a string, and writes it to the specified location.
301 * `setup`: takes the original filename, does all pre-processing needed before uploading the file (for example, for the S3 backend, this method is used to establish a connection with the S3 server).
302 * `update_filename`: takes the `request` object and the original name of the file being updated, can return a new filename which will be used to refer to the file being saved. If undefined, the uploaded filename is used. If not overriden by `upload_complete`, this value will be returned in the response.
303 * `upload_complete`: receives the `request` object and the filename post `update_filename` and does any cleanup or manipulation after the upload is complete. (Examples: cropping the image, disconnecting from the server). If a dict is returned, it is used to update the response returned to the client.
308 `BUFFER_SIZE` - some users have reported problems using smaller buffer sizes. I also saw random failed uploads with very small sizes like 32k. 10MB has been completely reliable for me, and in what I've read here and there, so do some testing if you want to try a different value. Note that this doesn't have a big impact on the overall upload speed.
313 Original implementation and ongoing maintenance by [skoczen](https://github.com/skoczen), courtesy of [GoodCloud](https://www.agoodcloud.com).
314 Most of the backend abstraction was written by [chromano](https://github.com/chromano) and [shockflash](https://github.com/shockflash).
315 MongoDB support and saner defaults by [chrisjones-brack3t](https://github.com/chrisjones-brack3t).
316 Threadsafe improvements and bugfixes by [dwaiter](https://github.com/dwaiter).
317 CouchDB support by [paepke](https://github.com/paepke).
318 Default Storage backend by [fhahn](https://github.com/fhahn).
319 File number limit in upload by [qnub](https://github.com/qnub).
320 JSON parsing improvements by [onyxfish](https://github.com/onyxfish).
322 This code began as such a trivial layer on top of [valum's uploader](http://valums.com/ajax-upload/), [boto](https://github.com/boto/boto), and [alex's ideas](http://kuhlit.blogspot.com/2011/04/ajax-file-uploads-and-csrf-in-django-13.html) it's silly. However, I didn't find any implementations that *just worked*, so hopefully it's useful to someone else. I also drew from these sources:
324 * http://www.topfstedt.de/weblog/?p=558
325 * http://www.elastician.com/2010/12/s3-multipart-upload-in-boto.html
326 * https://github.com/valums/file-uploader
327 * https://github.com/alexkuhl/file-uploader
329 Many thanks to all for writing such helpful and readable code!