django-convenient-formsets
Advanced tools
Django dynamic formsets made convenient for users and developers alike.
This Django app aims to make dynamic formsets convenient for users and developers alike. It extends Django's built-in formset classes and includes support for adding, deleting and ordering of forms in the browser. JavaScript events are dispatched when forms are added, deleted or reordered, for executing custom logic.
Other platform versions may work, but are not actively tested.
Install using pip:
$ pip install django-convenient-formsets
Add to INSTALLED_APPS:
INSTALLED_APPS = [
# ...
'convenient_formsets'
]
Create a formset in your Python code:
from convenient_formsets import ConvenientBaseFormSet
from django import forms
class EmailForm(forms.Form):
email = forms.EmailField()
EmailFormSet = forms.formset_factory(
EmailForm,
formset=ConvenientBaseFormSet,
can_delete=True,
can_order=True,
)
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': '#email-formset #email-forms-container',
'formSelector': '.email-form',
'canAddForms': true,
'addFormButtonSelector': '#email-formset #add-form-button',
'emptyFormTemplateSelector': '#email-formset #empty-form-template',
'canDeleteForms': true,
'deleteFormButtonSelector': '#delete-form-button',
'canOrderForms': true,
'moveFormDownButtonSelector': '#move-form-down-button',
'moveFormUpButtonSelector': '#move-form-up-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 }}
<input type="button" id="delete-form-button" value="Delete">
{% endif %}
{% if email_formset.can_order %}
{{ email_form.ORDER }}
<input type="button" id="move-form-up-button" value="Move up">
<input type="button" id="move-form-down-button" value="Move down">
{% endif %}
</div>
{% endfor %}
</div>
<div><input type="button" id="add-form-button" value="Add another"></div>
<template id="empty-form-template">
<div class="email-form">
{{ email_formset.empty_form.email }}
{% if email_formset.can_delete %}
<input type="button" id="delete-form-button" value="Delete">
{% endif %}
{% if email_formset.can_order %}
{{ email_form.ORDER }}
<input type="button" id="move-form-up-button" value="Move up">
<input type="button" id="move-form-down-button" value="Move down">
{% endif %}
</div>
</template>
{{ email_formset.management_form }}
</div>
</body>
</html>
The Python classes ConvenientBaseFormSet, ConvenientBaseModelFormSet and
ConvenientBaseInlineFormSet extend Django's built-in BaseFormSet,
BaseModelFormSet and BaseInlineFormSet by:
deletion_widget for the DELETE field and ordering_widget for
the ORDER field. They default to the forms.HiddenInput widget in order to
hide them from the user.media attribute required
for dynamic formsets.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.
It is important that both the visible forms and the empty form follow the same structure. A form also needs to be contained inside a single parent element, denoted by the formSelector parameter:
<!-- Visible forms inside forms container -->
<div id="email-forms-container">
<div class="email-form">
<!-- Form -->
</div>
</div>
<!-- Empty form inside template element -->
<template id="empty-form-template">
<div class="email-form">
<!-- Form -->
</div>
</template>
Creating an instance of the JavaScript constructor function ConvenientFormset
allows a user to add, delete and reorder 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
initialization fails, check the browser console for some helpful output.
When adding, deleting or reordering forms, custom JavaScript events are dispatched to allow for executing custom JavaScript code:
All events will contain the formsetPrefix parameter value in the event's
detail property.
These events can be handled in the following way:
document.addEventListener('convenient_formset:added', (event) => {
if (event.detail.formsetPrefix === 'email-formset') {
// Handle event for a specific formset on the webpage
}
});
document.addEventListener('convenient_formset:removed', (event) => {
// Handle event for any formset on the webpage
});
Form deletion is handled in either of the following ways:
DELETE field, the field's value is updated and the
form will be hidden by applying the "hidden" HTML attribute. The deletion
will then be handled server side.DELETE field, the form is removed from
the DOM altogether and will not be submitted to the server.Form ordering is handled by moving visible forms above the previous (up)
and below the next (down) for visual feedback, and by swapping the values of
their ORDER fields for the server side. This means that the original values
are kept, even when in-between forms are deleted. New forms will see the
initial value for their ORDER field set to the last visible form's ORDER
field value + 1, as they're added to the bottom of all forms.
The scripts and documentation in this project are released under the BSD-3-Clause License.
FAQs
Django dynamic formsets made convenient for users and developers alike.
We found that django-convenient-formsets demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Ransomware payment rates hit an all-time low in 2024 as law enforcement crackdowns, stronger defenses, and shifting policies make attacks riskier and less profitable.
Security News
require(esm) backported to Node.js 20, easing the transition to ESM-only packages and reducing complexity for developers as Node 18 nears end-of-life.
Security News
PyPI now supports iOS and Android wheels, making it easier for Python developers to distribute mobile packages.