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', 'emptyFormSelector': '#formset #empty-form .form', 'addFormButtonSelector': '#formset #add-form-button', '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
Backend
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.
Frontend
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 following parameters:
| Name | Description | Type | Required |
|---|---|---|---|
formsetPrefix |
The formset's prefix property |
String | Yes |
formsContainerSelector |
CSS selector for the DOM element that contains all the forms | String | Yes |
formSelector |
CSS selector for each form within formsContainerSelector |
String | Yes |
emptyFormSelector |
CSS selector for the empty form | String | Yes |
addFormButtonSelector |
CSS selector for the DOM element that may be clicked to add an empty form | String | Yes |
deleteFormButtonSelector |
CSS selector for the DOM element within formSelector that may be clicked to delete a form |
String | No |
hideAddFormButtonOnMaxForms |
Whether or not to hide the add button when reaching the max. number of forms (default: true) |
Boolean | No |
How adding an empty form works
The CSS selector addFormButtonSelector determines the DOM element that may be
clicked (i.e. button or anchor) by the user to add an empty form, denoted by
emptyFormSelector. It is cloned and added to the DOM element with
formsContainerSelector.
If the hideAddFormButtonOnMaxForms parameter is set to true and the maximum
number of forms is reached, the DOM element with addFormButtonSelector is
automatically hidden by applying the hidden HTML attribute until one of the
visible forms is deleted again.
How form deletion works
The CSS selector deleteFormButtonSelector determines the DOM element within
each form that may be clicked by the user to delete that form. If the parameter
deleteFormButtonSelector has not been provided, support for form deletion is
automatically disabled.
If a user clicks the DOM element with deleteFormButtonSelector, 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 by the backend. - If the form does not include a
DELETEfield, the form is removed from the DOM altogether and will not be submitted to the backend.
Troubleshooting
In case the initialization of ConvenientFormset fails, check the browser
console for some helpful output.
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
Hashes for django-convenient-formsets-0.9.2.tar.gz
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | fc9848f10d625680f23e96fca480bca0d0eb5f1826bf3579367ba0b90163f1be |
|
| MD5 | 2f17f6d4aabc84552a7ec02c6360400b |
|
| BLAKE2b-256 | 72459f9d7e32895cb4db2a2fa79f7ab9bc681e46a15ed8693ba2418d073dd8e5 |
Hashes for django_convenient_formsets-0.9.2-py3-none-any.whl
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | f193ea7658f78705251591602b3bad06b7659a8fd955b2714747566f29fc6457 |
|
| MD5 | e3e5500069aedba73b87179e8effcf46 |
|
| BLAKE2b-256 | 8f0553e9c968d28cc5d4f362cd15b80b6c8512255398446b2a2d08bd704710af |
