django-ajax-filefield

⚠️ WARNING: Work in Progress

This package is under active development and is not ready for production use. APIs may change without notice. Use at your own risk.

A modern, Django FileField replacement that uploads files via AJAX instantly upon selection.

🌟 Overview

django-ajax-filefield reimagines Django's native file handling, delivering a user experience that treats file uploads just like any other form fields. By implementing instant uploads, the package eliminates user frustration associated with traditional file fields.

This package features:

• Instant Uploads: Files are uploaded via AJAX immediately upon selection, not when the form is submitted.
• Progress Bar: Provides immediate visual feedback on the upload status, eliminating anxiety over large files.
• Data Retention: Files are retained server-side and re-presented to the user upon form validation failure.
• Unobtrusive Widget: Integrates cleanly with Django's form system and templates.

💔 Why Not Use Django's Default FileField?

The native FileField and its associated widgets suffer from several usability issues, especially in modern web applications and complex forms:

Problematic Behavior	Pain Point
No Progress Feedback	For large files, users have no way of knowing if the file upload is progressing or if the browser has frozen.
Late Validation	File validation (e.g., size checks, type checks) is deferred until the user hits the final form submit button. If the file is invalid, the user only finds out after waiting for the upload.
File Field Cleared on Error	This is arguably the most frustrating issue. If any other field in the form fails validation, the browser clears the file input field, forcing the user to pick and re-upload the file—even if the file itself was valid.
FormSet/Inline Admin Complexity	This issue is compounded when dealing with Django FormSets or the admin's inline interface, where losing file context across multiple forms is a workflow killer.

django-ajax-filefield solves all of these problems by decoupling the file selection process from the form submission process.

🚀 Installation

1. Install:

   pip install django-ajax-filefield

2. Add to INSTALLED_APPS in your project's settings.py:

   INSTALLED_APPS = [
       # ... other apps
       'ajax_filefield',
   ]

3. Configure the upload URL in your urls.py:

   # urls.py
   from django.urls import path
   from ajax_filefield.views import AjaxUploadView
   
   urlpatterns = [
       # ... other urls
       path('ajax-upload/', AjaxUploadView.as_view(), name='ajax_upload'),
   ]

💡 Usage

Simply use the custom field in your Django form, specifying the upload_view_name:

Forms

# forms.py
from django import forms
from ajax_filefield import AjaxFileField

class DocumentForm(forms.Form):
    title = forms.CharField(max_length=100)
    document = AjaxFileField(upload_view_name='ajax_upload')