Source code for dal.forms

"""
tl;dr: See FutureModelForm's docstring.

Many apps provide new related managers to extend your django models with. For
example, django-tagulous provides a TagField which abstracts an M2M relation
with the Tag model, django-gm2m provides a GM2MField which abstracts an
relation, django-taggit provides a TaggableManager which abstracts a relation
too, django-generic-m2m provides RelatedObjectsDescriptor which abstracts a
relation again.

While that works pretty well, it gets a bit complicated when it comes to
encapsulating the business logic for saving such data in a form object. This is
three-part problem:

- getting initial data,
- saving instance attributes,
- saving relations like reverse relations or many to many.

Django's ModelForm calls the form field's ``value_from_object()`` method to get
the initial data. ``FutureModelForm`` tries the ``value_from_object()`` method
from the form field instead, if defined. Unlike the model field, the form field
doesn't know its name, so ``FutureModelForm`` passes it when calling the form
field's ``value_from_object()`` method.

Django's ModelForm calls the form field's ``save_form_data()`` in two
occasions:

- in ``_post_clean()`` for model fields in ``Meta.fields``,
- in ``_save_m2m()`` for model fields in ``Meta.virtual_fields`` and
  ``Meta.many_to_many``, which then operate on an instance which as a PK.

If we just added ``save_form_data()`` to form fields like for
``value_from_object()`` then it would be called twice, once in
``_post_clean()`` and once in ``_save_m2m()``. Instead, ``FutureModelForm``
would call the following methods from the form field, if defined:

- ``save_object_data()`` in ``_post_clean()``, to set object attributes for a
  given value,
- ``save_relation_data()`` in ``_save_m2m()``, to save relations for a given
  value.

For example:

- a generic foreign key only sets instance attributes, its form field would do
  that in ``save_object_data()``,
- a tag field saves relations, its form field would do that in
  ``save_relation_data()``.
"""

from itertools import chain

from django import forms


[docs]class FutureModelForm(forms.ModelForm): """ ModelForm which adds extra API to form fields. Form fields may define new methods for FutureModelForm: - ``FormField.value_from_object(instance, name)`` should return the initial value to use in the form, overrides ``ModelField.value_from_object()`` which is what ModelForm uses by default, - ``FormField.save_object_data(instance, name, value)`` should set instance attributes. Called by ``save()`` **before** writting the database, when ``instance.pk`` may not be set, it overrides ``ModelField.save_form_data()`` which is normally used in this occasion for non-m2m and non-virtual model fields. - ``FormField.save_relation_data(instance, name, value)`` should save relations required for value on the instance. Called by ``save()`` **after** writting the database, when ``instance.pk`` is necessarely set, it overrides ``ModelField.save_form_data()`` which is normally used in this occasion for m2m and virtual model fields. For complete rationale, see this module's docstring. """ def __init__(self, *args, **kwargs): """Override that uses a form field's ``value_from_object()``.""" super(FutureModelForm, self).__init__(*args, **kwargs) for name, field in self.fields.items(): if not hasattr(field, 'value_from_object'): continue self.initial[name] = field.value_from_object(self.instance, name) def _post_clean(self): """Override that uses the form field's ``save_object_data()``.""" super(FutureModelForm, self)._post_clean() for name, field in self.fields.items(): if not hasattr(field, 'save_object_data'): continue field.save_object_data( self.instance, name, self.cleaned_data.get(name, None), ) def _save_m2m(self): # noqa """Override that uses the form field's ``save_object_data()``.""" cleaned_data = self.cleaned_data exclude = self._meta.exclude fields = self._meta.fields opts = self.instance._meta # Added to give the field a chance to do the work handled = [] for name, field in self.fields.items(): if not hasattr(field, 'save_relation_data'): continue field.save_relation_data( self.instance, name, cleaned_data[name] ) handled.append(name) # Note that for historical reasons we want to include also # virtual_fields here. (GenericRelation was previously a fake # m2m field). for f in chain(opts.many_to_many, opts.virtual_fields): # Added to give the form field a chance to do the work if f.name in handled: continue if not hasattr(f, 'save_form_data'): continue if fields and f.name not in fields: continue if exclude and f.name in exclude: continue if f.name in cleaned_data: f.save_form_data(self.instance, cleaned_data[f.name])
[docs] def save(self, commit=True): """Backport from Django 1.9+ for 1.8.""" if self.errors: raise ValueError( "The %s could not be %s because the data didn't validate." % ( self.instance._meta.object_name, 'created' if self.instance._state.adding else 'changed', ) ) if commit: # If committing, save the instance and the m2m data immediately. self.instance.save() self._save_m2m() else: # If not committing, add a method to the form to allow deferred # saving of m2m data. self.save_m2m = self._save_m2m return self.instance