diff --git a/docs/topics/pages.rst b/docs/topics/pages.rst index fb0e771a6e..a43364c128 100644 --- a/docs/topics/pages.rst +++ b/docs/topics/pages.rst @@ -308,10 +308,57 @@ For example, this can be overriden to make the ``BlogPage`` model respond with a }) -Child models -============ +Inline models +============= -TODO: https://pypi.python.org/pypi/django-modelcluster +Wagtail can nest the content of other models within the page. This is useful for creating repeated fields, such as related links or items to display in a carousel. Inline model content is also versioned with the rest of the page content. + +Each inline model requires the following: + + - It must inherit from :class:`wagtail.wagtailcore.models.Orderable` + - It must have a ``ParentalKey`` to the parent model + +.. note:: django-modelcluster and ParentalKey + + The model inlining feature is provided to by `django-modelcluster `_ and the ``ParentalKey`` field type must be imported from there: + + ..code-block:: python + + from modelcluster.fields import ParentalKey + + ``ParentalKey`` is a subclass of Django's ``ForeignKey`` and takes the same arguments + + +For example, the following inline model can be used to add related links (a list of name, url pairs) to the ``BlogPage`` model: + +.. code-block:: python + + from django.db import models + from modelcluster.fields import ParentalKey + from wagtail.wagtailcore.models import Orderable + + + class BlogPageRelatedLink(Orderable): + page = ParentalKey(BlogPage, related_name='related_links') + name = models.CharField(max_length=255) + url = models.URLField() + + panels = [ + FieldPanel('name'), + FieldPanel('url'), + ] + +To add this to the admin interface, use the :class:`~wagtail.wagtailadmin.edit_handlers.InlinePanel` edit panel class: + +.. code-block:: python + + content_panels = [ + ... + + InlinePanel('related_links', label="Related links"), + ] + +The first argument must match the value of the ``related_name`` attribute of the ``ParentalKey``. Database representation