documentation for hybrid url generation

Chris McDonough

2013-08-30 0a4aed1c8e0a6da9219cccb6f55882d916f49916

documentation for hybrid url generation

 CHANGES.txt

@@ -4,6 +4,12 @@
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 

 docs/narr/hybrid.rst

@@ -549,3 +549,83 @@
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``.


 pyramid/url.py

@@ -420,6 +420,14 @@
        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 @@

        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 @@
        ``__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