.. _hybrid_chapter:

Combining Traversal and URL Dispatch
====================================

:mod:`repoze.bfg` makes an honest attempt to unify the (largely
incompatible) concepts of :term:`traversal` and :term:`url dispatch`.

When you write *most* :mod:`repoze.bfg` applications, you'll be using
either one or the other concept, but not both, to resolve URLs to
:term:`view` callables.  However, for some problems, it's useful to
use both traversal *and* URL dispatch within the same application.
:mod:`repoze.bfg` makes this possible via *hybrid* applications.

.. warning:: Creating applications that use hybrid-mode features of
   :mod:`repoze.bfg` is a advanced topic that exposes non-trivial
   corner cases.  Don't use it unless you must.

The Schism
----------

:mod:`repoze.bfg`, especially when used according to the tutorials in
its documentation is sort of a "dual-mode" framework.  The tutorials
explain how to create an application in terms of using either
:term:`url dispatch` *or* :term:`traversal`.  But not both.  It's
useful to examine that pattern in order to understand the schism
between the two.

URL Dispatch Only
~~~~~~~~~~~~~~~~~

An application that uses :term:`url dispatch` exclusively to map URLs
to code will often have declarations like this within :term:`ZCML`:

.. code-block:: xml

   <route
     path=":foo/:bar"
     name="foobar"
     view=".views.foobar"
     />

   <route
     path=":baz/:buz"
     name="bazbuz"
     view=".views.bazbuz"
     />

In other words, each :term:`route` typically corresponds with a single
view callable, and when that route is matched during a request, the
view callable attached to it is invoked.

"Under the hood", these ``<route>`` declarations register a view for
each route.  This view is registered for the following context/request
type/name triad:

- the context :term:`interface` ``None``, implying any context.

- A :term:`request type` interface that inherits from
  :class:`repoze.bfg.interfaces.IRequest` *and* a
  dynamically-constructed route-statement-specific :term:`interface`.

- the empty string as the :term:`view name`, implying the default
  view.

This usually ensures that the named view will only be called when the
route it's attached to actually matches.

Typically, applications that use only URL dispatch won't have any
``<view>`` directives in ZCML and will not have any calls to
:meth:`repoze.bfg.configuration.Configurator.add_view` in their
startup code.

Traversal Only
~~~~~~~~~~~~~~

An application that uses :term:`traversal` exclusively to map URLs to
code just won't have any ``<route>`` declarations or calls to the
:meth:`repoze.bfg.configuration.Configurator.add_route`.  Instead, its
view configuration will imply declarations that look like this:

.. code-block:: xml

   <view
     name="foobar"
     view=".views.foobar"
     />

   <view
     name="bazbuz"
     view=".views.bazbuz"
     />

"Under the hood", the above view statements register a view using the
following context/request/name triad:

- The :term:`context` interface ``None``

- the the :class:`repoze.bfg.interfaces.IRequest` :term:`request type`
  interface

- a :term:`view name` matching the ``name=`` argument.

The ``.views.foobar`` view callable above will be called when the URL
``/a/b/c/foobar`` or ``/foobar``, etc, assuming that no view is named
``a``, ``b``, or ``c`` during traversal.

.. index::
   single: hybrid mode application

Hybrid Applications
-------------------

So far we've seen that *either* traversal or url dispatch to create a
:mod:`repoze.bfg` application.  However, it is possible to combine the
competing concepts of traversal and url dispatch to resolve URLs to
code within the same application.

Reasoning about a "hybrid" URL dispatch + traversal model can be
difficult because the combination of the two concepts seems to fall
outside the sweet spot of `the magical number seven plus or minus 2
<http://en.wikipedia.org/wiki/The_Magical_Number_Seven,_Plus_or_Minus_Two>`_.
To reason successfully about using URL dispatch and traversal
together, you need to understand 1) URL pattern matching, 2) root
factories and 3) the traversal algorithm, and the interactions between
all of them.  Therefore, use of this pattern is not recommended unless
you *really* need to use it.

Understanding how hybrid mode works requires a little "inside
baseball" knowledge of how :mod:`repoze.bfg` works.  No matter whether
:term:`traversal` or :term:`URL dispatch` is used, :mod:`repoze.bfg`
uses the :term:`Zope Component Architecture` under the hood to
dispatch a request to a :term:`view callable`.  In Zope Component
Architecture-speak, a view callable is a "multi adapter" registered
for a :term:`context` type and a :term:`request` type as well as a
particular :term:`view name`, aka a "triad".  When a request is
generated and a :term:`router` performs its logic, it locates these
three values.  These three values are fed to the :term:`application
registry` as a query to find "the best" view callable.

