Django formsets made convenient for users and developers alike.
Project description
Django Convenient Formsets
This Django app aims to make formsets convenient for users and developers alike. It extends Django's built-in formset classes and includes support for dynamically adding and removing of forms on the webpage.
Installation
-
Install using pip:
$ pip install django-convenient-formsets
-
Add to
INSTALLED_APPS:INSTALLED_APPS = [ # ... 'convenient_formsets' ]
Quick start
-
Create a formset in your Python code:
from django import forms from convenient_formsets import ConvenientBaseFormSet class EmailForm(forms.Form): email = forms.EmailField() EmailFormSet = forms.formset_factory( EmailForm, formset=ConvenientBaseFormset, can_delete=True, extra=1, ) email_formset = EmailFormSet(prefix='email-formset')
-
Render formset in your template and add JavaScript code for initialization:
<!doctype html> <html> <head> <!-- Include the formset's media --> {{ email_formset.media }} <!-- Initialize a ConvenientFormset --> <script> window.addEventListener('load', function(event) { new ConvenientFormset({ 'formsetPrefix': '{{ email_formset.prefix }}', 'formsContainerSelector': '#formset #forms-container', 'formSelector': '.form', 'canAddForms': true, 'addFormButtonSelector': '#formset #add-form-button', 'emptyFormSelector': '#formset #empty-form .form', 'canAddForms': true, 'deleteFormButtonSelector': '#delete-form-button', }); }); </script> </head> <body> <!-- Render formset using the following basic structure --> <div id="email-formset"> <div id="email-forms-container"> {% for email_form in email_formset.forms %} <div class="email-form"> {{ email_form.email }} {% if email_formset.can_delete %}{{ email_form.DELETE }}{% endif %} <input type="button" id="delete-form-button" value="Delete"> </div> {% endfor %} </div> <div><input type="button" id="add-form-button" value="Add another"></div> <div id="empty-form" hidden> <div class="email-form"> {{ email_formset.empty_form.email }} <input type="button" id="delete-form-button" value="Delete"> </div> </div> {{ email_formset.management_form }} </div> </body> </html>
Usage
Server side
The Python classes ConvenientBaseFormSet and ConvenientBaseModelFormSet
extend Django's built-in BaseFormSet and BaseModelFormset by:
- Allowing you to override the
delete_widgetproperty, used for theDELETEfield in formset forms. It defaults to theforms.HiddenInputin order to hide it from the user. - Including the JavaScript files required for dynamic formsets.
Client side
See the example in the Quick start guide above on how to render the formset in your HTML template. Feel free to add some intermediate DOM elements if it suits your template better, as long as you stick to the basic structure shown above.
Creating an instance of the JavaScript constructor function ConvenientFormset
allows a user to add and delete forms within the rendered formset. When a user
makes changes, the management form is updated accordingly. The constructor
function can be passed the parameters outlined below. In case the initialization
of ConvenientFormset fails, check the browser console for some helpful output.
GENERAL
- formsetPrefix
- The formset's "prefix" property (required).
- formsContainerSelector
- CSS selector for the DOM element that contains all the forms (required).
- formSelector
- CSS selector for each form within "formsContainerSelector" (required).
ADDING FORMS
- canAddForms
- Enables adding of new forms (default: true).
- addFormButtonSelector
- CSS selector for the DOM element that may be clicked to add an empty form (required if "canAddForms" is set).
- emptyFormSelector
- CSS selector for the empty form (required if "canAddForms" is set).
- hideAddFormButtonOnMaxForms
- Hides the add button when reaching the maximum number of forms, by applying the "hidden" HTML attribute (default: true).
DELETING FORMS
- canDeleteForms
- Enables deleting of forms (default: false).
- deleteFormButtonSelector
- CSS selector for the DOM element within "formSelector" that may be clicked to delete a form (required if "canDeleteForms" is set).
Internals
Form deletion is handled in either of the following ways:
- If a form includes a
DELETEfield, the field's value is updated and the form will be hidden by applying thehiddenHTML attribute. The deletion will then be handled server side. - If the form does not include a
DELETEfield, the form is removed from the DOM altogether and will not be submitted to the server.
License
The scripts and documentation in this project are released under the BSD-3-Clause License.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file django-convenient-formsets-0.9.3.tar.gz.
File metadata
- Download URL: django-convenient-formsets-0.9.3.tar.gz
- Upload date:
- Size: 18.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.4.2 importlib_metadata/4.6.1 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.61.2 CPython/3.9.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | fda4792b8c1ab65178091a9994a98cf2910582b96ddfdc60e3d864a221d50867 |
|
| MD5 | 403a745813437968e3f29909536dd1e1 |
|
| BLAKE2b-256 | d6433a560f90394988c64a0fd0e6d35584f7446c5842951d6bc00e67f7628422 |
File details
Details for the file django_convenient_formsets-0.9.3-py3-none-any.whl.
File metadata
- Download URL: django_convenient_formsets-0.9.3-py3-none-any.whl
- Upload date:
- Size: 11.6 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.4.2 importlib_metadata/4.6.1 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.61.2 CPython/3.9.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 306f391858b657f99d50be3b0bf7512a315e63afc86393fbc626306dc6402c9b |
|
| MD5 | c1eb1c2e5fcc5bf4f6eddeef58e0d71f |
|
| BLAKE2b-256 | a23b828495217ba6dd6f82cc7fa71640cb1aad4ec939b8cc982f004f39fbc398 |
