Embedding URL configuration in Pages

New in version 0.6.

The RoutablePageMixin mixin provides a convenient way for a page to respond on multiple sub-URLs with different views. For example, a blog section on a site might provide several different types of index page at URLs like /blog/2013/06/, /blog/authors/bob/, /blog/tagged/python/, all served by the same BlogIndex page.

A Page using RoutablePageMixin exists within the page tree like any other page, but URL paths underneath it are checked against a list of patterns, using Django’s urlconf scheme. If none of the patterns match, control is passed to subpages as usual (or failing that, a 404 error is thrown).

The basics

To use RoutablePageMixin, you need to make your class inherit from both wagtail.contrib.wagtailroutablepage.models.RoutablePageMixin and wagtail.wagtailcore.models.Page, and configure the subpage_urls attribute with your URL configuration.

Here’s an example of an EventPage with three views:

from django.conf.urls import url

from wagtail.contrib.wagtailroutablepage.models import RoutablePageMixin
from wagtail.wagtailcore.models import Page


class EventPage(RoutablePageMixin, Page):
    subpage_urls = (
        url(r'^$', 'current_events', name='current_events'),
        url(r'^past/$', 'past_events', name='past_events'),
        url(r'^year/(\d+)/$', 'events_for_year', name='events_for_year'),
    )

    def current_events(self, request):
        """
        View function for the current events page
        """
        ...

    def past_events(self, request):
        """
        View function for the past events page
        """
        ...

    def events_for_year(self, request):
        """
        View function for the events for year page
        """
        ...

The RoutablePageMixin class

class wagtail.contrib.wagtailroutablepage.models.RoutablePageMixin

This class can be mixed in to a Page subclass to allow urlconfs to be embedded inside pages.

subpage_urls = None

Set this to a tuple of django.conf.urls.url objects.

Example:

from django.conf.urls import url

from wagtail.wagtailcore.models import Page


class MyPage(RoutablePageMixin, Page):
    subpage_urls = (
        url(r'^$', 'main', name='main'),
        url(r'^archive/$', 'archive', name='archive'),
        url(r'^archive/(?P<year>[0-9]{4})/$', 'archive', name='archive'),
    )

    def main(self, request):
        ...

    def archive(self, request, year=None):
        ...

resolve_subpage(path)

This finds a view method/function from a URL path.

Example:

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

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

This method does the same job as Djangos’ built in “urlresolvers.reverse()” function for subpage urlconfs.

Example:

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

The routablepageurl template tag

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

routablepageurl is similar to pageurl, but works with RoutablePages. 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 self "feed" %}
{% routablepageurl self "archive" 2014 08 14 %}
{% routablepageurl self "food" foo="bar" baz="quux" %}