.. note:: To understand this process more deeply, it may be useful to
   read :ref:`router_chapter`.

To "turn on" hybrid mode, use a :term:`route configuration` that
includes a ``path`` argument that contains a special dynamic part:
either ``*traverse`` or ``*subpath``.

Using ``*traverse`` In a Route Path
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To create a hybrid application, combine traversal and URL dispatch by
using a ``<route>`` declaration that contains the special token
``*traverse`` in its path.

.. code-block:: xml

   <route
     path=":foo/:bar/*traverse"
     name="home"
     view=".views.home"
     />

When the view attached to this route is invoked, :mod:`repoze.bfg`
will attempt to use :term:`traversal` against the context implied by
the :term:`root factory` of this route.  The above example isn't very
useful unless you've defined a custom :term:`root factory` by passing
it to constructor of a :class:`repoze.bfg.configuration.Configurator`
because the *default* root factory cannot be traversed (it has no
useful ``__getitem__`` method).  But let's imagine that your root
factory looks like so:

.. code-block:: python

   class Traversable(object):
       def __init__(self, subobjects):
          self.subobjects = subobjects

       def __getitem__(self, name):
          return self.subobjects[name]

   root = Traversable(
           {'a':Traversable({'b':Traversable({'c':Traversable({})})})})

   def root_factory(request):
       return root

We've defined a bogus graph here that can be traversed, and a
root_factory method that returns the root of the graph.  Because the
Traversable object we've defined has a ``__getitem__`` method that
does something nominally useful, using traversal against the root
implied by a route statement becomes a not-completely-insane thing to
do.  So for this route:

.. code-block:: xml

   <route
     path=":foo/:bar/*traverse"
     name="home"
     view=".views.home"
     />

Under this circumstance, traversal is performed *after* the route
matches.  If the root factory returns a traversable object, the
"capture value" implied by the ``*traverse`` element in the path
pattern will be used to traverse the graph.  For example, if the URL
requested by a user was ``http://example.com/one/two/a/b/c``, and the
above route was matched (some other route might match before this one
does), the traversal path used against the root would be ``a/b/c``.
:mod:`repoze.bfg` will attempt to traverse a graph through the edges
``a``, ``b``, and ``c``.  In our above example, that would imply that
the *context* of the view would be the ``Traversable`` object we've
named ``c`` in our bogus graph, using the ``.views.home`` view as the
view callable.

We can also define extra views that match a route:

.. code-block:: xml

   <route
     path=":foo/:bar/*traverse"
     name="home"
     view=".views.home"
     />

   <view
     route_name="home"
     name="another"
     view=".views.another"
     />

Views that spell a route name are meant to associate a particular view
declaration with a route, using the route's name, in order to indicate
that the view should *only be invoked when the route matches*.

Views declared *after* the route declaration may have a ``route_name``
attribute which refers to the value of the ``<route>`` declaration's
``name`` attribute ("home").  The ``<view>`` declaration above names a
different view and (more importantly) a different :term:`view name`.
It's :term:`view name` will be looked for during traversal.  So if our
URL is "http://example.com/one/two/a/another", the ``.views.another``
view will be called.

.. index::
   pair: subpath; route

