From d1bc198e00d7b268b905158e092e3911bb9140f4 Mon Sep 17 00:00:00 2001 From: Brian Rosner Date: Wed, 11 Jun 2008 20:28:37 +0000 Subject: [PATCH] newforms-admin: Added inline documentation. git-svn-id: http://code.djangoproject.com/svn/django/branches/newforms-admin@7617 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/admin.txt | 113 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 113 insertions(+) diff --git a/docs/admin.txt b/docs/admin.txt index 32476aae5f..b4e32b4e72 100644 --- a/docs/admin.txt +++ b/docs/admin.txt @@ -330,6 +330,11 @@ For more on ``select_related()``, see `the select_related() docs`_. .. _the select_related() docs: ../db-api/#select-related +``inlines`` +----------- + +See ``InlineModelAdmin`` objects below. + ``ordering`` ------------ @@ -422,6 +427,114 @@ with an operator: Performs a full-text match. This is like the default search method but uses an index. Currently this is only available for MySQL. +``InlineModelAdmin`` objects +============================ + +The admin interface has the ability to edit models on the same page as a +parent model. These are called inlines. You can add them a model being +specifing them in a ``ModelAdmin.inlines`` attribute:: + + class BookInline(admin.TabularInline): + model = Book + + class AuthorAdmin(admin.ModelAdmin): + inlines = [ + BookInline, + ] + +Django provides two subclasses of ``InlineModelAdmin`` and they are:: + + * ``TabularInline`` + * ``StackedInline`` + +The difference between these two is merely the template used to render them. + +``InlineModelAdmin`` options +----------------------------- + +The ``InlineModelAdmin`` class is a subclass of ``ModelAdmin`` so it inherits +all the same functionality as well as some of its own: + +``model`` +~~~~~~~~~ + +The model in which the inline is using. This is required. + +``fk_name`` +~~~~~~~~~~~ + +The name of the foreign key on the model. In most cases this will be dealt +with automatically, but ``fk_name`` must be specified explicitly if there are +more than one foreign key to the same parent model. + +``formset`` +~~~~~~~~~~~ + +This defaults to ``BaseInlineFormset``. Using your own formset can give you +many possibilities of customization. Inlines are built around +`model formsets`_. + +.. _model formsets: ../modelforms/# + +``form`` +~~~~~~~~ + +The value for ``form`` is inherited from ``ModelAdmin``. This is what is +passed through to ``formset_factory`` when creating the formset for this +inline. + +``extra`` +~~~~~~~~~ + +This controls the number of extra forms the formset will display in addition +to the initial forms. See `extra in formsets`_ for more information. + +``max_num`` +~~~~~~~~~~~ + +This controls the maximum number of forms to show in the inline. This doesn't +directly corrolate to the number of objects, but can if the value is small +enough. See `max_num in model formsets`_ for more information. + +``template`` +~~~~~~~~~~~~ + +The template used to render the inline on the page. + +``verbose_name`` +~~~~~~~~~~~~~~~~ + +An override to the ``verbose_name`` found in the model's inner ``Meta`` class. + +``verbose_name_plural`` +~~~~~~~~~~~~~~~~~~~~~~~ + +An override to the ``verbose_name_plural`` found in the model's inner ``Meta`` +class. + +Working with a model with two or more foreign keys to the same parent model +--------------------------------------------------------------------------- + +It is sometimes possible to have more than one foreign key to the same model. +Take this model for instance:: + + class Friendship(models.Model): + to_person = models.ForeignKey(Person, related_name="friends") + from_person = models.ForeignKey(Person, related_name="from_friends") + +If you wanted to display an inline on the ``Person`` admin add/change pages +you need to explicitly define the foreign key since it is unable to do so +automatically:: + + class FriendshipInline(admin.TabularInline): + model = Friendship + fk_name = "to_person" + + class PersonAdmin(admin.ModelAdmin): + inlines = [ + FriendshipInline, + ] + ``AdminSite`` objects =====================