docs start for formset/inline support

polymorphic/admin/childadmin.py

@@ -6,8 +6,10 @@ from django.core.urlresolvers import resolve
 from django.utils import six
 from django.utils.translation import ugettext_lazy as _
 
+from .helpers import PolymorphicInlineSupportMixin
 
-class PolymorphicChildModelAdmin(admin.ModelAdmin):
+
+class PolymorphicChildModelAdmin(PolymorphicInlineSupportMixin, admin.ModelAdmin):
     """
     The *optional* base class for the admin interface of derived models.
 

polymorphic/admin/filters.py

@@ -7,6 +7,12 @@ class PolymorphicChildModelFilter(admin.SimpleListFilter):
     """
     An admin list filter for the PolymorphicParentModelAdmin which enables
     filtering by its child models.
+
+    This can be used in the parent admin:
+
+    .. code-block:: python
+
+        list_filter = (PolymorphicChildModelFilter,)
     """
     title = _('Type')
     parameter_name = 'polymorphic_ctype'

polymorphic/admin/helpers.py

@@ -5,7 +5,7 @@ This makes sure that admin fieldsets/layout settings are exported to the templat
 """
 from django.contrib.admin.helpers import InlineAdminFormSet, InlineAdminForm
 
-from ..formsets import BasePolymorphicModelFormSet
+from polymorphic.formsets import BasePolymorphicModelFormSet
 
 
 class InlinePolymorphicAdminForm(InlineAdminForm):
@@ -75,6 +75,14 @@ class InlinePolymorphicAdminFormSet(InlineAdminFormSet):
 class PolymorphicInlineSupportMixin(object):
     """
     A Mixin to add to the regular admin, so it can work with our polymorphic inlines.
+
+    This mixin needs to be included in the admin that hosts the ``inlines``.
+    It makes sure the generated admin forms have different fieldsets/fields
+    depending on the polymorphic type of the form instance.
+
+    This is achieved by overwriting :func:`get_inline_formsets` to return
+    an :class:`InlinePolymorphicAdminFormSet` instead of a standard Django
+    :class:`~django.contrib.admin.helpers.InlineAdminFormSet` for the polymorphic formsets.
     """
 
     def get_inline_formsets(self, request, formsets, inline_instances, obj=None):
@@ -88,7 +96,8 @@ class PolymorphicInlineSupportMixin(object):
 
         for admin_formset in inline_admin_formsets:
             if isinstance(admin_formset.formset, BasePolymorphicModelFormSet):
-                # Downcast the admin
+                # This is a polymorphic formset, which belongs to our inline.
+                # Downcast the admin wrapper that generates the form fields.
                 admin_formset.__class__ = InlinePolymorphicAdminFormSet
                 admin_formset.request = request
                 admin_formset.obj = obj

polymorphic/admin/inlines.py

@@ -17,11 +17,10 @@ class PolymorphicParentInlineModelAdmin(InlineModelAdmin):
     """
     A polymorphic inline, where each formset row can be a different form.
 
-    Note that
+    Note that:
 
     * Permissions are only checked on the base model.
     * The child inlines can't override the base model fields, only this parent inline can do that.
-    * Child formset media is not yet processed.
     """
     formset = BasePolymorphicInlineFormSet
 
@@ -79,7 +78,7 @@ class PolymorphicParentInlineModelAdmin(InlineModelAdmin):
 
         # Instead of completely redefining super().get_formset(), we use
         # the regular inlineformset_factory(), and amend that with our extra bits.
-        # This is identical to what polymorphic_inlineformset_factory() does.
+        # This code line is the essence of what polymorphic_inlineformset_factory() does.
         FormSet.child_forms = polymorphic_child_forms_factory(
             formset_children=self.get_formset_children(request, obj=obj)
         )