| Name | django-filepond-form-widget JSON |
| Version |
0.2.1
JSON |
| download |
| home_page | None |
| Summary | A Django form widget using FilePond with image preview support |
| upload_time | 2025-01-09 10:05:36 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT License Copyright (c) 2025 Krystof Beuermann Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
django
filepond
widget
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# django-filepond-form-widget
A Django form widget using FilePond with image preview support.
## Table of Contents
- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Example](#example)
- [Testing](#testing)
- [Contributing](#contributing)
- [License](#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})
```
### 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).
-
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.
Raw data
{
"_id": null,
"home_page": null,
"name": "django-filepond-form-widget",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "django, filepond, widget",
"author": null,
"author_email": "Krystof Beuermann <krystof+django@blackbox.ms>",
"download_url": "https://files.pythonhosted.org/packages/0b/ed/cc1e5b0016d36d7f548679404133301952374aa49bc8739d5563a7353ba7/django_filepond_form_widget-0.2.1.tar.gz",
"platform": null,
"description": "# django-filepond-form-widget\n\nA Django form widget using FilePond with image preview support.\n\n## Table of Contents\n- [Features](#features)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Example](#example)\n- [Testing](#testing)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Features\n- **Easy Integration**: Seamlessly integrates FilePond with Django forms.\n- **Image Preview**: Provides image preview functionality out of the box.\n- **Customization**: Configurable options to tailor the widget to your needs.\n- **Responsive Design**: Ensures a responsive and user-friendly interface.\n- **Simple Form Submission**: Focuses on regular file field submissions with forms, without handling server API endpoints.\n- **Language Selection**: Automatically sets the locale based on the current language, ensuring the FilePond interface matches the user's language preferences.\n- **Extensible**: Support for additional FilePond plugins planned for future releases.\n\nNote: 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.\n\n## Installation\nInstall the package using pip:\n\n```\npip install django-filepond-form-widget\n```\n\nAlternatively, you can install it from the repository:\n\n```\npip install git+https://github.com/krystofbe/django-filepond-form-widget.git\n```\n\n\n\n## Usage\n### Add to Installed Apps\n\nAdd `django_filepond_form_widget` to your `INSTALLED_APPS` in `settings.py`:\n\n```\nINSTALLED_APPS = [\n # ...\n 'django_filepond_form_widget',\n # ...\n]\n```\n\n### Include Static Files\n\nEnsure that your templates include the necessary static files. Typically, this is handled automatically by the widget's media.\n\n### Use the Widget in Forms\n\n```\nfrom django import forms\nfrom django_filepond_form_widget.widgets import FilePondWidget\n\n\nclass ExampleForm(forms.Form):\n image = forms.FileField(\n widget=FilePondWidget(\n config={\"allowImagePreview\": True, \"allowMultiple\": False}\n )\n )\n```\n\n### Create Views and Templates\n\n```\nfrom django.shortcuts import render\nfrom .forms import ExampleForm\n\n\ndef upload_view(request):\n if request.method == \"POST\":\n form = ExampleForm(request.POST, request.FILES)\n if form.is_valid():\n # Handle uploaded file\n return render(request, \"example_app/success.html\")\n else:\n form = ExampleForm()\n return render(request, \"example_app/upload.html\", {\"form\": form})\n```\n### File Size Validation\n\nTo enable file size validation, set the `allowFileSizeValidation` option to `True` in the widget's `config`. You can also configure the following options:\n\n- `minFileSize`: The minimum size of a file (e.g., \"1KB\", \"2MB\").\n- `maxFileSize`: The maximum size of a file (e.g., \"5MB\", \"10MB\").\n- `maxTotalFileSize`: The maximum total size of all files (e.g., \"10MB\", \"20MB\").\n- `labelMaxFileSizeExceeded`: Custom message when a file exceeds `maxFileSize`.\n- `labelMaxFileSize`: Custom message showing the max file size.\n- `labelMaxTotalFileSizeExceeded`: Custom message when total size exceeds `maxTotalFileSize`.\n- `labelMaxTotalFileSize`: Custom message showing the max total file size.\n\n### Image Resize\n\nTo enable image resizing, set the `allowImageResize` option to `True` in the widget's `config`. You can also configure the following options:\n\n- `imageResizeTargetWidth`: The target width of the resized image in pixels.\n- `imageResizeTargetHeight`: The target height of the resized image in pixels.\n- `imageResizeMode`: The resizing mode ('cover', 'contain', or 'force').\n- `imageResizeUpscale`: Whether to upscale images smaller than the target size (true or false).\n- \nExample:\n\n```\nfrom django import forms\nfrom django_filepond_form_widget.widgets import FilePondWidget\n\nclass ExampleForm(forms.Form):\n image = forms.FileField(\n widget=FilePondWidget(\n config={\n \"allowImagePreview\": True,\n \"allowMultiple\": False,\n \"allowFileSizeValidation\": True,\n \"maxFileSize\": \"5MB\",\n \"maxTotalFileSize\": \"10MB\",\n }\n )\n )\n```\n\n## Example\nAn example project is provided to demonstrate how to integrate and run the widget.\n\n### Run the Development Server\n\nNavigate to the example directory and run the server using Uvicorn:\n\n```\nuv run python example/manage.py runserver\n```\n\n### Access the Application\n\nOpen your browser and navigate to `http://localhost:8000/upload/` to see the file upload form in action.\n\n## Testing\nThis project uses pytest for testing. To run the tests:\n\n### Install Development Dependencies\n\n```\nuv pip install -e \".[test]\" \n```\n\n### Run Tests\n\n```\npytest\n```\n\n## Contributing\nContributions are welcome! Please follow these steps:\n\n1. Fork the repository.\n2. Create a new branch for your feature or bugfix.\n3. Commit your changes with clear messages.\n4. Submit a pull request detailing your changes.\n\n## License\nThis project is licensed under the MIT License.\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2025 Krystof Beuermann Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.",
"summary": "A Django form widget using FilePond with image preview support",
"version": "0.2.1",
"project_urls": null,
"split_keywords": [
"django",
" filepond",
" widget"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c5480154362aa9b45a88ec4342aaa3c89891d8bfafdb0ed486bcb6373519f596",
"md5": "26ce9318bde2ebfa63f7c46a45f84dd1",
"sha256": "803fe1fa3372695d6a82e1ec933736e5602c5f99cd4119e7e1fa44c0d2d0e616"
},
"downloads": -1,
"filename": "django_filepond_form_widget-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "26ce9318bde2ebfa63f7c46a45f84dd1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 103554,
"upload_time": "2025-01-09T10:05:35",
"upload_time_iso_8601": "2025-01-09T10:05:35.067001Z",
"url": "https://files.pythonhosted.org/packages/c5/48/0154362aa9b45a88ec4342aaa3c89891d8bfafdb0ed486bcb6373519f596/django_filepond_form_widget-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0bedcc1e5b0016d36d7f548679404133301952374aa49bc8739d5563a7353ba7",
"md5": "88fe413cb5a1e747a1c352a0f4547f87",
"sha256": "cc1ebab01b6d3f95c8b16dbd91f0e3f325d3805862ca8d0d64ba8b5c2f71afe8"
},
"downloads": -1,
"filename": "django_filepond_form_widget-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "88fe413cb5a1e747a1c352a0f4547f87",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 137019,
"upload_time": "2025-01-09T10:05:36",
"upload_time_iso_8601": "2025-01-09T10:05:36.101481Z",
"url": "https://files.pythonhosted.org/packages/0b/ed/cc1e5b0016d36d7f548679404133301952374aa49bc8739d5563a7353ba7/django_filepond_form_widget-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-09 10:05:36",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "django-filepond-form-widget"
}
