Skip to main content

So much easier handling of formsets.

Project description

django-superform
================

**Less sucking formsets.**

|build| |docs| |package| |gitter|

A ``SuperForm`` is absolutely super if you want to nest a lot of forms in each
other. Use formsets and nested forms inside the ``SuperForm``. The
``SuperForm`` will take care of its children!

.. note::
This package is still in rapid development. Some APIs might change in the
future and it's not yet feature complete. The documentation is not yet
complete either, but everything that is documented, is up to date and
should work as stated. If not, then please file a bug.
Every non-backwards compatible change and new features will be documented
in the changelog_.

.. _changelog: https://github.com/gregmuellegger/django-superform/tree/master/CHANGES.rst

Imagine you want to have a view that shows and validates a form and a formset.
Let's say you have a signup form where users can enter multiple email
addresses. Django provides formsets_ for this usecase, but handling those in a
view is usually quite troublesome. You need to validate both the form and the
formset manually and you cannot use django's generic FormView_. So here comes
**django-superform** into play.

.. _formsets: https://docs.djangoproject.com/en/1.6/topics/forms/formsets/
.. _FormView: https://docs.djangoproject.com/en/1.6/ref/class-based-views/generic-editing/#formview

Here we have an example for the usecase. Let's have a look at the
``forms.py``:

.. code-block:: python

from django import forms
from django_superform import SuperModelForm, InlineFormSetField
from myapp.models import Account, Email


class EmailForm(forms.ModelForm):
class Meta:
model = Email
fields = ('account', 'email',)


EmailFormSet = modelformset_factory(EmailForm)


class SignupForm(SuperModelForm):
username = forms.CharField()
# The model `Email` has a ForeignKey called `user` to `Account`.
emails = InlineFormSetField(formset_class=EmailFormSet)

class Meta:
model = Account
fields = ('username',)


So we assign the ``EmailFormSet`` as a field directly to the ``SignupForm``.
That's where it belongs! Ok and how do I handle this composite form in the
view? Have a look:

.. code-block:: python

def post_form(request):
if request.method == 'POST':
form = PostForm(request.POST)
if form.is_valid():
account = form.save()
return HttpResponseRedirect('/success/')
else:
form = PostForm()
return render_to_response('post_form.html', {
'form',
}, context_instance=RequestContext(request))


No, we don't do anything different as we would do without having the
``FormSet`` on the ``SignupForm``. That way you are free to implement all the
logic in the form it self where it belongs and use generic views like
``CreateView`` you would use them with simple forms. Want an example for this?

.. code-block:: python

from django.views.generic import CreateView
from myapp.models import Account
from myapp.forms import SignupForm


class SignupView(CreateView):
model = Account
form_class = SignupForm


urlpatterns = patterns('',
url('^signup/$', SignupView.as_view()),
)

And it just works.

Documentation
-------------

Full documentation is available on Read The Docs: https://django-superform.readthedocs.org/

----

Developed by Gregor Müllegger in cooperation with Team23_.

.. _Team23: http://www.team23.de/

.. |build| image:: https://travis-ci.org/gregmuellegger/django-superform.svg?branch=master
:alt: Build Status
:scale: 100%
:target: https://travis-ci.org/gregmuellegger/django-superform
.. |docs| image:: https://readthedocs.org/projects/django-superform/badge/?version=latest
:alt: Documentation Status
:scale: 100%
:target: https://django-superform.readthedocs.org/
.. |package| image:: https://badge.fury.io/py/django-superform.svg
:alt: Package Version
:scale: 100%
:target: http://badge.fury.io/py/django-superform
.. |gitter| image:: https://badges.gitter.im/JoinChat.svg
:alt: Gitter Chat, discuss django-superform with others
:scale: 100%
:target: https://gitter.im/gregmuellegger/django-superform


Changelog
=========

0.3.1
-----

* ``SuperForm.composite_fields`` dict is not longer shared between form
instances. Every new form instances get's a deep copy. So changes to it
won't leak into other instances of the same form class.

0.3.0
-----

* `#11`_: Fix ``CompositeBoundField`` to allow direct access to nested form
fields via ``form['nested_form']['field']``.
* Support for Django's Media handling in nested forms. See `#3`_ and `#5`_.
* Do not populate errorlist representations without any errors of nested
formsets into the errors of the super form. See `#5`_ for details.

.. _#3: https://github.com/gregmuellegger/django-superform/issues/3
.. _#5: https://github.com/gregmuellegger/django-superform/pull/5
.. _#11: https://github.com/gregmuellegger/django-superform/issues/11

0.2.0
-----

* Django 1.8 support.
* Initial values given to the ``__init__`` method of the super-form will get
passed through to the nested forms.
* The ``empty_permitted`` argument for modelforms used in a ``ModelFormField``
is set depending on the ``required`` attribute given to the field.

0.1.0
-----

* Initial release with proof of concept.

Project details


Download files

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

Source Distribution

django-superform-0.3.1.tar.gz (24.2 kB view details)

Uploaded Source

File details

Details for the file django-superform-0.3.1.tar.gz.

File metadata

File hashes

Hashes for django-superform-0.3.1.tar.gz
Algorithm Hash digest
SHA256 149421eaf0cad3571ed8eb159d95a6020dce8bbb93717bc4303fe804c0164aba
MD5 a00c00cd094d665a8342b820823b1abe
BLAKE2b-256 c2a8e21b160b66031439157a73c2f84b94d2981f6e5c85fcbcfb4bd11580c3d8

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page