Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #13524 -- Added backwards compatibility and feature notes regar…

…ding admin inlines and formsets. Thanks to Ramiro Morales and Gabriel Hurley.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@13241 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit d0d3e6792da9e716e547f23dfd44706d2bab3c8e 1 parent b8ed827
Russell Keith-Magee authored
13  docs/ref/contrib/admin/index.txt
@@ -1053,6 +1053,8 @@ The value for ``form`` defaults to ``ModelForm``. This is what is
1053 1053
 passed through to ``inlineformset_factory`` when creating the formset for this
1054 1054
 inline.
1055 1055
 
  1056
+.. _ref-contrib-admin-inline-extra:
  1057
+
1056 1058
 ``extra``
1057 1059
 ~~~~~~~~~
1058 1060
 
@@ -1062,8 +1064,15 @@ to the initial forms. See the
1062 1064
 
1063 1065
 .. versionadded:: 1.2
1064 1066
 
1065  
-Extra forms for inlines will be hidden and replaced with a link to dynamically
1066  
-add any number of new inlines for users with Javascript enabled.
  1067
+For users with JavaScript-enabled browsers, an "Add another" link is
  1068
+provided to enable any number of additional inlines to be added in
  1069
+addition to those provided as a result of the ``extra`` argument.
  1070
+
  1071
+The dynamic link will not appear if the number of currently displayed
  1072
+forms exceeds ``max_num``, or if the user does not have JavaScript
  1073
+enabled.
  1074
+
  1075
+.. _ref-contrib-admin-inline-max-num:
1067 1076
 
1068 1077
 ``max_num``
1069 1078
 ~~~~~~~~~~~
53  docs/releases/1.2.txt
@@ -351,6 +351,39 @@ people this shouldn't have been a problem because ``bool`` is a subclass of
351 351
 only time this should ever be an issue is if you were expecting printing the
352 352
 ``repr`` of a ``BooleanField`` to print ``1`` or ``0``.
353 353
 
  354
+Changes to the interpretation of``max_num`` in FormSets
  355
+-------------------------------------------------------
  356
+
  357
+As part of enhancements made to the handling of FormSets, the default
  358
+value and interpretation of the ``max_num`` parameter to the
  359
+:ref:`django.forms.formsets.formset_factory() <formsets-max-num>` and
  360
+:ref:`django.forms.models.modelformset_factory()
  361
+<model-formsets-max-num>` functions has changed slightly. This
  362
+change also affects the way the ``max_num`` argument is :ref:`used for
  363
+inline admin objects <ref-contrib-admin-inline-max-num>`
  364
+
  365
+Previously, the default value for ``max_num`` was ``0`` (zero).
  366
+FormSets then used the boolean value of ``max_num`` to determine if a
  367
+limit was to be imposed on the number of generated forms. The default
  368
+value of ``0`` meant that there was no default limit on the number of
  369
+forms in a FormSet.
  370
+
  371
+Starting with 1.2, the default value for ``max_num`` has been changed
  372
+to ``None``, and FormSets will differentiate between a value of
  373
+``None`` and a value of ``0``. A value of ``None`` indicates that no
  374
+limit on the number of forms is to be imposed; a value of ``0``
  375
+indicates that a maximum of 0 forms should be imposed. This doesn't
  376
+necessarily mean that no forms will be displayed -- see the
  377
+:ref:`ModelFormSet documentation <model-formsets-max-num>` for more
  378
+details.
  379
+
  380
+If you were manually specifying a value of ``0`` for ``max_num``, you
  381
+will need to update your FormSet and/or admin definitions.
  382
+
  383
+.. seealso::
  384
+
  385
+    :ref:`1.2-js-assisted-inlines`
  386
+
354 387
 .. _deprecated-features-1.2:
355 388
 
356 389
 Features deprecated in 1.2
@@ -611,7 +644,7 @@ were affected by these changes.
611 644
 ``SpatialBackend``
612 645
 ^^^^^^^^^^^^^^^^^^
613 646
 
614  
-Prior to the creation of the separate spatial backends, the 
  647
+Prior to the creation of the separate spatial backends, the
615 648
 ``django.contrib.gis.db.backend.SpatialBackend`` object was
616 649
 provided as an abstraction to introspect on the capabilities of
617 650
 the spatial database.  All of the attributes and routines provided by
