diff --git a/docs/topics/pages.rst b/docs/topics/pages.rst index a43364c128..3e01141966 100644 --- a/docs/topics/pages.rst +++ b/docs/topics/pages.rst @@ -361,15 +361,45 @@ To add this to the admin interface, use the :class:`~wagtail.wagtailadmin.edit_h The first argument must match the value of the ``related_name`` attribute of the ``ParentalKey``. -Database representation -======================= +Working with pages +================== -Querying pages -============== +Wagtail uses Django's `multi-table inheritance `_ feature to allow multiple page models to be used in the same tree. -TODO: In these two sections, we must describe multi-table inheritance... +Each page is added to both Wagtail's builtin :class:`~wagtail.wagtailcore.models.Page` model as well as it's user-defined model (such as the ``BlogPage`` model created earlier). + +Pages can exist in Python code in two forms, an instance of ``Page`` or an instance of the page model. + + When working with multiple page types together, you will typically use instances of Wagtail's :class:`~wagtail.wagtailcore.models.Page` model, which doesn't give you access to any fields specific to their type. + +.. code-block:: python + + # Get all pages in the database + >>> from wagtail.wagtailcore.models import Page + >>> Page.objects.all() + [, , , , ] + +When working with a single page type, you can work with instances of the user-defined model that gives access to all the fields available in ``Page`` and any user defined fields for that type. + +.. code-block:: python + + # Get all blog entries in the database + >>> BlogPage.objects.all() + [, ] + +You can convert a ``Page`` object to a specific object using the ``.specific`` property (this may require performing a query each time you use it). + +.. code-block:: python + + >>> page = Page.objects.get(title="A Blog post") + >>> page + + + # Note: the blog post is an instance of Page so we cannot access body, date or feed_image + + >>> page.specific + -NOTE: The reason I renamed this to "page models" is because I think it would be a good place to also describe "general usage" of pages, such as finding the specific object, the url or overriding the template/template context. I think that things like creating pages programmatically probably should be documented elsewhere but linked to from here. Tips ====