.. _star_subpath:

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 actually
performing traversal.  For instance, the
:func:`repoze.bfg.wsgi.wsgiapp2` decorator and the
:class:`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
:class:`repoze.bfg.view.static`.  This effectively tells the static
helper to traverse everything in the subpath as a filename.

Corner Cases
------------

A number of corner case "gotchas" exist when using a hybrid
application.  Let's see what they are.

.. _globalviews_corner_case:

"Global" Views Match Any Route When A More Specific View Doesn't
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Note that views that don't mention a ``route_name`` will *also* match
when *any* route matches.  For example, the "bazbuz" view below will
be found if the route named "abc" below is matched.

.. code-block:: xml

   <route
     path="/abc/*traverse"
     name="abc"
     view=".views.abc"
     />

   <view
     name="bazbuz"
     view=".views.bazbuz"
     />

To override the behavior of the "bazbuz" view when this route matches,
use an additional view that mentions the route name explicitly.

.. code-block:: xml

   <route
     path="/abc/*traverse"
     name="abc"
     view=".views.abc"
     />

   <view
     name="bazbuz"
     view=".views.bazbuz"
     />

   <view
     name="bazbuz"
     route_name="abc"
     view=".views.bazbuz2"
     />

In the above setup, when no route matches, and traversal finds the
view name to be "bazbuz", the ``.views.bazbuz`` view will be used.
However, if the "abc" route matches, and traversal finds the view name
to be "bazbuz", the ``.views.bazbuz2`` view will be used.

``context`` Type Registrations Bind More Tightly Than ``request``  Type Registrations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This corner case is only interesting if you are using a hybrid
application and you believe the "wrong" view is being called for a
given request.

A view is registered for a ``route`` either as its default view via
the ``view=`` attribute of a ``route`` declaration in ZCML *or* as a
standalone ``<view>`` declaration (or via the ``@bfg_route``
decorator) which has a ``route_name`` that matches the route's name.
At startup time, when such a registration is encountered, the view is
registered for the ``context`` type ``None`` (meaning *any* context)
and a *special* request type which is dynamically generated.  This
request type also derives from a "base" request type, which is what
allows it to match against views defined without a route name (see
:ref:`globalviews_corner_case`).

When a request URL matches a ``<route>`` path, the special request
type interface mentioned in the previous paragraph is attached to the
``request`` object as it is created.  The *root* found by the router
is based on either the route's ``factory`` (or the default root
factory if no ``factory`` is mentioned in the ``<route>``
declaration).  This root is eventually resolved to a ``context`` via
:term:`traversal`.  This ``context`` will either have some particular
interface, or it won't, depending on the result of traversal.

Given how view dispatch works, since the registration made "under the
hood" for views that match a route use the (very weakly binding)
``None`` value as the context value's interface, if the context that
is found has a specific interface, and a global view statement is
registered against this interface as its context interface, it's
likely that the *global* view will match *before* the view that is
attached to the route unless the ``view_context`` attribute is used on
the ``route`` registration to match the "correct" interface first
(because then both the request type and the context type are "more
specific" for the view registration).

What it all boils down to is: if a request that matches a route
resolves to a view you don't expect it to, use the ``view_context``
attribute of the ``route`` statement (*or* the ``context`` attribute
of the ZCML statement that also has a ``route_name`` *or* the
equivalent ``context`` parameter to the
:class:`repoze.bfg.view.bfg_view` decorator that also has a
``route_name`` parameter) to name the specific context interface you
want the route-related view to match.

Yes, that was as painful for me to write as it was for you to read.

Registering a Default View for a Route That has a ``view`` attribute
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

It is an error to provide *both* a ``view`` attribute on a ``<route>``
declaration *and* a ``<view>`` declaration that serves as a "default
view" (a view with no ``name`` attribute or the empty ``name``
attribute).  For example, this pair of route/view statements will
generate a "conflict" error at startup time.

.. code-block:: xml

   <route
     path=":foo/:bar/*traverse"
     name="home"
     view=".views.home"
     />

   <view
     route_name="home"
     view=".views.another"
     />

This is because the ``view`` attribute of the ``<route>`` statement
above is an *implicit* default view when that route matches.
``<route>`` declarations don't *need* to supply a view attribute.  For
example, this ``<route>`` statement:

.. code-block:: xml

   <route
     path=":foo/:bar/*traverse"
     name="home"
     view=".views.home"
     />

Can also be spelled like so:

.. code-block:: xml


   <route
     path=":foo/:bar/*traverse"
     name="home"
     />

   <view
     route_name="home"
     view=".views.home"
     />

The two spellings are logically equivalent.  

Binding Extra Views Against a  ``<route>`` Statement that Doesn't Have a ``*traverse`` Element In Its Path
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Here's another corner case that just makes no sense.

.. code-block:: xml

   <route
     path="/abc"
     name="abc"
     view=".views.abc"
     />

   <view
     name="bazbuz"
     view=".views.bazbuz"
     route_name="abc"
     />

The above ``<view>`` declaration is completely useless, because the
view name will never be matched when the route it references matches.
Only the view associated with the route itself (``.views.abc``) will
ever be invoked when the route matches, because the default view is
always invoked when a route matches and when no post-match traversal
is performed.  To make the below ``<view>`` declaration non-useless,
you must the special ``*traverse`` token to the route's "path"., e.g.:

.. code-block:: xml

   <route
     path="/abc/*traverse"
     name="abc"
     view=".views.abc"
     />

   <view
     name="bazbuz"
     view=".views.bazbuz"
     route_name="abc"
     />