documentation for hybrid url generation

3 files changed, 95 insertions, 9 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 657c50009..cfa77283f 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -4,6 +4,12 @@ Next Release
 Features
 --------
 
+- You can now generate "hybrid" urldispatch/traversal URLs more easily
+  by using the new ``route_name`` and ``route_kw`` arguments to 
+  ``request.resource_url`` and ``request.resource_path``.  See the new section 
+  of the "Combining Traversal and URL Dispatch" documentation chapter entitled 
+  "Hybrid URL Generation".
+
 - It is now possible to escape double braces in Pyramid scaffolds (unescaped, 
   these represent replacement values).  You can use ``\{\{a\}\}`` to
   represent a "bare" ``{{a}}``.  See 
diff --git a/docs/narr/hybrid.rst b/docs/narr/hybrid.rst
index 1773a6b8c..58d89fc98 100644
--- a/docs/narr/hybrid.rst
+++ b/docs/narr/hybrid.rst
@@ -549,3 +549,83 @@ be invoked when the request URI is ``/abc/bazbuz``, assuming there is
 no object contained by the root object with the key ``bazbuz``. A
 different request URI, such as ``/abc/foo/bar``, would invoke the
 default ``myproject.views.abc`` view.
+
+.. index::
+   pair: hybrid urls; generating
+
+.. _generating_hybrid_urls:
+
+Generating Hybrid URLs
+----------------------
+
+.. versionadded:: 1.5
+
+The :meth:`pyramid.request.Request.resource_url` method and the 
+:meth:`pyramid.request.Request.resource_path` method both accept optional 
+keyword arguments that make it easier to generate route-prefixed URLs that
+contain paths to traversal resources:``route_name`` and ``route_kw``.
+
+Any route that has a pattern that contains a ``*remainder`` pattern (any
+stararg remainder pattern, such as ``*traverse`` or ``*subpath`` or ``*fred``) 
+can be used as the target name for ``request.resource_url(..., route_name=)`` 
+and ``request.resource_path(..., route_name=)``. 
+
+For example, let's imagine you have a route defined in your Pyramid application
+like so:
+
+.. code-block:: python
+
+   config.add_route('mysection', '/mysection*traverse')
+
+If you'd like to generate the URL ``http://example.com/mysection/a/``, you can 
+use the following incantation, assuming that the variable ``a`` below points to
+a resource that is a child of the root with a ``__name__`` of ``a``:
+
+.. code-block:: python
+
+   request.resource_url(a, route_name='mysection')
+
+You can generate only the path portion ``/mysection/a/`` assuming the same:
+
+.. code-block:: python
+
+   request.resource_path(a, route_name='mysection')
+
+The path is virtual host aware, so if the ``X-Vhm-Root`` environ variable is 
+present in the request, and it's set to ``/a``, the above call to 
+``request.resource_url`` would generate ``http://example.com/mysection/`` 
+and the above call to ``request.resource_path`` would generate ``/mysection/``.
+See :ref:`virtual_root_support` for more information.
+
+If the route you're trying to use needs simple dynamic part values to be filled
+in to succesfully generate the URL, you can pass these as the ``route_kw`` 
+argument to ``resource_url`` and ``resource_path``.  For example, assuming that
+the route definition is like so:
+
+.. code-block:: python
+
+   config.add_route('mysection', '/{id}/mysection*traverse')
+
+You can pass ``route_kw`` in to fill in ``{id}`` above:
+
+.. code-block:: python
+
+   request.resource_url(a, route_name='mysection', route_kw={'id':'1'})
+
+If you pass ``route_kw`` but do not pass ``route_name``, ``route_kw`` will
+be ignored.
+
+All other values that are normally passable to ``resource_path`` and 
+``resource_url`` (such as ``query``, ``anchor``, ``host``, ``port``, etc) work 
+as you might expect in this configuration too.
+
+If you try to use ``resource_path`` or ``resource_url`` when the ``route_name``
+argument points at a route that does not have a remainder stararg, an error
+will not be raised, but the generated URL will not contain any remainder
+information either.
+
+Note that this feature is incompatible with the ``__resource_url__`` feature
+(see :ref:`overriding_resource_url_generation`) implemented on resource
+objects.  Any  ``__resource_url__`` supplied by your resource will be ignored
+when you pass ``route_name``.
+
diff --git a/pyramid/url.py b/pyramid/url.py
index d8fe997d9..90b8f667f 100644
--- a/pyramid/url.py
+++ b/pyramid/url.py
@@ -420,6 +420,14 @@ class URLMethodsMixin(object):
         are also passed, ``app_url`` will take precedence and the values
         passed for ``scheme``, ``host``, and/or ``port`` will be ignored.
 
+        If the ``resource`` passed in has a ``__resource_url__`` method, it
+        will be used to generate the URL (scheme, host, port, path) for the
+        base resource which is operated upon by this function.  See also
+        :ref:`overriding_resource_url_generation`.
+
+        .. versionadded:: 1.5
+           ``route_name`` and ``route_kw``
+           
         If ``route_name`` is passed, this function will delegate its URL
         production to the ``route_url`` function.  Calling
         ``resource_url(someresource, 'element1', 'element2', query={'a':1},
@@ -436,7 +444,7 @@ class URLMethodsMixin(object):
 
         It is only sensible to pass ``route_name`` if the route being named has
         a ``*remainder`` stararg value such as ``*traverse``.  The remainder
-        will be ignored in the output otherwise.
+        value will be ignored in the output otherwise.
 
         If ``route_name`` is passed, it is also permissible to pass
         ``route_kw``, which will passed as additional keyword arguments to
@@ -458,14 +466,6 @@ class URLMethodsMixin(object):
         ``__resource_url__`` method of the resource passed is ignored
         unconditionally.
         
-        The ``route_name`` and ``route_kw`` arguments were added in Pyramid
-        1.5.
-
-        If the ``resource`` passed in has a ``__resource_url__`` method, it
-        will be used to generate the URL (scheme, host, port, path) for the
-        base resource which is operated upon by this function.  See also
-        :ref:`overriding_resource_url_generation`.
-
         .. note::
 
            If the :term:`resource` used is the result of a :term:`traversal`, it