27

Given an example like this:

class MyForm(forms.Form): 
    name = forms.CharField()

I'm trying to grasp what the difference between the following two snippets is:

"Bound Data" style:

my_form = MyForm({'name': request.user.first_name})

"Initial data" style:

my_form = MyForm(initial={'name': request.user.first_name})

The documentation seems to suggest than "initial is for dynamic initial values", and yet being able to pass "bound data" to the constructor accomplishes exactly the same thing. I've used initial data in the past for dynamic values, but I'm tempted to use the more straightforward "bound data" style, but would like some insights about what the real difference between these two styles is.

slacy
  • 11,397
  • 8
  • 56
  • 61

3 Answers3

47

Here's the key part from the django docs on bound and unbound forms.

A Form instance is either bound to a set of data, or unbound:

  • If it’s bound to a set of data, it’s capable of validating that data and rendering the form as HTML with the data displayed in the HTML.
  • If it’s unbound, it cannot do validation (because there’s no data to validate!), but it can still render the blank form as HTML.

You can't really see the difference for the example form you gave, because the form is valid in the "bound data" style. Let's extend the form by adding an age field, then the difference will be more obvious.

class MyForm(forms.Form):
    name = forms.CharField()
    age = forms.IntegerField()

Bound form

my_form = MyForm({'name': request.user.first_name})

This form is invalid, because age is not specified. When you render the form in the template, you will see validation errors for the age field.

Unbound form with dynamic initial data

my_form = MyForm(initial={'name':request.user.first_name})

This form is unbound. Validation is not triggered, so there will not be any errors displayed when you render the template.

Community
  • 1
  • 1
Alasdair
  • 298,606
  • 55
  • 578
  • 516
  • 6
    In addition the format of `initial` and `data` can differ. If you use a prefix on your form what is passed as `data` will be expected to have the prefix in the key whereas the prefix is not expected in `initial`. – Bran Handley Apr 15 '13 at 16:48
  • 1
    @BranHandley thank you so much for pointing out this difference which leads to silent failures. Is there a reason for this or is it just some buggy feature? – e18r Dec 05 '15 at 23:17
8

No, that's not what the difference is (and I'd be interested to know where in the documentation you got that impression from). The difference is whether validation is performed.

Initial data does not trigger validation. This allows you, for example, to pre-fill certain fields but leave others empty, even though they are required. If you used bound data, you would get errors for those empty required fields even on the first viewing of that form, which would be annoying for the user.

Bound data, of course, triggers validation. Also, if you're using a modelform, the related instance will only be updated with bound data, not initial data.

Daniel Roseman
  • 588,541
  • 66
  • 880
  • 895
4

Another difference is that data expects something that widgets can parse whereas initial is per-field. This makes a difference if you e.g. use MultiWidgets. In such case data should contain something like 

{'myfield_0': 'data for subwidget 0', 
 'myfield_1': 'data for subwidget 1'}

whereas initial expects something like this:

{'myfield': 'data for subwidget 0,data for subwidget 1'}
Tomasz Zieliński
  • 16,136
  • 7
  • 59
  • 83