Getting Started with django-sticky-uploads ================================================ 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. Necessary Settings ---------------------------------------------------------------------- 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. .. code-block:: python 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. Including the URLs ---------------------------------------------------------------------- django-sticky-uploads includes views for accepting the AJAX file uploads. You'll need to include these in your url patterns: .. code-block:: python 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. Including the JS ---------------------------------------------------------------------- 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. .. code-block:: html {% load static from staticfiles %} 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. Adding the Widget ---------------------------------------------------------------------- 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. .. code-block:: python 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. Next Steps ---------------------------------------------------------------------- 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.