Django dynamic formsets made convenient for users and developers alike.

These details have not been verified by PyPI

Project links

Project description

Django Convenient Formsets

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 on the client side.

Supported platforms

Django: 4.0, 3.2, 3.1, 3.0, 2.2
Python: 3.10, 3.9, 3.8, 3.7, 3.6, 3.5
Browsers: Chrome 48+, Firefox 44+, Internet Explorer 11, Edge 79+, Opera 50+, Safari 11+, latest Safari on iOS, latest Chrome on Android

Other platform versions may work, but are not actively tested.

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 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',
                'emptyFormSelector': '#email-formset #empty-form .email-form',

                '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>
        <div id="empty-form" hidden>
            <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>
        </div>
        {{ email_formset.management_form }}
    </div>
</body>
</html>

Usage

Server side

The Python classes ConvenientBaseFormSet, ConvenientBaseModelFormSet and ConvenientBaseInlineFormSet extend Django's built-in BaseFormSet, BaseModelFormset and BaseInlineFormSet by:

Overriding 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.
Note: the deletion_widget attribute and corresponding method are available from Django 4.0 and later, and the ordering_widget attribute and corresponding method are available from Django 3.0 and later. They are backported to older Django versions for your convenience.
Including the JavaScript file in the formset's media attribute 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 initialization fails, check the browser console for some helpful output.

GENERAL

formsetPrefix: The formset's "prefix" attribute (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).

ORDERING FORMS

canOrderForms: Enables ordering of forms (default: false).
moveFormDownButtonSelector: CSS selector for the DOM element within "formSelector" that may be clicked to move a form down among the visible forms (required if "canOrderForms" is set).
moveFormUpButtonSelector: CSS selector for the DOM element within "formSelector" that may be clicked to move a form up among the visible forms (required if "canOrderForms" is set).

Internals

Form 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 server side.
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.

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.

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

Project links

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

This version

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

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-1.1.tar.gz (22.2 kB view details)

Uploaded Dec 9, 2021 Source

Built Distribution

django_convenient_formsets-1.1-py3-none-any.whl (13.9 kB view details)

Uploaded Dec 9, 2021 Python 3

File details

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

File metadata

Download URL: django-convenient-formsets-1.1.tar.gz
Upload date: Dec 9, 2021
Size: 22.2 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/3.7.1 importlib_metadata/4.8.2 pkginfo/1.8.2 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.9.9

File hashes

Hashes for django-convenient-formsets-1.1.tar.gz
Algorithm	Hash digest
SHA256	`920f8381ad3ee150574a356a5a40238c34804f62b6239018769ee8802e55b33f`
MD5	`2fd7015059155f4a1804a743a26f7430`
BLAKE2b-256	`622c7884ec82957c523f1912cf4059a1161615ff3e47c6014afe6adde2f1ff46`

See more details on using hashes here.

File details

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

File metadata

Download URL: django_convenient_formsets-1.1-py3-none-any.whl
Upload date: Dec 9, 2021
Size: 13.9 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/3.7.1 importlib_metadata/4.8.2 pkginfo/1.8.2 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.9.9

File hashes

Hashes for django_convenient_formsets-1.1-py3-none-any.whl
Algorithm	Hash digest
SHA256	`9001e25fe7c6545d0f672c3c217427fa536df9e5f6cb08b95af85f8f1410caa5`
MD5	`74e96a01a61f3fcee477365ddf5a7b9a`
BLAKE2b-256	`cdaa0c78b5a641a1dbbe0a49012ab2ec1c64d00378a21028a809fdef18d8ea84`