Model Reference¶
This document contains reference information for the model classes inside the wagtailcore
module.
Page
¶
Database fields¶
-
class
wagtail.core.models.
Page
¶ -
title
¶ (text)
Human-readable title of the page.
-
draft_title
¶ (text)
Human-readable title of the page, incorporating any changes that have been made in a draft edit (in contrast to the
title
field, which for published pages will be the title as it exists in the current published version).
-
slug
¶ (text)
This is used for constructing the page’s URL.
For example:
http://domain.com/blog/[my-slug]/
-
content_type
¶ (foreign key to
django.contrib.contenttypes.models.ContentType
)A foreign key to the
ContentType
object that represents the specific model of this page.
-
live
¶ (boolean)
A boolean that is set to
True
if the page is published.Note: this field defaults to
True
meaning that any pages that are created programmatically will be published by default.
-
has_unpublished_changes
¶ (boolean)
A boolean that is set to
True
when the page is either in draft or published with draft changes.
-
owner
¶ (foreign key to user model)
A foreign key to the user that created the page.
-
first_published_at
¶ (date/time)
The date/time when the page was first published.
-
last_published_at
¶ (date/time)
The date/time when the page was last published.
-
seo_title
¶ (text)
Alternate SEO-crafted title, for use in the page’s
<title>
HTML tag.
-
search_description
¶ (text)
SEO-crafted description of the content, used for search indexing. This is also suitable for the page’s
<meta name="description">
HTML tag.
(boolean)
Toggles whether the page should be included in site-wide menus.
This is used by the
in_menu()
QuerySet filter.Defaults to
False
and can be overridden on the model withshow_in_menus_default = True
.Note
To set the global default for all pages, set
Page.show_in_menus_default = True
once where you first import thePage
model.
-
Methods and properties¶
In addition to the model fields provided, Page
has many properties and methods that you may wish to reference, use, or override in creating your own models.
Note
See also django-treebeard’s node API. Page
is a subclass of materialized path tree nodes.
-
class
wagtail.core.models.
Page
-
specific
¶ Return this page in its most specific subclassed form.
-
specific_class
¶ Return the class that this page would be if instantiated in its most specific form
-
get_url
(request=None, current_site=None)¶ Return the ‘most appropriate’ URL for referring to this page from the pages we serve, within the Wagtail backend and actual website templates; this is the local URL (starting with ‘/’) if we’re only running a single site (i.e. we know that whatever the current page is being served from, this link will be on the same domain), and the full URL (with domain) if not. Return None if the page is not routable.
Accepts an optional but recommended
request
keyword argument that, if provided, will be used to cache site-level URL information (thereby avoiding repeated database / cache lookups) and, via therequest.site
attribute, determine whether a relative or full URL is most appropriate.
-
full_url
¶ Return the full URL (including protocol / domain) to this page, or None if it is not routable
-
relative_url
(current_site, request=None)¶ Return the ‘most appropriate’ URL for this page taking into account the site we’re currently on; a local URL if the site matches, or a fully qualified one otherwise. Return None if the page is not routable.
Accepts an optional but recommended
request
keyword argument that, if provided, will be used to cache site-level URL information (thereby avoiding repeated database / cache lookups).
-
get_site
()¶ Return the Site object that this page belongs to.
-
get_url_parts
(request=None)¶ Determine the URL for this page and return it as a tuple of
(site_id, site_root_url, page_url_relative_to_site_root)
. Return None if the page is not routable.This is used internally by the
full_url
,url
,relative_url
andget_site
properties and methods; pages with custom URL routing should override this method in order to have those operations return the custom URLs.Accepts an optional keyword argument
request
, which may be used to avoid repeated database / cache lookups. Typically, a page model that overridesget_url_parts
should not need to deal withrequest
directly, and should just pass it to the original method when callingsuper
.
-
route
(request, path_components)¶
-
serve
(request, *args, **kwargs)¶
-
get_context
(request, *args, **kwargs)¶
-
get_template
(request, *args, **kwargs)¶
-
get_admin_display_title
()¶ Return the title for this page as it should appear in the admin backend; override this if you wish to display extra contextual information about the page, such as language. By default, returns
draft_title
.
-
preview_modes
¶ A list of (internal_name, display_name) tuples for the modes in which this page can be displayed for preview/moderation purposes. Ordinarily a page will only have one display mode, but subclasses of Page can override this - for example, a page containing a form might have a default view of the form, and a post-submission ‘thankyou’ page
-
serve_preview
(request, mode_name)¶ Return an HTTP response for use in page previews. Normally this would be equivalent to self.serve(request), since we obviously want the preview to be indicative of how it looks on the live site. However, there are a couple of cases where this is not appropriate, and custom behaviour is required:
1) The page has custom routing logic that derives some additional required args/kwargs to be passed to serve(). The routing mechanism is bypassed when previewing, so there’s no way to know what args we should pass. In such a case, the page model needs to implement its own version of serve_preview.
2) The page has several different renderings that we would like to be able to see when previewing - for example, a form page might have one rendering that displays the form, and another rendering to display a landing page when the form is posted. This can be done by setting a custom preview_modes list on the page model - Wagtail will allow the user to specify one of those modes when previewing, and pass the chosen mode_name to serve_preview so that the page model can decide how to render it appropriately. (Page models that do not specify their own preview_modes list will always receive an empty string as mode_name.)
Any templates rendered during this process should use the ‘request’ object passed here - this ensures that request.user and other properties are set appropriately for the wagtail user bar to be displayed. This request will always be a GET.
-
get_parent
(update=False)¶ Returns: the parent node of the current node object. Caches the result in the object itself to help in loops.
-
get_ancestors
(inclusive=False)¶ Returns a queryset of the current page’s ancestors, starting at the root page and descending to the parent, or to the current page itself if
inclusive
is true.
-
get_descendants
(inclusive=False)¶ Returns a queryset of all pages underneath the current page, any number of levels deep. If
inclusive
is true, the current page itself is included in the queryset.
-
get_siblings
(inclusive=True)¶ Returns a queryset of all other pages with the same parent as the current page. If
inclusive
is true, the current page itself is included in the queryset.
-
search_fields
¶ A list of fields to be indexed by the search engine. See Search docs Indexing extra fields
-
subpage_types
¶ A whitelist of page models which can be created as children of this page type. For example, a
BlogIndex
page might allow aBlogPage
as a child, but not aJobPage
:class BlogIndex(Page): subpage_types = ['mysite.BlogPage', 'mysite.BlogArchivePage']
The creation of child pages can be blocked altogether for a given page by setting it’s subpage_types attribute to an empty array:
class BlogPage(Page): subpage_types = []
-
parent_page_types
¶ A whitelist of page models which are allowed as parent page types. For example, a
BlogPage
may only allow itself to be created below theBlogIndex
page:class BlogPage(Page): parent_page_types = ['mysite.BlogIndexPage']
Pages can block themselves from being created at all by setting parent_page_types to an empty array (this is useful for creating unique pages that should only be created once):
class HiddenPage(Page): parent_page_types = []
-
classmethod
can_exist_under
(parent)¶ Checks if this page type can exist as a subpage under a parent page instance.
See also:
Page.can_create_at()
andPage.can_move_to()
-
classmethod
can_create_at
(parent)¶ Checks if this page type can be created as a subpage under a parent page instance.
-
can_move_to
(parent)¶ Checks if this page instance can be moved to be a subpage of a parent page instance.
-
password_required_template
¶ Defines which template file should be used to render the login form for Protected pages using this model. This overrides the default, defined using
PASSWORD_REQUIRED_TEMPLATE
in your settings. See Private pages
-
is_creatable
¶ Controls if this page can be created through the Wagtail administration. Defaults to
True
, and is not inherited by subclasses. This is useful when using multi-table inheritance, to stop the base model from being created as an actual page.
-
max_count
¶ Controls the maximum number of pages of this type that can be created through the Wagtail administration interface. This is useful when needing “allow at most 3 of these pages to exist”, or for singleton pages.
-
max_count_per_parent
¶ Controls the maximum number of pages of this type that can be created under any one parent page.
-
exclude_fields_in_copy
¶ An array of field names that will not be included when a Page is copied. Useful when you have relations that do not use ClusterableModel or should not be copied.
class BlogPage(Page): exclude_fields_in_copy = ['special_relation', 'custom_uuid']
The following fields will always be excluded in a copy - [‘id’, ‘path’, ‘depth’, ‘numchild’, ‘url_path’, ‘path’].
-
base_form_class
¶ The form class used as a base for editing Pages of this type in the Wagtail page editor. This attribute can be set on a model to customise the Page editor form. Forms must be a subclass of
WagtailAdminPageForm
. See Customising generated forms for more information.
-
with_content_json
(content_json)¶ Returns a new version of the page with field values updated to reflect changes in the provided
content_json
(which usually comes from a previously-saved page revision).Certain field values are preserved in order to prevent errors if the returned page is saved, such as
id
,content_type
and some tree-related values. The following field values are also preserved, as they are considered to be meaningful to the page as a whole, rather than to a specific revision:draft_title
live
has_unpublished_changes
owner
locked
latest_revision_created_at
first_published_at
-
Site
¶
The Site
model is useful for multi-site installations as it allows an administrator to configure which part of the tree to use for each hostname that the server responds on.
This configuration is used by the SiteMiddleware
middleware class which checks each request against this configuration and appends the Site object to the Django request object.
Database fields¶
-
class
wagtail.core.models.
Site
¶ -
hostname
¶ (text)
This is the hostname of the site, excluding the scheme, port and path.
For example:
www.mysite.com
Note
If you’re looking for how to get the root url of a site, use the
root_url
attribute.
-
port
¶ (number)
This is the port number that the site responds on.
-
site_name
¶ (text - optional)
A human-readable name for the site. This is not used by Wagtail itself, but is suitable for use on the site front-end, such as in
<title>
elements.For example:
Rod's World of Birds
-
root_page
¶ (foreign key to
Page
)This is a link to the root page of the site. This page will be what appears at the
/
URL on the site and would usually be a homepage.
-
is_default_site
¶ (boolean)
This is set to
True
if the site is the default. Only one site can be the default.The default site is used as a fallback in situations where a site with the required hostname/port couldn’t be found.
-
Methods and properties¶
-
class
wagtail.core.models.
Site
-
static
find_for_request
(request)¶ Find the site object responsible for responding to this HTTP request object. Try:
- unique hostname first
- then hostname and port
- if there is no matching hostname at all, or no matching hostname:port combination, fall back to the unique default site, or raise an exception
NB this means that high-numbered ports on an extant hostname may still be routed to a different hostname which is set as the default
-
root_url
¶ This returns the URL of the site. It is calculated from the
hostname
and theport
fields.The scheme part of the URL is calculated based on value of the
port
field:- 80 =
http://
- 443 =
https://
- Everything else will use the
http://
scheme and the port will be appended to the end of the hostname (eg.http://mysite.com:8000/
)
- 80 =
-
static
get_site_root_paths
()¶ Return a list of (id, root_path, root_url) tuples, most specific path first - used to translate url_paths into actual URLs with hostnames
-
static
PageRevision
¶
Every time a page is edited a new PageRevision
is created and saved to the database. It can be used to find the full history of all changes that have been made to a page and it also provides a place for new changes to be kept before going live.
- Revisions can be created from any
Page
object by calling itssave_revision()
method- The content of the page is JSON-serialised and stored in the
content_json
field- You can retrieve a
PageRevision
as aPage
object by calling theas_page_object()
method
Database fields¶
-
class
wagtail.core.models.
PageRevision
¶ -
-
submitted_for_moderation
¶ (boolean)
True
if this revision is in moderation
-
created_at
¶ (date/time)
This is the time the revision was created
-
user
¶ (foreign key to user model)
This links to the user that created the revision
-
content_json
¶ (text)
This field contains the JSON content for the page at the time the revision was created
-
Managers¶
-
class
wagtail.core.models.
PageRevision
-
objects
¶ This manager is used to retrieve all of the
PageRevision
objects in the databaseExample:
PageRevision.objects.all()
-
submitted_revisions
¶ This manager is used to retrieve all of the
PageRevision
objects that are awaiting moderator approvalExample:
PageRevision.submitted_revisions.all()
-
Methods and properties¶
-
class
wagtail.core.models.
PageRevision
-
-
approve_moderation
()¶ Calling this on a revision that’s in moderation will mark it as approved and publish it
-
reject_moderation
()¶ Calling this on a revision that’s in moderation will mark it as rejected
-
is_latest_revision
()¶ Returns
True
if this revision is its page’s latest revision
-
publish
()¶ Calling this will copy the content of this revision into the live page object. If the page is in draft, it will be published.
-