Model Reference

wagtail.core.models is split into submodules for maintainability. All definitions intended as public should be imported here (with ‘noqa’ comments as required) and outside code should continue to import them from wagtail.core.models (e.g. from wagtail.core.models import Site, not from wagtail.core.models.sites import Site.)

Submodules should take care to keep the direction of dependencies consistent; where possible they should implement low-level generic functionality which is then imported by higher-level models such as Page.

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.

show_in_menus

(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 with show_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 the Page model.

locked

(boolean)

When set to True, the Wagtail editor will not allow any users to edit the content of the page.

If locked_by is also set, only that user can edit the page.

locked_by

(foreign key to user model)

The user who has currently locked the page. Only this user can edit the page.

If this is None when locked is True, nobody can edit the page.

locked_at

(date/time)

The date/time when the page was locked.

alias_of

(foreign key to another page)

If set, this page is an alias of the page referenced in this field.

locale

(foreign key to Locale)

This foreign key links to the Locale object that represents the page language.

translation_key

(uuid)

A UUID that is shared between translations of a page. These are randomly generated when a new page is created and copied when a translation of a page is made.

A translation_key value can only be used on one page in each locale.

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
get_specific(deferred=False, copy_attrs=None, copy_attrs_exclude=None)

New in version 2.12.

Return this page in its most specific subclassed form.

Changed in version 2.13: * When copy_attrs is not supplied, all known non-field attribute values are copied to the returned object. Previously, no non-field values would be copied. * The copy_attrs_exclude option was added.

By default, a database query is made to fetch all field values for the specific object. If you only require access to custom methods or other non-field attributes on the specific object, you can use deferred=True to avoid this query. However, any attempts to access specific field values from the returned object will trigger additional database queries.

By default, references to all non-field attribute values are copied from current object to the returned one. This includes:

  • Values set by a queryset, for example: annotations, or values set as a result of using select_related() or prefetch_related().
  • Any cached_property values that have been evaluated.
  • Attributes set elsewhere in Python code.

For fine-grained control over which non-field values are copied to the returned object, you can use copy_attrs to specify a complete list of attribute names to include. Alternatively, you can use copy_attrs_exclude to specify a list of attribute names to exclude.

If called on a page object that is already an instance of the most specific class (e.g. an EventPage), the object will be returned as is, and no database queries or other operations will be triggered.

If the page was originally created using a page type that has since been removed from the codebase, a generic Page object will be returned (without any custom field values or other functionality present on the original class). Usually, deleting these pages is the best course of action, but there is currently no safe way for Wagtail to do that at migration time.

specific

Returns this page in its most specific subclassed form with all field values fetched from the database. The result is cached in memory.

specific_deferred

New in version 2.12.

Returns this page in its most specific subclassed form without any additional field values being fetched from the database. The result is cached in memory.

specific_class

Return the class that this page would be if instantiated in its most specific form.

If the model class can no longer be found in the codebase, and the relevant ContentType has been removed by a database migration, the return value will be None.

If the model class can no longer be found in the codebase, but the relevant ContentType is still present in the database (usually a result of switching between git branches without running or reverting database migrations beforehand), the return value will be None.

cached_content_type

New in version 2.10.

Return this page’s content_type value from the ContentType model’s cached manager, which will avoid a database query if the object is already in memory.

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 the Site.find_for_request() function, determine whether a relative or full URL is most appropriate.

get_full_url(request=None)

Return the full URL (including protocol / domain) to this page, or None if it is not routable

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 and get_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 overrides get_url_parts should not need to deal with request directly, and should just pass it to the original method when calling super.

route(request, path_components)
serve(request, *args, **kwargs)
context_object_name = None

Custom name for page instance in page’s Context.

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 ‘thank you’ 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.

get_translations(inclusive=False)

Returns a queryset containing the translations of this instance.

get_translation(locale)

Finds the translation in the specified locale.

If there is no translation in that locale, this raises a model.DoesNotExist exception.

get_translation_or_none(locale)

Finds the translation in the specified locale.

If there is no translation in that locale, this returns None.

has_translation(locale)

Returns True if a translation exists in the specified locale.

copy_for_translation(locale, copy_parents=False, alias=False, exclude_fields=None)

Creates a copy of this page in the specified locale.

The new page will be created in draft as a child of this page’s translated parent.

For example, if you are translating a blog post from English into French, this method will look for the French version of the blog index and create the French translation of the blog post under that.

If this page’s parent is not translated into the locale, then a ParentNotTranslatedError is raised. You can circumvent this error by passing copy_parents=True which copies any parents that are not translated yet.

The exclude_fields parameter can be used to set any fields to a blank value in the copy.

Note that this method calls the .copy() method internally so any fields that are excluded in .exclude_fields_in_copy will be excluded from the translation.

localized

Finds the translation in the current active language.

If there is no translation in the active language, self is returned.

Note: This will not return the translation if it is in draft. If you want to include drafts, use the .localized_draft attribute instead.

localized_draft

Finds the translation in the current active language.

If there is no translation in the active language, self is returned.

Note: This will return translations that are in draft. If you want to exclude these, use the .localized attribute.

search_fields

A list of fields to be indexed by the search engine. See Search docs Indexing extra fields

subpage_types

A list of page models which can be created as children of this page type. For example, a BlogIndex page might allow a BlogPage as a child, but not a JobPage:

class BlogIndex(Page):
    subpage_types = ['mysite.BlogPage', 'mysite.BlogArchivePage']

The creation of child pages can be blocked altogether for a given page by setting its subpage_types attribute to an empty array:

class BlogPage(Page):
    subpage_types = []
parent_page_types

A list of page models which are allowed as parent page types. For example, a BlogPage may only allow itself to be created below the BlogIndex 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 = []

To allow for a page to be only created under the root page (e.g. for HomePage models) set the parent_page_type to ['wagtailcore.Page'].

class HomePage(Page):
    parent_page_types = ['wagtailcore.Page']
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() and Page.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
  • locked_by
  • locked_at
  • latest_revision_created_at
  • first_published_at
  • alias_of
  • comments
save(clean=True, user=None, log_action=False, **kwargs)

Overrides default method behaviour to make additional updates unique to pages, such as updating the url_path value of descendant page to reflect changes to this page’s slug.

New pages should generally be saved via the add_child() or add_sibling() method of an existing page, which will correctly set the path and depth fields on the new page before saving it.

By default, pages are validated using full_clean() before attempting to save changes to the database, which helps to preserve validity when restoring pages from historic revisions (which might not necessarily reflect the current model state). This validation step can be bypassed by calling the method with clean=False.

create_alias(*, recursive=False, parent=None, update_slug=None, update_locale=None, user=None, log_action='wagtail.create_alias', reset_translation_key=True, _mpnode_attrs=None)

Creates an alias of the given page.

An alias is like a copy, but an alias remains in sync with the original page. They are not directly editable and do not have revisions.

You can convert an alias into a regular page by setting the .alias_of attribute to None and creating an initial revision.

Parameters:
  • recursive (boolean, optional) – create aliases of the page’s subtree, defaults to False
  • parent (Page, optional) – The page to create the new alias under
  • update_slug (string, optional) – The slug of the new alias page, defaults to the slug of the original page
  • update_locale (Locale, optional) – The locale of the new alias page, defaults to the locale of the original page
  • user (User, optional) – The user who is performing this action. This user would be assigned as the owner of the new page and appear in the audit log
  • log_action (string or None, optional) – Override the log action with a custom one. or pass None to skip logging, defaults to ‘wagtail.create_alias’
  • reset_translation_key (boolean, optional) – Generate new translation_keys for the page and any translatable child objects, defaults to False
update_aliases(*, revision=None, user=None, _content_json=None, _updated_ids=None)

Publishes all aliases that follow this page with the latest content from this page.

This is called by Wagtail whenever a page with aliases is published.

Parameters:
  • revision (PageRevision, optional) – The revision of the original page that we are updating to (used for logging purposes)
  • user (User, optional) – The user who is publishing (used for logging purposes)
has_workflow

Returns True if the page or an ancestor has an active workflow assigned, otherwise False

get_workflow()

Returns the active workflow assigned to the page or its nearest ancestor

workflow_in_progress

Returns True if a workflow is in progress on the current page, otherwise False

current_workflow_state

Returns the in progress or needs changes workflow state on this page, if it exists

current_workflow_task_state

Returns (specific class of) the current task state of the workflow on this page, if it exists

current_workflow_task

Returns (specific class of) the current task in progress on this page, if it exists

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.

The find_for_request() function returns the Site object that will handle the given HTTP request.

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

The site will be cached via request._wagtail_site

root_url

This returns the URL of the site. It is calculated from the hostname and the port 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/)
static get_site_root_paths()

