django-files-widget

Django AJAX form widgets and model fields for multiple files/images upload with progress bar

This is currently an alpha release. Not all functionality is there, only ImageField and ImagesField have been implemented and there is not yet enough error handling.

Features

• Drag & drop file uploading via AJAX
• Plus three other ways to add files: upload button, Django Filebrowser library, and by URL
• Uploading multiple files at once
• Upload progress bar
• Four model fields with corresponding form fields and widgets: ImagesField, ImageField, FilesField, and FileField
• Image gallery widget with drag & drop reordering
• Documents gallery widget with file type icons with drag & drop reordering
• Integrates with Django Admin, Grappelli, Django Filebrowser and Mezzanine

Screenshots

File drag & drop to ImagesWidget in Django Admin	Ajax upload progress bar in ImagesWidget in Django Admin

Quick Start

Requirements

• Django 1.5 or later
• sorl-thumbnail
• Pillow (or PIL)
• Unix/Linux (file saving uses os.link())
• jQuery 1.7 or later
• jQuery UI
• jQuery File Upload (included)

Install

pip install git+git://github.com/TND/django-files-widget.git

In settings.py

INSTALLED_APPS = (
    ...,
    'sorl.thumbnail',
    'topnotchdev.files_widget',
    ...,
)

MEDIA_URL = ...
MEDIA_ROOT = ...
THUMBNAIL_DEBUG = False

(Optional) basic settings with their defaults:

FILES_WIDGET_TEMP_DIR            # 'temp/files_widget/'
FILES_WIDGET_FILES_DIR           # 'uploads/files_widget/'
FILES_WIDGET_JQUERY_PATH         # (jQuery 1.9.1 from Google)
FILES_WIDGET_JQUERY_UI_PATH      # (jQuery UI 1.10.3 from Google)
FILES_WIDGET_USE_FILEBROWSER     # False
FILES_WIDGET_FILEBROWSER_JS_PATH # 'filebrowser/js/AddFileBrowser.js'

In urls.py

url(r'^files-widget/', include('topnotchdev.files_widget.urls')),

In models.py

from topnotchdev import files_widget

class MyModel(models.Model):
    image = files_widget.ImageField()
    images = files_widget.ImagesField()

Django Auth User Permissions (optional)

files_widget.can_upload_files

Template Usage Examples

No extra steps are required to use the widget in your Admin site. Here are some examples of displaying files and (thumbnail) images on your site:

A list of linked thumbnails:

{% for img in my_instance.images.all %}
    <a src="{{ img.url }}">
        {{ img.thumbnail_tag_100x100 }}
        <span class="caption">{{ img.filename }}</span>
    </a>
{% endfor %}

Only the next image:

{{ my_instance.images.next.img_tag }}

The filename without extension and underscores of the next 3 (or n) images:

{% for img in my_instance.images.next_3 %}
    {{ img.display_name }}
{% endfor %}

Or other attributes:

{{ my_instance.image.url }}
{{ my_instance.image.filename }}
{{ my_instance.image.local_path }} (just as an example)
{{ my_instance.image.exists }}
{{ my_instance.image.get_size }}
{{ my_instance.image.thumbnail_64x64.url }}
...

License

MIT

Credits

• jQuery File Upload
• Tutorial on jQuery Filedrop by Martin Angelov
• Tutorial on Django AJAX file upload by Alex Kuhl
• Answer on non-Model user permissions on Stackoverflow

API Documentation

(Under construction)

Navigation

Settings

• FILES_WIDGET_TEMP_DIR
• FILES_WIDGET_FILES_DIR
• FILES_WIDGET_JQUERY_PATH
• FILES_WIDGET_JQUERY_UI_PATH
• FILES_WIDGET_USE_FILEBROWSER
• FILES_WIDGET_FILEBROWSER_JS_PATH
• FILES_WIDGET_MAX_FILESIZE (not yet implemented)
• FILES_WIDGET_FILE_TYPES (not yet implemented)
• FILES_WIDGET_USE_TRASH (not yet implemented)
• FILES_WIDGET_TRASH_DIR (not yet implemented)

Model Fields

• files_widget.FileField() (not yet implemented)
• files_widget.FilesField() (not yet implemented)
• files_widget.ImageField()
• files_widget.ImagesField()

Model Field Options

• max_length
• on_delete (not yet implemented)
• max_files (not yet implemented)
• max_filesize (not yet implemented)
• file_types (not yet implemented)

FilesField and ImagesField Instance Attributes

• splitlines()
• all()
• count()
• first()
• last()
• next()
• next_n()
• has_next()
• as_list() (not yet implemented)
• as_gallery() (not yet implemented)
• as_carousel() (not yet implemented)

FileField, FilesField, ImageField and ImagesField Instance Attributes

• (unicode)
• settings
• escaped
• url
• local_path
• filename
• display_name
• ext
• img_tag()
• thumbnail()
• thumbnail_mxn()
• thumbnail_tag()
• thumbnail_tag_mxn()
• exists()
• get_size()
• get_accessed_time()
• get_created_time()
• get_modified_time()

Django Auth Permissions

• files_widget.can_upload_files
• files_widget.can_remove_files (not yet implemented)

Static Files Inclusion

• form.media
• files_widget/media.html (not yet implemented)
• Manual

Signals

• files_widget.signals.pre_upload (not yet implemented)
• files_widget.signals.post_upload (not yet implemented)
• files_widget.signals.pre_move (not yet implemented)
• files_widget.signals.post_move (not yet implemented)
• files_widget.signals.pre_delete (not yet implemented)
• files_widget.signals.post_delete (not yet implemented)

Signal Handlers

• post_save
• post_delete (not yet implemented)

Management Commands

• manage.py files_widget cleanup (not yet implemented)