@@ -678,6 +711,11 @@ for your spatial database use the methods provided by the spatial backend::
678 711
         sr_qs = SpatialRefSys.objects.using('my_spatialite').filter(...)
679 712
         gc_qs = GeometryColumns.objects.using('my_postgis').filter(...)
680 713
 
  714
+Language code ``no``
  715
+--------------------
  716
+
  717
+The currently used language code for Norwegian Bokmål ``no`` is being
  718
+replaced by the more common language code ``nb``.
681 719
 
682 720
 What's new in Django 1.2
683 721
 ========================
@@ -923,9 +961,12 @@ Finally, :ref:`GeoDjango's documentation <ref-contrib-gis>` is now
923 961
 included with Django's and is no longer
924 962
 hosted separately at `geodjango.org <http://geodjango.org/>`_.
925 963
 
926  
-Deprecation of old language code ``no``
927  
----------------------------------------
  964
+.. _1.2-js-assisted-inlines:
928 965
 
929  
-The currently used language code for Norwegian Bokmål ``no`` is being
930  
-replaced by the more common language code ``nb``, which should be updated
931  
-by translators from now on.
  966
+JavaScript-assisted handling of inline related objects in the admin
  967
+-------------------------------------------------------------------
  968
+
  969
+If a user has JavaScript enabled in their browser, the interface for
  970
+inline objects in the admin now allows inline objects to be
  971
+dynamically added and removed. Users without JavaScript-enabled
  972
+browsers will see no change in the behavior of inline objects.
9  docs/topics/forms/formsets.txt
@@ -68,6 +68,8 @@ list of dictionaries as the initial data.
68 68
 
69 69
     :ref:`Creating formsets from models with model formsets <model-formsets>`.
70 70
 
  71
+.. _formsets-max-num:
  72
+
71 73
 Limiting the maximum number of forms
72 74
 ------------------------------------
73 75
 
@@ -83,7 +85,7 @@ limit the maximum number of empty forms the formset will display::
83 85
 
84 86
 .. versionchanged:: 1.2
85 87
 
86  
-If the value of ``max_num`` is geater than the number of existing related
  88
+If the value of ``max_num`` is greater than the number of existing
87 89
 objects, up to ``extra`` additional blank forms will be added to the formset,
88 90
 so long as the total number of forms does not exceed ``max_num``.
89 91
 
@@ -91,11 +93,6 @@ A ``max_num`` value of ``None`` (the default) puts no limit on the number of
91 93
 forms displayed. Please note that the default value of ``max_num`` was changed
92 94
 from ``0`` to ``None`` in version 1.2 to allow ``0`` as a valid value.
93 95
 
94  
-.. versionadded:: 1.2
95  
-
96  
-The dynamic "Add Another" link in the Django admin will not appear if
97  
-``max_num`` is less than the number of currently displayed forms.
98  
-
99 96
 Formset validation
100 97
 ------------------
101 98
 
4  docs/topics/forms/modelforms.txt
@@ -661,8 +661,8 @@ Limiting the number of editable objects
661 661
 
662 662
 .. versionchanged:: 1.2
663 663
 
664  
-As with regular formsets, you can use the ``max_num`` parameter to
665  
-``modelformset_factory`` to limit the number of extra forms displayed.
  664
+As with regular formsets, you can use the ``max_num`` and ``extra`` parameters
  665
+to ``modelformset_factory`` to limit the number of extra forms displayed.
666 666
 
667 667
 ``max_num`` does not prevent existing objects from being displayed::
668 668
 
6  tests/modeltests/model_formsets/models.py
@@ -368,16 +368,22 @@ def __unicode__(self):
368 368
 
369 369
 >>> AuthorFormSet = modelformset_factory(Author, max_num=None, extra=3)
370 370
 >>> formset = AuthorFormSet(queryset=qs)
  371
+>>> len(formset.forms)
  372
+6
371 373
 >>> len(formset.extra_forms)
372 374
 3
373 375
 
374 376
 >>> AuthorFormSet = modelformset_factory(Author, max_num=4, extra=3)
375 377
 >>> formset = AuthorFormSet(queryset=qs)
  378
+>>> len(formset.forms)
  379
+4
376 380
 >>> len(formset.extra_forms)
377 381
 1
378 382
 
379 383
 >>> AuthorFormSet = modelformset_factory(Author, max_num=0, extra=3)
380 384
 >>> formset = AuthorFormSet(queryset=qs)
  385
