django-ajax-filefield 0.1.1
A modern, Django FileField replacement that uploads files via AJAX.
Requires Python: >=3.10
Keywords: ajax, django, file, form, upload, widget

# **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:
    ```python
    INSTALLED_APPS = [
        # ... other apps
        'ajax_filefield',
    ]
    ```

3. **Configure the upload URL** in your urls.py:
    ```python
    # 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**

```python
# 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')
```