RoutablePageMixin¶

Installation¶

Add "wagtail.contrib.routable_page" to your INSTALLED_APPS:

INSTALLED_APPS = [
    ...

    "wagtail.contrib.routable_page",
]

The basics¶

To use RoutablePageMixin, you need to make your class inherit from both :class:wagtail.contrib.routable_page.models.RoutablePageMixin and wagtail.models.Page, then define some view methods and decorate them with path or re_path.

These view methods behave like ordinary Django view functions, and must return an HttpResponse object; typically this is done through a call to django.shortcuts.render.

The path and re_path decorators from wagtail.contrib.routable_page.models.path are similar to the Django django.urls path and re_path functions. The former allows the use of plain paths and converters while the latter lets you specify your URL patterns as regular expressions.

Here’s an example of an EventIndexPage with three views, assuming that an EventPage model with an event_date field has been defined elsewhere:

import datetime
from django.http import JsonResponse
from wagtail.fields import RichTextField
from wagtail.models import Page
from wagtail.contrib.routable_page.models import RoutablePageMixin, path


class EventIndexPage(RoutablePageMixin, Page):

    # Routable pages can have fields like any other - here we would
    # render the intro text on a template with {{ page.intro|richtext }}
    intro = RichTextField()

    @path('') # will override the default Page serving mechanism
    def current_events(self, request):
        """
        View function for the current events page
        """
        events = EventPage.objects.live().filter(event_date__gte=datetime.date.today())

        # NOTE: We can use the RoutablePageMixin.render() method to render
        # the page as normal, but with some of the context values overridden
        return self.render(request, context_overrides={
            'title': "Current events",
            'events': events,
        })

    @path('past/')
    def past_events(self, request):
        """
        View function for the past events page
        """
        events = EventPage.objects.live().filter(event_date__lt=datetime.date.today())

        # NOTE: We are overriding the template here, as well as few context values
        return self.render(
            request,
            context_overrides={
                'title': "Past events",
                'events': events,
            },
            template="events/event_index_historical.html",
        )

    # Multiple routes!
    @path('year/<int:year>/')
    @path('year/current/')
    def events_for_year(self, request, year=None):
        """
        View function for the events for year page
        """
        if year is None:
            year = datetime.date.today().year

        events = EventPage.objects.live().filter(event_date__year=year)

        return self.render(request, context_overrides={
            'title': "Events for %d" % year,
            'events': events,
        })

    @re_path(r'^year/(\d+)/count/$')
    def count_for_year(self, request, year=None):
        """
        View function that returns a simple JSON response that
        includes the number of events scheduled for a specific year
        """
        events = EventPage.objects.live().filter(event_date__year=year)

        # NOTE: The usual template/context rendering process is irrelevant
        # here, so we'll just return a HttpResponse directly
        return JsonResponse({'count': events.count()})

@path('next/')
def next_event(self, request):
    """
    Display the page for the next event
    """
    future_events = EventPage.objects.live().filter(event_date__gt=datetime.date.today())
    next_event = future_events.order_by('event_date').first()

    return next_event.serve(request)

    # The URL name defaults to the view method name.
    >>> event_page.reverse_subpage('events_for_year', args=(2015, ))
    'year/2015/'

>>> event_page.url + event_page.reverse_subpage('events_for_year', args=(2015, ))
'/events/year/2015/'

>>> event_page.full_url + event_page.reverse_subpage('events_for_year', args=(2015, ))
'http://example.com/events/year/2015/'

from wagtail.models import Page
from wagtail.contrib.routable_page.models import RoutablePageMixin, route


class EventPage(RoutablePageMixin, Page):
    ...

    @re_path(r'^year/(\d+)/$', name='year')
    def events_for_year(self, request, year):
        """
        View function for the events for year page
        """
        ...

>>> event_page.url + event_page.reverse_subpage('year', args=(2015, ))
'/events/year/2015/'

The RoutablePageMixin class¶

class wagtail.contrib.routable_page.models.RoutablePageMixin¶

This class can be mixed in to a Page model, allowing extra routes to be added to it.

render(request, *args, template=None, context_overrides=None, **kwargs)¶

This method replicates what Page.serve() usually does when RoutablePageMixin is not used. By default, Page.get_template() is called to derive the template to use for rendering, and Page.get_context() is always called to gather the data to be included in the context.

You can use the context_overrides keyword argument as a shortcut to override or add new values to the context. For example:

@path('') # override the default route
def upcoming_events(self, request):
    return self.render(request, context_overrides={
        'title': "Current events",
        'events': EventPage.objects.live().future(),
    })

You can also use the template argument to specify an alternative template to use for rendering. For example:

@path('past/')
def past_events(self, request):
    return self.render(
        request,
        context_overrides={
            'title': "Past events",
            'events': EventPage.objects.live().past(),
        },
        template="events/event_index_historical.html",
    )

classmethod get_subpage_urls()¶

resolve_subpage(path)¶

This method takes a URL path and finds the view to call.

Example:

view, args, kwargs = page.resolve_subpage('/past/')
response = view(request, *args, **kwargs)

reverse_subpage(name, args=None, kwargs=None)¶

This method takes a route name/arguments and returns a URL path.

Example:

url = page.url + page.reverse_subpage('events_for_year', kwargs={'year': '2014'})

The routablepageurl template tag¶

wagtail.contrib.routable_page.templatetags.wagtailroutablepage_tags.routablepageurl(context, page, url_name, *args, **kwargs)¶

routablepageurl is similar to pageurl, but works with pages using RoutablePageMixin. It behaves like a hybrid between the built-in reverse, and pageurl from Wagtail.

page is the RoutablePage that URLs will be generated from.

url_name is a URL name defined in page.subpage_urls.

Positional arguments and keyword arguments should be passed as normal positional arguments and keyword arguments.

Example:

{% load wagtailroutablepage_tags %}

{% routablepageurl page "feed" %}
{% routablepageurl page "archive" 2014 08 14 %}
{% routablepageurl page "food" foo="bar" baz="quux" %}