+>>> len(formset.forms)
  386
+3
381 387
 >>> len(formset.extra_forms)
382 388
 0
383 389
 
46  tests/regressiontests/forms/formsets.py
@@ -599,6 +599,24 @@
599 599
 
600 600
 # Base case for max_num.
601 601
 
  602
+# When not passed, max_num will take its default value of None, i.e. unlimited
  603
+# number of forms, only controlled by the value of the extra parameter.
  604
+
  605
+>>> LimitedFavoriteDrinkFormSet = formset_factory(FavoriteDrinkForm, extra=3)
  606
+>>> formset = LimitedFavoriteDrinkFormSet()
  607
+>>> for form in formset.forms:
  608
+...     print form
  609
+<tr><th><label for="id_form-0-name">Name:</label></th><td><input type="text" name="form-0-name" id="id_form-0-name" /></td></tr>
  610
+<tr><th><label for="id_form-1-name">Name:</label></th><td><input type="text" name="form-1-name" id="id_form-1-name" /></td></tr>
  611
+<tr><th><label for="id_form-2-name">Name:</label></th><td><input type="text" name="form-2-name" id="id_form-2-name" /></td></tr>
  612
+
  613
+# If max_num is 0 then no form is rendered at all.
  614
+
  615
+>>> LimitedFavoriteDrinkFormSet = formset_factory(FavoriteDrinkForm, extra=3, max_num=0)
  616
+>>> formset = LimitedFavoriteDrinkFormSet()
  617
+>>> for form in formset.forms:
  618
+...     print form
  619
+
602 620
 >>> LimitedFavoriteDrinkFormSet = formset_factory(FavoriteDrinkForm, extra=5, max_num=2)
603 621
 >>> formset = LimitedFavoriteDrinkFormSet()
604 622
 >>> for form in formset.forms:
@@ -606,7 +624,7 @@
606 624
 <tr><th><label for="id_form-0-name">Name:</label></th><td><input type="text" name="form-0-name" id="id_form-0-name" /></td></tr>
607 625
 <tr><th><label for="id_form-1-name">Name:</label></th><td><input type="text" name="form-1-name" id="id_form-1-name" /></td></tr>
608 626
 
609  
-# Ensure the that max_num has no affect when extra is less than max_forms.
  627
+# Ensure that max_num has no effect when extra is less than max_num.
610 628
 
611 629
 >>> LimitedFavoriteDrinkFormSet = formset_factory(FavoriteDrinkForm, extra=1, max_num=2)
612 630
 >>> formset = LimitedFavoriteDrinkFormSet()
@@ -616,6 +634,32 @@
616 634
 
617 635
 # max_num with initial data
618 636
 
  637
+# When not passed, max_num will take its default value of None, i.e. unlimited
  638
+# number of forms, only controlled by the values of the initial and extra
  639
+# parameters.
  640
+
  641
+>>> initial = [
  642
+...     {'name': 'Fernet and Coke'},
  643
+... ]
  644
+>>> LimitedFavoriteDrinkFormSet = formset_factory(FavoriteDrinkForm, extra=1)
  645
+>>> formset = LimitedFavoriteDrinkFormSet(initial=initial)
  646
+>>> for form in formset.forms:
  647
+...     print form
  648
+<tr><th><label for="id_form-0-name">Name:</label></th><td><input type="text" name="form-0-name" value="Fernet and Coke" id="id_form-0-name" /></td></tr>
  649
+<tr><th><label for="id_form-1-name">Name:</label></th><td><input type="text" name="form-1-name" id="id_form-1-name" /></td></tr>
  650
+
  651
+# If max_num is 0 then no form is rendered at all, even if extra and initial
  652
+# are specified.
  653
+
  654
+>>> initial = [
  655
+...     {'name': 'Fernet and Coke'},
  656
+...     {'name': 'Bloody Mary'},
  657
+... ]
  658
+>>> LimitedFavoriteDrinkFormSet = formset_factory(FavoriteDrinkForm, extra=1, max_num=0)
  659
+>>> formset = LimitedFavoriteDrinkFormSet(initial=initial)
  660
+>>> for form in formset.forms:
  661
+...     print form
  662
+
619 663
 # More initial forms than max_num will result in only the first max_num of
620 664
 # them to be displayed with no extra forms.
621 665
 

0 notes on commit d0d3e67

Please sign in to comment.
Something went wrong with that request. Please try again.