Embedding URL configuration in Pages

New in version 0.5.

The RoutablePage class 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 RoutablePage 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 RoutablePage, you need to make your class inherit from wagtail.contrib.wagtailroutablepage.models.RoutablePage 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 RoutablePage


class EventPage(RoutablePage):
    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 current events page
        """
        ...

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

The RoutablePage class

class wagtail.contrib.wagtailroutablepage.models.RoutablePage(*args, **kwargs)

This class extends Page by adding methods 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

subpage_urls = (
    url(r'^$', 'serve', name='main'),
    url(r'^archive/$', 'archive', name='archive'),
)
resolve_subpage(path)

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

Example:

view, args, kwargs = page.resolve_subpage('/past/')
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('events_for_year', args=('2014', ))