This will walk you through the basics of getting started with django-sticky-uploads. It assumes that you have already installed django-sticky-uploads via:
pip install django-sticky-uploads
and have an existing project using a compatible version of Django and Python.
After installing you should include stickyuploads
in your INSTALLED_APPS
setting. To use the default upload view you must also be using contrib.auth
to manage users.
INSTALLED_APPS = (
# Required by stickyuploads
'django.contrib.auth',
# Required by contrib.auth
'django.contrib.contenttypes',
'django.contrib.sessions',
# Other apps go here
'stickyuploads',
)
This is required so that the built-in contrib.staticfiles
can find the JS
included in the django-sticky-uploads distribution. If you are not using
contrib.staticfiles
then this step is not required but you are on your
own to ensure the static files are included correctly.
django-sticky-uploads includes views for accepting the AJAX file uploads. You’ll need to include these in your url patterns:
from django.conf.urls import patterns, include, url
urlpatterns = patterns('',
# Other url patterns go here
url(r'^sticky-uploads/', include('stickyuploads.urls')),
)
The sticky-uploads/
is there for example purposes and you are free to
change it to suit your own needs.
The enhanced upload widget requires a small piece of JavaScript to handle the background
upload. Each of the cases assume that you are using contrib.staticfiles
to manage static dependencies.
First, you can add the following script tag to any page which will use the widget.
{% load static from staticfiles %}
<script type="text/javascript" src="{% static 'stickyuploads/js/django-uploader.js' %}"></script>
Alternatively, you can minimize the JavaScript and load that, or bundle it with other JavaScript for the page.
Yet another option is to include {{ form.media }}
, where form
is whatever form
is using the upload widget. The widget includes an
inner Media class
that lists 'stickyuploads/js/django-uploader.js'
as a dependency, and including
{{ form.media }}
in the template will produce the necessary markup to load it.
The final step to use django-sticky-uploads is to use the widget on an existing
form with a FileField
. The StickyUploadWidget
is a drop-in replacement for
the default ClearableFileInput
and can be used on any Django Form
including
``ModelForm``s.
from django import forms
from stickyuploads.widgets import StickyUploadWidget
class ExampleForm(forms.Form):
upload = forms.FileField(widget=StickyUploadWidget)
Note that to make use of the background upload, the user must be authenticated, so
the StickyUploadWidget
should only be used on forms/views where the user is
authenticated.
There are hooks on both the client side and server side for customizing the behavior of the uploads. Continue reading to see how you can adjust the default settings to fit your needs.