Page QuerySet reference¶
All models that inherit from Page
are given some extra QuerySet methods accessible from their .objects
attribute.
Examples¶
Selecting only live pages
live_pages = Page.objects.live()Selecting published EventPages that are descendants of events_index
events = EventPage.objects.live().descendant_of(events_index)Getting a list of menu items
# This gets a QuerySet of live children of the homepage with ``show_in_menus`` set menu_items = homepage.get_children().live().in_menu()
Reference¶
-
class
wagtail.core.query.
PageQuerySet
(model=None, query=None, using=None, hints=None)¶ -
live
()¶ This filters the QuerySet to only contain published pages.
Example:
published_pages = Page.objects.live()
-
not_live
()¶ This filters the QuerySet to only contain unpublished pages.
Example:
unpublished_pages = Page.objects.not_live()
This filters the QuerySet to only contain pages that are in the menus.
Example:
# Build a menu from live pages that are children of the homepage menu_items = homepage.get_children().live().in_menu()
Note
To put your page in menus, set the show_in_menus flag to true:
# Add 'my_page' to the menu my_page.show_in_menus = True
This filters the QuerySet to only contain pages that are not in the menus.
-
in_site
(site)¶ This filters the QuerySet to only contain pages within the specified site.
Example:
# Get all the EventPages in the current site site_events = EventPage.objects.in_site(request.site)
-
page
(other)¶ This filters the QuerySet so it only contains the specified page.
Example:
# Append an extra page to a QuerySet new_queryset = old_queryset | Page.objects.page(page_to_add)
-
not_page
(other)¶ This filters the QuerySet so it doesn’t contain the specified page.
Example:
# Remove a page from a QuerySet new_queryset = old_queryset & Page.objects.not_page(page_to_remove)
-
descendant_of
(other, inclusive=False)¶ This filters the QuerySet to only contain pages that descend from the specified page.
If inclusive is set to True, it will also contain the page itself (instead of just its descendants).
Example:
# Get EventPages that are under the special_events Page special_events = EventPage.objects.descendant_of(special_events_index) # Alternative way special_events = special_events_index.get_descendants()
-
not_descendant_of
(other, inclusive=False)¶ This filters the QuerySet to not contain any pages that descend from the specified page.
If inclusive is set to True, it will also exclude the specified page.
Example:
# Get EventPages that are not under the archived_events Page non_archived_events = EventPage.objects.not_descendant_of(archived_events_index)
-
child_of
(other)¶ This filters the QuerySet to only contain pages that are direct children of the specified page.
Example:
# Get a list of sections sections = Page.objects.child_of(homepage) # Alternative way sections = homepage.get_children()
-
not_child_of
(other)¶ This filters the QuerySet to not contain any pages that are direct children of the specified page.
-
ancestor_of
(other, inclusive=False)¶ This filters the QuerySet to only contain pages that are ancestors of the specified page.
If inclusive is set to True, it will also include the specified page.
Example:
# Get the current section current_section = Page.objects.ancestor_of(current_page).child_of(homepage).first() # Alternative way current_section = current_page.get_ancestors().child_of(homepage).first()
-
not_ancestor_of
(other, inclusive=False)¶ This filters the QuerySet to not contain any pages that are ancestors of the specified page.
If inclusive is set to True, it will also exclude the specified page.
Example:
# Get the other sections other_sections = Page.objects.not_ancestor_of(current_page).child_of(homepage)
-
parent_of
(other)¶ This filters the QuerySet to only contain the parent of the specified page.
-
not_parent_of
(other)¶ This filters the QuerySet to exclude the parent of the specified page.
-
sibling_of
(other, inclusive=True)¶ This filters the QuerySet to only contain pages that are siblings of the specified page.
By default, inclusive is set to True so it will include the specified page in the results.
If inclusive is set to False, the page will be excluded from the results.
Example:
# Get list of siblings siblings = Page.objects.sibling_of(current_page) # Alternative way siblings = current_page.get_siblings()
-
not_sibling_of
(other, inclusive=True)¶ This filters the QuerySet to not contain any pages that are siblings of the specified page.
By default, inclusive is set to True so it will exclude the specified page from the results.
If inclusive is set to False, the page will be included in the results.
-
public
()¶ This filters the QuerySet to only contain pages that are not in a private section
See: Private pages
Note
This doesn’t filter out unpublished pages. If you want to only have published public pages, use
.live().public()
Example:
# Find all the pages that are viewable by the public all_pages = Page.objects.live().public()
-
not_public
()¶ This filters the QuerySet to only contain pages that are in a private section
-
search
(query, fields=None, operator=None, order_by_relevance=True, partial_match=True, backend='default')¶ This runs a search query on all the items in the QuerySet
See: Searching QuerySets
Example:
# Search future events results = EventPage.objects.live().filter(date__gt=timezone.now()).search("Hello")
-
type
(model)¶ This filters the QuerySet to only contain pages that are an instance of the specified model (including subclasses).
Example:
# Find all pages that are of type AbstractEmailForm, or a descendant of it form_pages = Page.objects.type(AbstractEmailForm)
-
not_type
(model)¶ This filters the QuerySet to not contain any pages which are an instance of the specified model.
-
exact_type
(model)¶ This filters the QuerySet to only contain pages that are an instance of the specified model (matching the model exactly, not subclasses).
Example:
# Find all pages that are of the exact type EventPage event_pages = Page.objects.exact_type(EventPage)
-
not_exact_type
(model)¶ This filters the QuerySet to not contain any pages which are an instance of the specified model (matching the model exactly, not subclasses).
Example:
# Find all pages that are not of the exact type EventPage (but may be a subclass) non_event_pages = Page.objects.not_exact_type(EventPage)
-
unpublish
()¶ This unpublishes all live pages in the QuerySet.
Example:
# Unpublish current_page and all of its children Page.objects.descendant_of(current_page, inclusive=True).unpublish()
-
specific
(defer=False)¶ This efficiently gets all the specific pages for the queryset, using the minimum number of queries.
When the “defer” keyword argument is set to True, only the basic page fields will be loaded and all specific fields will be deferred. It will still generate a query for each page type though (this may be improved to generate only a single query in a future release).
Example:
# Get the specific instance of all children of the hompage, # in a minimum number of database queries. homepage.get_children().specific()
See also:
Page.specific
-
first_common_ancestor
(include_self=False, strict=False)¶ Find the first ancestor that all pages in this queryset have in common. For example, consider a page hierarchy like:
- Home/ - Foo Event Index/ - Foo Event Page 1/ - Foo Event Page 2/ - Bar Event Index/ - Bar Event Page 1/ - Bar Event Page 2/
The common ancestors for some queries would be:
>>> Page.objects\ ... .type(EventPage)\ ... .first_common_ancestor() <Page: Home> >>> Page.objects\ ... .type(EventPage)\ ... .filter(title__contains='Foo')\ ... .first_common_ancestor() <Page: Foo Event Index>
This method tries to be efficient, but if you have millions of pages scattered across your page tree, it will be slow.
If include_self is True, the ancestor can be one of the pages in the queryset:
>>> Page.objects\ ... .filter(title__contains='Foo')\ ... .first_common_ancestor() <Page: Foo Event Index> >>> Page.objects\ ... .filter(title__exact='Bar Event Index')\ ... .first_common_ancestor() <Page: Bar Event Index>
A few invalid cases exist: when the queryset is empty, when the root Page is in the queryset and
include_self
is False, and when there are multiple page trees with no common root (a case Wagtail does not support). Ifstrict
is False (the default), then the first root node is returned in these cases. Ifstrict
is True, then aObjectDoesNotExist
is raised.
-