Extend Django formsets with JavaScript
pip install django-formset-js==0.4.1
A wrapper for a JavaScript formset helper.
Install via pip:
pip install django-formset-js
Then add it and its dependancy django-jquery-js
to your INSTALLED_APPS
:
INSTALLED_APPS += (
'django.contrib.staticfiles',
'jquery',
'djangoformsetjs',
)
Both jQuery and this library must be included in your page. The simplest way to do this is to add the scripts as media dependencies on your form:
from djangoformsetjs.utils import formset_media_js
class MyForm(forms.Form):
class Media(object):
js = formset_media_js + (
# Other form media here
)
MyFormSet = formset_factory(MyForm)
And then include the Media of the form in your template:
{{ formset.media }}
Alternatively, simply add the script tags:
<script src="{{ STATIC_URL }}js/jquery.js"></script>
<script src="{{ STATIC_URL }}js/jquery.formset.js"></script>
So that the library can work with your formset,
certain blocks of your formset need to be marked up with data-formset-...
attributes:
{% load formset_tags %}
<div id="formset" data-formset-prefix="{{ formset.prefix }}">
{{ formset.management_form }}
<div data-formset-body>
<!-- New forms will be inserted in here -->
{% for form in formset %}
<div data-formset-form>
{{ form }}
<button type="button" data-formset-delete-button>Delete form</button>
</div>
{% endfor %}
</div>
<!-- The empty form template. By wrapping this in a <script> tag, the
__prefix__ placeholder can easily be replaced in both attributes and
any scripts -->
<script type="form-template" data-formset-empty-form>
{% escapescript %}
<div data-formset-form>
{{ formset.empty_form }}
<button type="button" data-formset-delete-button>Delete form</button>
</div>
{% endescapescript %}
</script>
<!-- This button will add a new form when clicked -->
<input type="button" value="Add another" data-formset-add>
<script>jQuery(function($) {
$("#formset").formset({
animateForms: true
});
});</script>
</div>
The data-formset-
data attributes are:
data-formset-prefix
{{ formset.prefix }}
.
This is used to find the management form.data-formset-body
data-formset-form
data-formset-empty-form
<script>
tag.data-formset-add
data-formset-delete-button
The empty form template is wrapped in a <script>
as plain text.
This stops any JavaScript attached to widgets from running upon page load,
and makes finding and replacing the __prefix__
placeholder easier.
The contents of the <script>
should be wrapped in a {% escapescript %}
block
to prevent any script tags inside from closing the wrapping script tag prematurely.
When the data-formset-add
button is clicked, the formAdded
event is
fired on the form which was added. This event propagates upwards, and as such
can be handled from the form container.
For example, to select the new form added for form additions from the above
example, bind as such:
$('#formset').on('formAdded', function(event) {
newForm = event.target;
//Do Stuff
});
If the forms can be deleted, and contain a delete checkbox, the following actions occur:
formDeleted
event is fired on the data-formset-form
container,
and the data-formset-form-deleted
attribute is added.formAdded
event is fired on the data-formset-form
container,
and the data-formset-form-deleted
attribute is removed.If the forms can be deleted, and contain a delete button,
pressing the delete button will toggle the delete checkbox for that form.
The DELETE
field should be hidden if the delete button is used.
The delete button is identified by the data-formset-delete-button
attribute:
{% for form in formset %}
<div data-formset-form>
{{ form.name }}
{{ form.age }}
<div class="hidden">{{ form.DELETE }}</div>
<button type="button" data-formset-delete-button>Delete form</button>
</div>
{% endfor %}
If the animateForms
option is set when the formset is created,
adding and deleting forms will be animated by sliding the forms in and out.
The jQuery plugin takes the following options:
form
:[data-formset-form]
.emptyForm
:script[type=form-template][data-formset-empty-form]
.body
:[data-formset-body]
.add
:[data-formset-add]
.deleteButton
:[data-formset-delete-button]
.hasMaxFormsClass
:has-max-forms
.animateForms
:false
.If the bundled functionality is not for you,
you can interact with the formset using the JavaScript API.
All the behaviour is driven by a Formset
class.
To get a Formset
for an element, call:
var formset = $('#my-form').formset('getOrCreate');
This can be called multiple times on a single element,
and will always return the same Formset
instance.
All the methods and attributes listed below operate on a Formset
instance.
Formset.opts
Formset
.Formset.$formset
Formset
was created for.Formset.$emptyForm
Formset.$body
Formset.$add
Formset.addForm()
Formset
.
If the maximum number of forms would be exceeded if another form was added,
an error will be thrown.Formset.$forms()
Formset
.Formset.$managementForm(field)
Get a jQuery object for the management form field field
:
// Update the TOTAL_FORMS management form field
this.$managementForm('TOTAL_FORMS').val(10);
Formset.totalFormCount()
Formset
, including deleted forms.Formset.activeFormCount()
Formset
.Formset.deletedFormCount()
Formset
.Formset.hasMaxForms()
Formset
has its maximum number of forms.Formset.checkMaxForms()
Formset
,
and set the relevant classes on the Formset
element
if the Formset
has reached its limit.A minimal example project is provided in the example/
directory.
Read example/README
for more information
When running ./setup.py sdist
, the JavaScript asset is minified using
UglifyJS if it is installed. To install UglifyJS, install node.js and npm, and
run:
npm install uglifyjs
You can minify the scripts manually using:
./setup.py minify