Skip to main content

Django formsets made convenient for users and developers alike.

Project description

Django Convenient Formsets

Python unit tests End-to-end tests Linters BrowserStack Status

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

  1. Install using pip:

    $ pip install django-convenient-formsets
    
  2. Add to INSTALLED_APPS:

    INSTALLED_APPS = [
        # ...
        'convenient_formsets'
    ]
    

Quick start

  1. 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')
    
  2. 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_widget property, used for the DELETE field in formset forms. It defaults to the forms.HiddenInput in 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:

  1. If a form includes a 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.
  2. If the form does not include a DELETE field, 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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for django-convenient-formsets, version 0.9.3
Filename, size File type Python version Upload date Hashes
Filename, size django_convenient_formsets-0.9.3-py3-none-any.whl (11.6 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size django-convenient-formsets-0.9.3.tar.gz (18.3 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page