- The ``Hybrid`` narrative chapter now contains a description of the

  ``traverse`` route argument.

- Fix route ZCML directive to use traverse.

3 files changed, 66 insertions, 3 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index dfdec3ec6..e9d0e0ce0 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -62,6 +62,9 @@ Documentation
 - The ``Views`` narrative chapter now contains a description of the
   ``match_val`` predicate.
 
+- The ``Hybrid`` narrative chapter now contains a description of the
+  ``traverse`` route argument.
+
 Bug Fixes
 ---------
 
diff --git a/docs/narr/hybrid.rst b/docs/narr/hybrid.rst
index 368d44626..be2689c68 100644
--- a/docs/narr/hybrid.rst
+++ b/docs/narr/hybrid.rst
@@ -206,13 +206,13 @@ of a route's path:
      />
 
 A ``*traverse`` token at the end of the path in a route's
-configuration implies a "stararg" *capture* value.  When it is used,
+configuration implies a "remainder" *capture* value.  When it is used,
 it will match the remainder of the path segments of the URL.  This
 remainder becomes the path used to perform traversal.
 
 .. note::
 
-   The ``*stararg`` route path pattern syntax is explained in more
+   The ``*remainder`` route path pattern syntax is explained in more
    detail within :ref:`route_path_pattern_syntax`.
 
 Note that unlike the examples provided within
@@ -392,6 +392,57 @@ configuration statements and *view* configuration statements are
 supported in hybrid applications (such as :term:`predicate`
 arguments).
 
+Using the ``traverse`` Argument In a Route Definition
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Rather than using the ``*traverse`` remainder marker in a path
+pattern, you can use the ``traverse`` argument to the
+:meth:`repoze.bfg.configuration.Configurator.add_route`` method or the
+``traverse`` attribute of the :ref:`route_directive` ZCML directive.
+(either method is equivalent).
+
+When you use the ``*traverse`` remainder marker, the traversal path is
+limited to being the remainder segments of a request URL when a route
+matches.  However, when you use the ``traverse`` argument or
+attribute, you have more control over how to compose a traversal path.
+
+Here's a use of the ``traverse`` pattern in a ZCML ``route``
+declaration:
+
+.. code-block:: xml
+   :linenos:
+
+   <route
+     name="abc"
+     path="/articles/:article/edit"
+     traverse="/articles/:article"
+     />
+
+The syntax of the ``traverse`` argument is the same as it is for
+``path``.
+
+If, as above, the ``path`` provided is ``articles/:article/edit``, and
+the ``traverse`` argument provided is ``/:article``, when a request
+comes in that causes the route to match in such a way that the
+``article`` match value is ``1`` (when the request URI is
+``/articles/1/edit``), the traversal path will be generated as ``/1``.
+This means that the root object's ``__getitem__`` will be called with
+the name ``1`` during the traversal phase.  If the ``1`` object
+exists, it will become the :term:`context` of the request.
+:ref:`traversal_chapter` has more information about traversal.
+
+If the traversal path contains segment marker names which are not
+present in the path argument, a runtime error will occur.  The
+``traverse`` pattern should not contain segment markers that do not
+exist in the ``path``.
+
+Note that the ``traverse`` argument is ignored when attached to a
+route that has a ``*traverse`` remainder marker in its path.
+
+Traversal will begin at the root object implied by this route (either
+the global root, or the object returned by the ``factory`` associated
+with this route).
+
 Making Global Views Match
 +++++++++++++++++++++++++
 
diff --git a/repoze/bfg/zcml.py b/repoze/bfg/zcml.py
index b8ca9eb21..b350d5ea7 100644
--- a/repoze/bfg/zcml.py
+++ b/repoze/bfg/zcml.py
@@ -174,6 +174,7 @@ def view(
     header=None,
     path_info=None,
     match_val=None,
+    traverse=None,
     custom_predicates=(),
     context=None,
     cacheable=True, # not used, here for b/w compat < 0.8
@@ -205,7 +206,7 @@ def view(
             request_method=request_method, request_param=request_param,
             containment=containment, attr=attr, renderer=renderer,
             wrapper=wrapper, xhr=xhr, accept=accept, header=header,
-            path_info=path_info, match_val=match_val,
+            path_info=path_info, match_val=match_val, 
             custom_predicates=custom_predicates,
             _info=_context.info)
 
@@ -252,6 +253,12 @@ class IRouteDirective(Interface):
     accept = TextLine(title=u'accept', required=False)
     xhr = Bool(title=u'xhr', required=False)
     path_info = TextLine(title=u'path_info', required=False)
+
+    traverse = TextLine(
+        title=u'Traverse pattern"',
+        description=u'A pattern which will compose a traversal path',
+        required = False)
+
     custom_predicates = Tokens(
         title=u"One or more custom dotted names to custom predicate callables",
         description=(u"A list of dotted name references to callables that "
@@ -281,6 +288,7 @@ def route(_context,
           renderer=None,
           view_renderer=None,
           view_context=None,
+          traverse=None,
           use_global_views=False):
     """ Handle ``route`` ZCML directives
     """
@@ -318,6 +326,7 @@ def route(_context,
             view_renderer=view_renderer,
             view_attr=view_attr,
             use_global_views=use_global_views,
+            traverse=traverse,
             _info=_context.info
             )