Merge pull request #1105 from kaedroho/routablepage-dj18

Recommend defining subpage_urls as a property

docs/contrib/routablepage.rst

@@ -14,7 +14,7 @@ A ``Page`` using ``RoutablePageMixin`` exists within the page tree like any othe
 The basics
 ==========
 
-To use ``RoutablePageMixin``, you need to make your class inherit from both :class:`wagtail.contrib.wagtailroutablepage.models.RoutablePageMixin` and :class:`wagtail.wagtailcore.models.Page`, and configure the ``subpage_urls`` attribute with your URL configuration.
+To use ``RoutablePageMixin``, you need to make your class inherit from both :class:`wagtail.contrib.wagtailroutablepage.models.RoutablePageMixin` and :class:`wagtail.wagtailcore.models.Page`, then define a ``subpage_urls`` property that returns a tuple of ``django.conf.url`` objects.
 
 Here's an example of an ``EventPage`` with three views:
 
@@ -27,11 +27,13 @@ Here's an example of an ``EventPage`` with three views:
 
 
     class EventPage(RoutablePageMixin, Page):
-        subpage_urls = (
+        @property
-            url(r'^$', 'current_events', name='current_events'),
+        def subpage_urls(self):
-            url(r'^past/$', 'past_events', name='past_events'),
+            return (
-            url(r'^year/(\d+)/$', 'events_for_year', name='events_for_year'),
+                url(r'^$', self.current_events, name='current_events'),
-        )
+                url(r'^past/$', self.past_events, name='past_events'),
+                url(r'^year/(\d+)/$', self.events_for_year, name='events_for_year'),
+            )
 
         def current_events(self, request):
             """
@@ -51,6 +53,16 @@ Here's an example of an ``EventPage`` with three views:
             """
             ...
 
+You can also set this as an attribute on the class. This will not work on Django 1.8 and above as the ``url`` function no longer allows strings to be specified as view names.
+
+.. code-block:: python
+
+    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'),
+        )
 
 The ``RoutablePageMixin`` class
 ===============================
@@ -60,6 +72,10 @@ The ``RoutablePageMixin`` class
 
     .. autoattribute:: subpage_urls
 
+        .. versionchanged:: 0.9
+
+            It was previously recommended to define ``subpage_urls`` as a class attribute. It is now recommend to define it as a property as Django 1.8 and above requires that the view argument to the ``url`` function is a callable and not a string.
+
         Example:
 
         .. code-block:: python
@@ -70,16 +86,17 @@ The ``RoutablePageMixin`` class
 
 
             class MyPage(RoutablePageMixin, Page):
-                subpage_urls = (
+                def subpage_urls(self):
-                    url(r'^$', 'main', name='main'),
+                    return (
-                    url(r'^archive/$', 'archive', name='archive'),
+                        url(r'^$', self.main_view, name='main'),
-                    url(r'^archive/(?P<year>[0-9]{4})/$', 'archive', name='archive'),
+                        url(r'^archive/$', self.archive_view, name='archive'),
-                )
+                        url(r'^archive/(?P<year>[0-9]{4})/$', self.archive_view, name='archive'),
+                    )
 
-                def main(self, request):
+                def main_view(self, request):
                     ...
 
-                def archive(self, request, year=None):
+                def archive_view(self, request, year=None):
                     ...
 
     .. automethod:: resolve_subpage
@@ -99,7 +116,6 @@ The ``RoutablePageMixin`` class
 
             url = page.url + page.reverse_subpage('archive', kwargs={'year': '2014'})
 
-
  .. _routablepageurl_template_tag:
 
 The ``routablepageurl`` template tag

wagtail/contrib/wagtailroutablepage/models.py

@@ -15,7 +15,8 @@ class RoutablePageMixin(object):
     This class can be mixed in to a Page subclass to allow urlconfs to be
     embedded inside pages.
     """
-    #: Set this to a tuple of ``django.conf.urls.url`` objects.
+    #: This attribute should contain a tuple of ``django.conf.url`` objects.
+    #: It can also be set to a property that returns a tuple of ``django.conf.url`` objects.
     subpage_urls = None
 
     def reverse_subpage(self, name, args=None, kwargs=None):