django-filepond-form-widget

A Django form widget using FilePond with image preview support.

Table of Contents

• Features
• Installation
• Usage
• Example
• Testing
• Contributing
• License

Features

• Easy Integration: Seamlessly integrates FilePond with Django forms.
• Image Preview: Provides image preview functionality out of the box.
• Customization: Configurable options to tailor the widget to your needs.
• Responsive Design: Ensures a responsive and user-friendly interface.
• Simple Form Submission: Focuses on regular file field submissions with forms, without handling server API endpoints.
• Language Selection: Automatically sets the locale based on the current language, ensuring the FilePond interface matches the user's language preferences.
• Extensible: Support for additional FilePond plugins planned for future releases.

Note: This widget is designed to work with standard form submissions. While FilePond's server property can be configured for API endpoints, this is beyond the scope of this project which aims to provide a simple form widget implementation.

Installation

Install the package using pip:

pip install django-filepond-form-widget

Alternatively, you can install it from the repository:

pip install git+https://github.com/krystofbe/django-filepond-form-widget.git

Usage

Add to Installed Apps

Add django_filepond_form_widget to your INSTALLED_APPS in settings.py:

INSTALLED_APPS = [
    # ...
    'django_filepond_form_widget',
    # ...
]

Include Static Files

Ensure that your templates include the necessary static files. Typically, this is handled automatically by the widget's media.

Use the Widget in Forms

from django import forms
from django_filepond_form_widget.widgets import FilePondWidget


class ExampleForm(forms.Form):
    image = forms.FileField(
        widget=FilePondWidget(
            config={"allowImagePreview": True, "allowMultiple": False}
        )
    )

Create Views and Templates

from django.shortcuts import render
from .forms import ExampleForm


def upload_view(request):
    if request.method == "POST":
        form = ExampleForm(request.POST, request.FILES)
        if form.is_valid():
            # Handle uploaded file
            return render(request, "example_app/success.html")
    else:
        form = ExampleForm()
    return render(request, "example_app/upload.html", {"form": form})

Plugins

Image Preview

To enable image preview, set the allowImagePreview option to True in the widget's config. You can also configure the following options:

• imagePreviewMinHeight: Minimum image preview height.
• imagePreviewMaxHeight: Maximum image preview height.
• imagePreviewHeight: Fixed image preview height, overrides min and max preview height.
• imagePreviewMaxFileSize: Can be used to prevent loading of large images when createImageBitmap is not supported. By default no maximum file size is defined, expects a string, like "2MB" or "500KB".
• imagePreviewTransparencyIndicator: Set to 'grid' to render a transparency grid behind the image, set to a color value (for example '#f00') to set transparent image background color. Please note that this is only for preview purposes, the background color or grid is not embedded in the output image.
• imagePreviewMaxInstantPreviewFileSize: Maximum file size for images to preview immediately, if files are larger and the browser doesn't support createImageBitmap the preview is queued till FilePond is in rest state.
• imagePreviewMarkupShow: Set to false to hide image markup in the preview panel.
• imagePreviewMarkupFilter: Use to filter markup items, useful to show only certain items and hide others till the image file is generated by the image transform plugin.
• imagePreviewFilterItem: Use to filter file items before generating the preview, useful to filter certain image types or names if we do not wish to generate a preview. Receives a file item as the first argument. Return false to skip generating an image preview. (item) => !/svg/.test(item.fileType) will skip generating previews for SVGs.

File Size Validation

To enable file size validation, set the allowFileSizeValidation option to True in the widget's config. You can also configure the following options:

• minFileSize: The minimum size of a file (e.g., "1KB", "2MB").
• maxFileSize: The maximum size of a file (e.g., "5MB", "10MB").
• maxTotalFileSize: The maximum total size of all files (e.g., "10MB", "20MB").
• labelMaxFileSizeExceeded: Custom message when a file exceeds maxFileSize.
• labelMaxFileSize: Custom message showing the max file size.
• labelMaxTotalFileSizeExceeded: Custom message when total size exceeds maxTotalFileSize.
• labelMaxTotalFileSize: Custom message showing the max total file size.

Image Resize

To enable image resizing, set the allowImageResize option to True in the widget's config. You can also configure the following options:

• imageResizeTargetWidth: The target width of the resized image in pixels.
• imageResizeTargetHeight: The target height of the resized image in pixels.
• imageResizeMode: The resizing mode ('cover', 'contain', or 'force').
• imageResizeUpscale: Whether to upscale images smaller than the target size (true or false).

File Type Validation

To enable file type validation, set the allowFileTypeValidation option to True in the widget's config. You can also configure the following options:

• acceptedFileTypes: An array of accepted file types. Can be MIME types or wildcards. For example, ['image/*'] will accept all images, and ['image/png', 'image/jpeg'] will only accept PNGs and JPEGs.
• labelFileTypeNotAllowed: Custom message shown when an invalid file is added.
• fileValidateTypeLabelExpectedTypes: Custom message shown to indicate the allowed file types. Available placeholders are {allTypes}, {allButLastType}, and {lastType}.
• fileValidateTypeLabelExpectedTypesMap: Allows mapping file types to more visually appealing labels. For example, { 'image/jpeg': '.jpg' } will show .jpg in the expected types label. Set to null to hide a type from the label.

Example:

from django import forms
from django_filepond_form_widget.widgets import FilePondWidget

class ExampleForm(forms.Form):
    image = forms.FileField(
        widget=FilePondWidget(
            config={
                "allowImagePreview": True,
                "allowMultiple": False,
                "allowFileSizeValidation": True,
                "maxFileSize": "5MB",
                "maxTotalFileSize": "10MB",
            }
        )
    )

Example

An example project is provided to demonstrate how to integrate and run the widget.

Run the Development Server

Navigate to the example directory and run the server using Uvicorn:

uv run python example/manage.py runserver

Access the Application

Open your browser and navigate to http://localhost:8000/upload/ to see the file upload form in action.

Testing

This project uses pytest for testing. To run the tests:

Install Development Dependencies

uv pip install -e ".[test]"   

Run Tests

pytest

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository.
2. Create a new branch for your feature or bugfix.
3. Commit your changes with clear messages.
4. Submit a pull request detailing your changes.

License

This project is licensed under the MIT License.