Ticket #8387: get_form+get_fieldsets-docs-01.diff

docs/ref/contrib/admin.txt

@@ -587 +587 @@
                 instance.save()
             formset.save_m2m()
 
+``get_form(self, request, obj=None, **kwargs)``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``get_form`` method is given the ``HttpRequest`` and a model
+instance, but only if the user is changing the object. It can also be passed
+keyword arguments to be used as attributes for the ``ModelForm.Meta``
+class. The return value is a ``ModelForm``.
+
+For example to dynamically add another field to the form when the user has extra rights::
+
+    class MyModelAdminForm(forms.ModelForm):
+        class Meta:
+            model = MyModel
+        extra_option = forms.BooleanField()
+    
+    class MyModelAdmin(admin.ModelAdmin):
+        def get_form(self, request, obj=None, **kwargs):
+            if request.user.has_perm("myapp.can_use_extra_option"):
+                return MyModelAdminForm
+            return super(MyModelAdmin, self).get_form(request, obj, **kwargs)
+
+``get_fieldsets(self, request, obj=None)``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``get_fieldsets`` method is given the ``HttpRequest`` and a model
+instance, but only if the user is changing the object. It returns the fieldsets
+in the same format they are specified in the ``fieldsets`` attribute.
+
+For example to display a smaller set of fields when the user is changing
+rather than adding::
+
+    class MyModelAdmin(admin.ModelAdmin):
+        def get_fieldsets(self, request, obj=None):
+            if obj:
+                return [(None, {'fields': ('field_c', 'field_b')})]
+            return [(None, {'fields': ('field_a', 'field_b', 'field_c')})]
+    
+        def get_form(self, request, obj=None, **kwargs):
+            if obj:
+                defaults = {'exclude': ('field_a',)}
+            else:
+                defaults = {}
+            defaults.update(kwargs)
+            return super(MyModelAdmin, self).get_form(request, obj, **defaults)
+
+.. admonition:: Note
+
+    If you return only a subset of your models fields in ``get_fieldsets`` you need
+    to override ``get_form`` as well and set the ``fields`` or ``exclude`` attribute.
+    Otherwise the form will expect *all* fields to be present and will either raise
+    validation errors on the missing fields or clear them if they have ``blank=True``.
+
 ``ModelAdmin`` media definitions
 --------------------------------