diff options
| -rw-r--r-- | CHANGES.txt | 3 | ||||
| -rw-r--r-- | docs/narr/hybrid.rst | 26 | ||||
| -rw-r--r-- | repoze/bfg/paster_templates/routesalchemy/+package+/configure.zcml | 3 |
3 files changed, 30 insertions, 2 deletions
diff --git a/CHANGES.txt b/CHANGES.txt index e5cb81aa9..9d3f35b3d 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -186,7 +186,8 @@ Documentation and authorization policies to the "Security" narrative chapter. - Added a (fairly sad) "Combining Traversal and URL Dispatch" chapter - to the narrative documentation. + to the narrative documentation. This explains the usage of + ``*traverse`` and ``*subpath`` in routes URL patters. - A "router" chapter explaining the request/response lifecycle at a high level was added. diff --git a/docs/narr/hybrid.rst b/docs/narr/hybrid.rst index c3e61d906..73648a129 100644 --- a/docs/narr/hybrid.rst +++ b/docs/narr/hybrid.rst @@ -215,6 +215,32 @@ In this way, each route can use a different factory, making it possible to traverse different graphs based on some routing parameter within the same application. +Using ``*subpath`` in a Route Path +---------------------------------- + +There are certain (extremely rare) cases when you'd like to influence +the traversal :term:`subpath` when a route matches without atually +performing traversal. For instance, the ``repoze.bfg.wsgi.wsgiapp2`` +decorator and the ``repoze.bfg.view.static`` helper attempt to compute +``PATH_INFO`` from the request's subpath, so it's useful to be able to +influence this value. When ``*subpath`` exists in a path pattern, no +path is actually traversed, but the traversal algorithm will return a +:term:`subpath` list implied by the capture value of ``*subpath``. +You'll see this pattern most commonly in route declarations that look +like this: + +.. code-block:: xml + + <route + path="/static/*subpath" + name="static" + view=".views.static_view" + /> + +Where ``.views.static_view`` is an instance of +``repoze.bfg.view.static``. This effectively tells the static helper +to traverse everything in the subpath as a filename. + Corner Cases ------------ diff --git a/repoze/bfg/paster_templates/routesalchemy/+package+/configure.zcml b/repoze/bfg/paster_templates/routesalchemy/+package+/configure.zcml index 13f4e2531..14bb95cd6 100644 --- a/repoze/bfg/paster_templates/routesalchemy/+package+/configure.zcml +++ b/repoze/bfg/paster_templates/routesalchemy/+package+/configure.zcml @@ -12,7 +12,8 @@ view=".views.my_view" /> - <view + <route + path="/static/*subpath" name="static" view=".views.static_view" /> |