Django formsets made convenient for users and developers alike.

These details have not been verified by PyPI

Reason this release was yanked:

Wheel package accidentally includes tests

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_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.

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 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 by the backend.
If the form does not include a DELETE field, 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.

Project details

These details have not been verified by PyPI

Release history Release notifications | RSS feed

2.0

Apr 5, 2023

1.2.1

Aug 21, 2022

1.2

Aug 21, 2022

1.1.1

Apr 6, 2022

1.1

Dec 9, 2021

1.0

Aug 11, 2021

0.9.4

Aug 10, 2021

0.9.3

Jul 29, 2021

0.9.2

Apr 21, 2021

This version

0.9.1 yanked

Apr 21, 2021

Reason this release was yanked:

Wheel package accidentally includes tests

0.9 yanked

Apr 9, 2021

Reason this release was yanked:

Incomplete wheel package

Download files

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

Source Distribution

django-convenient-formsets-0.9.1.tar.gz (17.1 kB view details)

Uploaded Apr 21, 2021 Source

Built Distribution

django_convenient_formsets-0.9.1-py3-none-any.whl (24.1 kB view details)

Uploaded Apr 21, 2021 Python 3

File details

Details for the file django-convenient-formsets-0.9.1.tar.gz.

File metadata

Download URL: django-convenient-formsets-0.9.1.tar.gz
Upload date: Apr 21, 2021
Size: 17.1 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/3.4.1 importlib_metadata/4.0.1 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.60.0 CPython/3.8.9

File hashes

Hashes for django-convenient-formsets-0.9.1.tar.gz
Algorithm	Hash digest
SHA256	`31c568cd8f9237ea5c76567621b50676eb58b9c34c9e6f7c095182d78889dd7d`
MD5	`dcd7d28f074bc1f7b90a66b68d74bed9`
BLAKE2b-256	`c7ba0c964e2c04e4fc99dd4aa5653097fa0bcdc47b017cb62b696c3362bc0f59`

See more details on using hashes here.

File details

Details for the file django_convenient_formsets-0.9.1-py3-none-any.whl.

File metadata

Download URL: django_convenient_formsets-0.9.1-py3-none-any.whl
Upload date: Apr 21, 2021
Size: 24.1 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/3.4.1 importlib_metadata/4.0.1 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.60.0 CPython/3.8.9

File hashes

Hashes for django_convenient_formsets-0.9.1-py3-none-any.whl
Algorithm	Hash digest
SHA256	`9f48456f35838461eb87e299e4f4d3e3a4ae90490644aa622867cf115f3e209a`
MD5	`df9f9c96be4b6eae847092df63ea5466`
BLAKE2b-256	`df0c8bafe766278cfd08fceeae7f4afcda47a63d72e358e8688cd13d09d14a7b`