From e2062b4a1eb0afa179dbf25a29eda841eaccb86c Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 22 Jun 2009 00:25:24 +0000 Subject: Add documentation for *subpath. Switch back to using a route with a subpath in the bfgalchemy paster template. --- CHANGES.txt | 3 ++- docs/narr/hybrid.rst | 26 ++++++++++++++++++++++ .../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 + + + +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" /> - -- cgit v1.2.3