Metadata-Version: 2.4
Name: django-ajax-filefield
Version: 0.1.1
Summary: A modern, Django FileField replacement that uploads files via AJAX.
Project-URL: Homepage, https://github.com/loic/django-ajax-filefield
Project-URL: Repository, https://github.com/loic/django-ajax-filefield
Project-URL: Issues, https://github.com/loic/django-ajax-filefield/issues
Author-email: Loïc Bistuer <loic.bistuer@gmail.com>
License-Expression: BSD-3-Clause
License-File: LICENSE
Keywords: ajax,django,file,form,upload,widget
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Framework :: Django :: 5.2
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.10
Requires-Dist: django>=4.2
Description-Content-Type: text/markdown

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