Return a list of SiteRootPath instances, most specific path first - used to translate url_paths into actual URLs with hostnames

Each root path is an instance of the SiteRootPath named tuple, and have the following attributes:

  • site_id - The ID of the Site record
  • root_path - The internal URL path of the site’s home page (for example ‘/home/’)
  • root_url - The scheme/domain name of the site (for example ‘https://www.example.com/’)
  • language_code - The language code of the site (for example ‘en’)

Locale

The Locale model defines the set of languages and/or locales that can be used on a site. Each Locale record corresponds to a “language code” defined in the WAGTAIL_CONTENT_LANGUAGES setting.

Wagtail will initially set up one Locale to act as the default language for all existing content. This first locale will automatically pick the value from WAGTAIL_CONTENT_LANGUAGES that most closely matches the site primary language code defined in LANGUAGE_CODE. If the primary language code is changed later, Wagtail will not automatically create a new Locale record or update an existing one.

Before internationalisation is enabled, all pages use this primary Locale record. This is to satisfy the database constraints, and makes it easier to switch internationalisation on at a later date.

Changing WAGTAIL_CONTENT_LANGUAGES

Languages can be added or removed from WAGTAIL_CONTENT_LANGUAGES over time.

Before removing an option from WAGTAIL_CONTENT_LANGUAGES, it’s important that the Locale record is updated to a use a different content language or is deleted. Any Locale instances that have invalid content languages are automatically filtered out from all database queries making them unable to be edited or viewed.

Methods and properties

class wagtail.core.models.Locale
language_code

The language code that represents this locale

The language code can either be a language code on its own (such as en, fr), or it can include a region code (such as en-gb, fr-fr).

classmethod get_default()

Returns the default Locale based on the site’s LANGUAGE_CODE setting

classmethod get_active()

Returns the Locale that corresponds to the currently activated language in Django.

get_display_name()

Translatable Mixin

TranslatableMixin is an abstract model that can be added to any non-page Django model to make it translatable. Pages already include this mixin, so there is no need to add it.

Methods and properties

The locale and translation_key fields have a unique key constraint to prevent the object being translated into a language more than once.

class wagtail.core.models.TranslatableMixin
locale

(Foreign Key to Locale)

For pages, this defaults to the locale of the parent page.

translation_key

(uuid)

A UUID that is randomly generated whenever a new model instance is created. This is shared with all translations of that instance so can be used for querying translations.

get_translations(inclusive=False)

Returns a queryset containing the translations of this instance.

get_translation(locale)

Finds the translation in the specified locale.

If there is no translation in that locale, this raises a model.DoesNotExist exception.

get_translation_or_none(locale)

Finds the translation in the specified locale.

If there is no translation in that locale, this returns None.

has_translation(locale)

Returns True if a translation exists in the specified locale.

copy_for_translation(locale)

Creates a copy of this instance with the specified locale.

Note that the copy is initially unsaved.

classmethod get_translation_model()

Returns this model’s “Translation model”.

The “Translation model” is the model that has the locale and translation_key fields. Typically this would be the current model, but it may be a super-class if multi-table inheritance is in use (as is the case for wagtailcore.Page).

localized

Finds the translation in the current active language.

If there is no translation in the active language, self is returned.

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 its save_revision() method
  • The content of the page is JSON-serialised and stored in the content_json field
  • You can retrieve a PageRevision as a Page object by calling the as_page_object() method

Database fields

class wagtail.core.models.PageRevision
page

(foreign key to Page)

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 database

Example:

PageRevision.objects.all()
submitted_revisions

This manager is used to retrieve all of the PageRevision objects that are awaiting moderator approval

Example:

PageRevision.submitted_revisions.all()

Methods and properties

class wagtail.core.models.PageRevision
as_page_object()

This method retrieves this revision as an instance of its Page subclass.

approve_moderation(user=None)

Calling this on a revision that’s in moderation will mark it as approved and publish it

reject_moderation(user=None)

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(user=None, changed=True, log_action=True, previous_revision=None)

Publishes or schedules revision for publishing.

Parameters:
  • user – the publishing user
  • changed – indicated whether content has changed
  • log_action – flag for the logging action. Pass False to skip logging. Cannot pass an action string as the method performs several actions: “publish”, “revert” (and publish the reverted revision), “schedule publishing with a live revision”, “schedule revision reversal publishing, with a live revision”, “schedule publishing”, “schedule revision reversal publishing”
  • previous_revision – indicates a revision reversal. Should be set to the previous revision instance

Calling this will copy the content of this revision into the live page object. If the page is in draft, it will be published.

GroupPagePermission

Database fields

class wagtail.core.models.GroupPagePermission
group

(foreign key to django.contrib.auth.models.Group)

page

(foreign key to Page)

permission_type

(choice list)

PageViewRestriction

Database fields

class wagtail.core.models.PageViewRestriction
page

(foreign key to Page)

password

(text)

Orderable (abstract)

Database fields

class wagtail.core.models.Orderable
sort_order

(number)

Workflow

Workflows represent sequences of tasks which much be approved for an action to be performed on a page - typically publication.

Database fields

class wagtail.core.models.Workflow
name

(text)

Human-readable name of the workflow.

active

(boolean)

Whether or not the workflow is active: active workflows can be added to pages, and started. Inactive workflows cannot.

Methods and properties

class wagtail.core.models.Workflow
start(page, user)

Initiates a workflow by creating an instance of WorkflowState

tasks

Returns all Task instances linked to this workflow

deactivate(user=None)

Sets the workflow as inactive, and cancels all in progress instances of WorkflowState linked to this workflow

all_pages()

Returns a queryset of all the pages that this Workflow applies to.

WorkflowState

Workflow states represent the status of a started workflow on a page.

Database fields

class wagtail.core.models.WorkflowState
page

(foreign key to Page)

The page on which the workflow has been started

workflow

(foreign key to Workflow)

The workflow whose state the WorkflowState represents

status

(text)

The current status of the workflow (options are WorkflowState.STATUS_CHOICES)

created_at

(date/time)

When this instance of WorkflowState was created - when the workflow was started

requested_by

(foreign key to user model)

The user who started this workflow

current_task_state

(foreign key to TaskState)

The TaskState model for the task the workflow is currently at: either completing (if in progress) or the final task state (if finished)

Methods and properties

class wagtail.core.models.WorkflowState
STATUS_CHOICES

A tuple of the possible options for the status field, and their verbose names. Options are STATUS_IN_PROGRESS, STATUS_APPROVED, STATUS_CANCELLED and STATUS_NEEDS_CHANGES.

update(user=None, next_task=None)

Checks the status of the current task, and progresses (or ends) the workflow if appropriate. If the workflow progresses, next_task will be used to start a specific task next if provided.

get_next_task()

Returns the next active task, which has not been either approved or skipped

cancel(user=None)

Cancels the workflow state

finish(user=None)

Finishes a successful in progress workflow, marking it as approved and performing the on_finish action

resume(user=None)

Put a STATUS_NEEDS_CHANGES workflow state back into STATUS_IN_PROGRESS, and restart the current task

copy_approved_task_states_to_revision(revision)

This creates copies of previously approved task states with page_revision set to a different revision.

all_tasks_with_status()

Returns a list of Task objects that are linked with this workflow state’s workflow. The status of that task in this workflow state is annotated in the .status field. And a displayable version of that status is annotated in the .status_display field.

This is different to querying TaskState as it also returns tasks that haven’t been started yet (so won’t have a TaskState).

revisions()

Returns all page revisions associated with task states linked to the current workflow state

Task

Tasks represent stages in a workflow which must be approved for the workflow to complete successfully.

Database fields

class wagtail.core.models.Task
name

(text)

Human-readable name of the task.

active

(boolean)

Whether or not the task is active: active workflows can be added to workflows, and started. Inactive workflows cannot, and are skipped when in an existing workflow.

content_type

(foreign key to django.contrib.contenttypes.models.ContentType)

A foreign key to the ContentType object that represents the specific model of this task.

Methods and properties

class wagtail.core.models.Task
workflows

Returns all Workflow instances that use this task

active_workflows

Return a QuerySet` of active workflows that this task is part of

task_state_class

The specific task state class to generate to store state information for this task. If not specified, this will be TaskState.

classmethod get_verbose_name()

Returns the human-readable “verbose name” of this task model e.g “Group approval task”.

specific

Return this Task in its most specific subclassed form.

start(workflow_state, user=None)

Start this task on the provided workflow state by creating an instance of TaskState

on_action(task_state, user, action_name, **kwargs)

Performs an action on a task state determined by the action_name string passed

user_can_access_editor(page, user)

Returns True if a user who would not normally be able to access the editor for the page should be able to if the page is currently on this task. Note that returning False does not remove permissions from users who would otherwise have them.

user_can_lock(page, user)

Returns True if a user who would not normally be able to lock the page should be able to if the page is currently on this task. Note that returning False does not remove permissions from users who would otherwise have them.

user_can_unlock(page, user)

Returns True if a user who would not normally be able to unlock the page should be able to if the page is currently on this task. Note that returning False does not remove permissions from users who would otherwise have them.

page_locked_for_user(page, user)

Returns True if the page should be locked to a given user’s edits. This can be used to prevent editing by non-reviewers.

get_actions(page, user)

Get the list of action strings (name, verbose_name, whether the action requires additional data - see get_form_for_action) for actions the current user can perform for this task on the given page. These strings should be the same as those able to be passed to on_action

get_task_states_user_can_moderate(user, **kwargs)

Returns a QuerySet of the task states the current user can moderate

deactivate(user=None)

Set active to False and cancel all in progress task states linked to this task

get_form_for_action(action)
get_template_for_action(action)
classmethod get_description()

Returns the task description.

TaskState

Task states store state information about the progress of a task on a particular page revision.

Database fields

class wagtail.core.models.TaskState
workflow_state

(foreign key to WorkflowState)

The workflow state which started this task state.

page_revision

(foreign key to PageRevision)

The page revision this task state was created on.

task

(foreign key to Task)

The task that this task state is storing state information for.

status

(text)

The completion status of the task on this revision. Options are available in TaskState.STATUS_CHOICES)

content_type

(foreign key to django.contrib.contenttypes.models.ContentType)

A foreign key to the ContentType object that represents the specific model of this task.

started_at

(date/time)

When this task state was created.

finished_at

(date/time)

When this task state was cancelled, rejected, or approved.

finished_by

(foreign key to user model)

The user who completed (cancelled, rejected, approved) the task.

comment

(text)

A text comment, typically added by a user when the task is completed.

Methods and properties

class wagtail.core.models.TaskState
STATUS_CHOICES

A tuple of the possible options for the status field, and their verbose names. Options are STATUS_IN_PROGRESS, STATUS_APPROVED, STATUS_CANCELLED, STATUS_REJECTED and STATUS_SKIPPED.

exclude_fields_in_copy

A list of fields not to copy when the TaskState.copy() method is called.

specific

Return this TaskState in its most specific subclassed form.

approve(user=None, update=True, comment='')

Approve the task state and update the workflow state

reject(user=None, update=True, comment='')

Reject the task state and update the workflow state

task_type_started_at

Finds the first chronological started_at for successive TaskStates - ie started_at if the task had not been restarted

cancel(user=None, resume=False, comment='')

Cancel the task state and update the workflow state. If resume is set to True, then upon update the workflow state is passed the current task as next_task, causing it to start a new task state on the current task if possible

copy(update_attrs=None, exclude_fields=None)

Copy this task state, excluding the attributes in the exclude_fields list and updating any attributes to values specified in the update_attrs dictionary of attribute: new value pairs

get_comment()

Returns a string that is displayed in workflow history.

This could be a comment by the reviewer, or generated. Use mark_safe to return HTML.

WorkflowTask

Represents the ordering of a task in a specific workflow.

Database fields

class wagtail.core.models.WorkflowTask
workflow

(foreign key to Workflow)

task

(foreign key to Task)

sort_order

(number)

The ordering of the task in the workflow.

WorkflowPage

Represents the assignment of a workflow to a page and its descendants.

Database fields

class wagtail.core.models.WorkflowPage
workflow

(foreign key to Workflow)

page

(foreign key to Page)

BaseLogEntry

An abstract base class that represents a record of an action performed on an object.

Database fields

class wagtail.core.models.BaseLogEntry
content_type

(foreign key to django.contrib.contenttypes.models.ContentType)

A foreign key to the ContentType object that represents the specific model of this model.

label

(text)

The object title at the time of the entry creation

Note: Wagtail will attempt to use get_admin_display_title or the string representation of the object passed to log_action()

user

(foreign key to user model)

A foreign key to the user that triggered the action.

data_json

(text)

The JSON representation of any additional details for each action. e.g. source page id and title when copying from a page. Or workflow id/name and next step id/name on a workflow transition

timestamp

(date/time)

The date/time when the entry was created.

content_changed

(boolean)

A boolean that can set to True when the content has changed.

deleted

(boolean)

A boolean that can set to True when the object is deleted. Used to filter entries in the Site History report.

Methods and properties

class wagtail.core.models.BaseLogEntry
user_display_name

Returns the display name of the associated user; get_full_name if available and non-empty, otherwise get_username. Defaults to ‘system’ when none is provided

data

Provides deserialized data

comment
object_verbose_name
object_id()

PageLogEntry

Represents a record of an action performed on an Page, subclasses BaseLogEntry.

Database fields

class wagtail.core.models.PageLogEntry
page

(foreign key to Page)

A foreign key to the page the action is performed on.

revision

(foreign key to PageRevision)

A foreign key to the current page revision.

Comment

Represents a comment on a page.

Database fields

class wagtail.core.models.Comment
page

(parental key to Page)

A parental key to the page the comment has been added to.

user

(foreign key to user model)

A foreign key to the user who added this comment.

text

(text)

The text content of the comment.

contentpath

(text)

The path to the field or streamfield block the comment is attached to, in the form field or field.streamfield_block_id.

position

(text)

An identifier for the position of the comment within its field. The format used is determined by the field.

created_at

(date/time)

The date/time when the comment was created.

updated_at

(date/time)

The date/time when the comment was updated.

revision_created

(foreign key to PageRevision)

A foreign key to the revision on which the comment was created.

resolved_at

(date/time)

The date/time when the comment was resolved, if any.

resolved_by

(foreign key to user model)

A foreign key to the user who resolved this comment, if any.

CommentReply

Represents a reply to a comment thread.

Database fields

class wagtail.core.models.CommentReply
comment

(parental key to Comment)

A parental key to the comment that started the thread.

user

(foreign key to user model)

A foreign key to the user who added this comment.

text

(text)

The text content of the comment.

created_at

(date/time)

The date/time when the comment was created.

updated_at

(date/time)

The date/time when the comment was updated.

PageSubscription

Represents a user’s subscription to email notifications about page events. Currently only used for comment notifications.

Database fields

class wagtail.core.models.PageSubscription
page

(parental key to Page)

user

(foreign key to user model)

comment_notifications

(boolean)

Whether the user should receive comment notifications for all comments, or just comments in threads they participate in.