Merge multiview2 branch to HEAD.

3 files changed, 202 insertions, 42 deletions

diff --git a/docs/narr/hybrid.rst b/docs/narr/hybrid.rst
index 48b2eedfc..34f606a97 100644
--- a/docs/narr/hybrid.rst
+++ b/docs/narr/hybrid.rst
@@ -259,9 +259,9 @@ application.  Let's see what they are.
 "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.
+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
 
@@ -323,7 +323,7 @@ name` to try to locate a view callable.
 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).
+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
@@ -463,9 +463,3 @@ statement ordering is very important, because routes are evaluated in
 a specific order, unlike traversal, which depends on emergent behavior
 rather than an ordered list of directives.
 
-A ``<route>`` Statement *Must* Precede Any ``<view>`` Statement Which Mentions It
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-A ``<route>`` declaration *must* precede (in XML order) any ``<view>``
-declaration which names it as a ``route_name``.  If it does not, at
-application startup time a ``ConfigurationError`` will be raised.
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index fdaea228f..dfae6e1b0 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -62,15 +62,22 @@ attributes are optional unless the description names them as required.
 
 path
 
-  The `route path
-  <http://routes.groovie.org/manual.html#route-path>`_,
-  e.g. ``ideas/:idea``.  This attribute is required.
+  The path of the route e.g. ``ideas/:idea``.  This attribute is
+  required.  See :ref:`route_path_pattern_syntax` for information
+  about the syntax of route paths.
 
 name
 
-  The `route name
-  <http://routes.groovie.org/manual.html#route-name>`_,
-  e.g. ``myroute``.  This attribute is required.
+  The name of the route, e.g. ``myroute``.  This attribute is
+  required.  It must be unique among all defined routes in a given
+  configuration.
+
+factory
+
+  The Python dotted-path name to a function that will generate a
+  :mod:`repoze.bfg` context object when this route matches.
+  e.g. ``mypackage.models.MyFactoryClass``.  If this argument is not
+  specified, a default root factory will be used.
 
 view
 
@@ -86,23 +93,79 @@ view_for
   attribute is used.  If this attribute is not specified, the default
   (``None``) will be used.
 
-permission
+  If the ``view`` attribute is not provided, this attribute has no
+  effect.
 
-  The permission name required to invoke the view.
-  e.g. ``edit``. (see :ref:`using_security_with_urldispatch` for more
-  information about permissions).
+  This attribute can also be spelled as ``for``.
 
-factory
+view_permission
 
-  The Python dotted-path name to a function that will generate a
-  :mod:`repoze.bfg` context object when this route matches.
-  e.g. ``mypackage.models.MyFactoryClass``.  If this argument is not
-  specified, a default root factory will be used.
+  The permission name required to invoke the view associated with this
+  route.  e.g. ``edit``. (see :ref:`using_security_with_urldispatch`
+  for more information about permissions).
+
+  If the ``view`` attribute is not provided, this attribute has no
+  effect.
+
+  This atribute can also be spelled as ``permission``.
+
+view_request_type
 
-request_type
+  A dotted Python name to an interface representing a :term:`request
+  type`.  For backwards compatibility with :mod:`repoze.bfg` 1.0 and
+  before, this may also be a string naming an HTTP ``REQUEST_METHOD``
+  (any of ``GET``, ``POST``, ``HEAD``, ``DELETE``, ``PUT``).  However,
+  these values should really be specified in ``request_method``.  If
+  this argument is not specified, any request type will be considered
+  a match for the view associated with this route.
 
-  A string representing an HTTP method name, e.g. ``GET`` or ``POST``
-  or an interface representing a :term:`request type`.
+  If the ``view`` attribute is not provided, this attribute has no
+  effect.
+
+  This attribute can also be spelled as ``request_type``.
+
+view_request_method
+
+  A string representing an HTTP method name, e.g. ``GET``, ``POST``,
+  ``HEAD``, ``DELETE``, ``PUT``.  If this argument is not specified
+  any request method will be considered a match for the view
+  associated with this route.
+
+  If the ``view`` attribute is not provided, this attribute has no
+  effect.
+
+  This attribute can also be spelled as ``request_method``.
+
+view_request_param
+
+  This value can be any string.  A view declaration with this
+  attribute ensures that the associated view will only be called when
+  the request has a key in the ``request.params`` dictionary (an HTTP
+  ``GET`` or ``POST`` variable) that has a name which matches the
+  supplied value.  If the value supplied to the attribute has a ``=``
+  sign in it, e.g. ``request_params="foo=123"``, then the key
+  (``foo``) must both exist in the ``request.params`` dictionary, and
+  the value must match the right hand side of the expression (``123``)
+  for the view to "match" the current request.
+
+  If the ``view`` attribute is not provided, this attribute has no
+  effect.
+
+  This attribute can also be spelled as ``request_param``.
+
+view_containment
+
+  This value should be a Python dotted-path string representing the
+  class that a graph traversal parent object of the :term:`context`
+  must be an instance of (or :term:`interface` that a parent object
+  must provide) in order for this view to be found and called.  Your
+  models must be "location-aware" to use this feature.  See
+  :ref:`location_aware` for more information about location-awareness.
+
+  If the ``view`` attribute is not provided, this attribute has no
+  effect.
+
+  This attribute can also be spelled as ``containment``.
 
 The Matchdict
 -------------
@@ -114,6 +177,8 @@ request named ``matchdict`` with the values that match patterns in the
 ``path`` element.  If the URL pattern does not match, no matchdict is
 generated.
 
+.. _route_path_pattern_syntax:
+
 Path Pattern Syntax
 --------------------
 
diff --git a/docs/narr/views.rst b/docs/narr/views.rst
index 389c4ddfc..28fe643d8 100644
--- a/docs/narr/views.rst
+++ b/docs/narr/views.rst
@@ -247,14 +247,34 @@ permission
   call the view.  See :ref:`view_security_section` for more
   information about view security and permissions.
 
-request_type
+request_method
 
   This value can either be one of the strings 'GET', 'POST', 'PUT',
-  'DELETE', or 'HEAD' representing an HTTP method, *or* it may be
-  Python dotted-path string representing the :term:`interface` that
-  the :term:`request` must have in order for this view to be found and
-  called.  See :ref:`view_request_types_section` for more information
-  about request types.
+  'DELETE', or 'HEAD' representing an HTTP ``REQUEST_METHOD``.  A view
+  declaration with this attribute ensures that the view will only be
+  called when the request's ``method`` (aka ``REQUEST_METHOD``) string
+  matches the supplied value.
+
+request_param
+
+  This value can be any string.  A view declaration with this
+  attribute ensures that the view will only be called when the request
+  has a key in the ``request.params`` dictionary (an HTTP ``GET`` or
+  ``POST`` variable) that has a name which matches the supplied value.
+  If the value supplied to the attribute has a ``=`` sign in it,
+  e.g. ``request_params="foo=123"``, then the key (``foo``) must both
+  exist in the ``request.params`` dictionary, and the value must match
+  the right hand side of the expression (``123``) for the view to
+  "match" the current request.
+
+containment
+
+  This value should be a Python dotted-path string representing the
+  class that a graph traversal parent object of the :term:`context`
+  must be an instance of (or :term:`interface` that a parent object
+  must provide) in order for this view to be found and called.  Your
+  models must be "location-aware" to use this feature.  See
+  :ref:`location_aware` for more information about location-awareness.
 
 route_name
 
@@ -271,6 +291,69 @@ route_name
   :term:`root factory`.  See :ref:`hybrid_chapter` for more
   information on using this advanced feature.
 
+request_type
+
+  This value should be a Python dotted-path string representing the
+  :term:`interface` that the :term:`request` must have in order for
+  this view to be found and called.  See
+  :ref:`view_request_types_section` for more information about request
+  types.  For backwards compatibility with :mod:`repoze.bfg` version
+  1.0, this value may also be an HTTP ``REQUEST_METHOD`` string, e.g.
+  ('GET', 'HEAD', 'PUT', 'POST', or 'DELETE').  Passing request method
+  strings as a ``request_type`` is deprecated.  Use the
+  ``request_method`` attribute instead for maximum forward
+  compatibility.
+
+.. _view_lookup_ordering:
+
+View Lookup Ordering
+--------------------
+
+Attributes of the ZCML ``view`` directive can be thought of like
+"narrowers" or "predicates".  In general, the greater number of
+attributes possessed by a view directive, the more specific the
+circumstances need to be before the registered view will be called.
+
+For any given request, a view with five predicates will always be
+found and evaluated before a view with two, for example.  All
+predicatese must match for the associated view to be called.
+
+This does not mean however, that :mod:`repoze.bfg` "stops looking"
+when it finds a view registration with predicates that don't match.
+If one set of view predicates does not match, the "next most specific"
+view (if any) view is consulted for predicates, and so on, until a
+view is found, or no view can be matched up with the request.  The
+first view with a set of predicates all of which match the request
+environment will be invoked.
+
+If no view can be found which has predicates which allow it to be
+matched up with the request, :mod:`repoze.bfg` will return an error to
+the user's browser, representing a "not found" (404) page.  See
+:ref:`changing_the_notfound_view` for more information about changing
+the default notfound view.
+
+There are a several exceptions to the the rule which says that ZCML
+directive attributes represent "narrowings".  Several attributes of
+the ``view`` directive are *not* narrowing predicates.  These are
+``permission`` and ``name``.
+
+The value of the ``permission`` attribute represents the permission
+that must be possessed by the user to invoke any found view.  When a
+view is found that matches all predicates, but the invoking user does
+not possess the permission implied by any associated ``permission`` in
+the current context, processing stops, and an ``Unauthorized`` error
+is raised, usually resulting in a "forbidden" view being shown to the
+invoking user.  No further view narrowing or view lookup is done.
+
+.. note:: 
+
+   See :ref:`changing_the_forbidden_view` for more information about
+   changing the default forbidden view.
+
+The value of the ``name`` attribute represents a direct match of the
+view name returned via traversal.  It is part of intial view lookup
+rather than a predicate/narrower.
+
 .. _mapping_views_to_urls_using_a_decorator_section:
 
 Mapping Views to URLs Using a Decorator
@@ -281,7 +364,8 @@ more comfortable defining your view declarations using Python, you may
 use the ``repoze.bfg.view.bfg_view`` decorator to associate your view
 functions with URLs instead of using :term:`ZCML` for the same
 purpose.  ``repoze.bfg.view.bfg_view`` can be used to associate
-``for``, ``name``, ``permission`` and ``request_type`` information --
+``for``, ``name``, ``permission`` and ``request_method``,
+``containment``, ``request_param`` and ``request_type`` information --
 as done via the equivalent ZCML -- with a function that acts as a
 :mod:`repoze.bfg` view.
 
@@ -343,8 +427,9 @@ All arguments to ``bfg_view`` are optional.
 If ``name`` is not supplied, the empty string is used (implying
 the default view).
 
-If ``request_type`` is not supplied, the interface ``None`` is used,
-implying any request type.
+If ``request_type`` is not supplied, the value ``None`` is used,
+implying any request type.  Otherwise, this should be a class or
+interface.
 
 If ``for_`` is not supplied, the interface
 ``zope.interface.Interface`` (which matches any model) is used.
@@ -357,6 +442,21 @@ If ``route_name`` is supplied, the view will be invoked only if the
 named route matches.  *This is an advanced feature, not often used by
 "civilians"*.
 
+If ``request_method`` is supplied, the view will be invoked only if
+the ``REQUEST_METHOD`` of the request matches the value.
+
+If ``request_param`` is supplied, the view will be invoked only if the
+``request.params`` data structure contains a key matching the value
+provided.
+
+If ``containment`` is supplied, the view will be invoked only if a
+location parent supplies the interface or class implied by the
+provided value.
+
+View lookup ordering for views registered with the ``bfg_view``
+decorator is the same as for those registered via ZCML.  See
+:ref:`view_lookup_ordering` for more information.
+
 All arguments may be omitted.  For example:
 
 .. code-block:: python
@@ -371,8 +471,8 @@ All arguments may be omitted.  For example:
 
 Such a registration as the one directly above implies that the view
 name will be ``my_view``, registered ``for_`` any model type, using no
-permission, registered against requests which implement any request
-method or interface.
+permission, registered against requests with any request method /
+request type / request param / route name / containment.
 
 If your view callable is a class, the ``bfg_view`` decorator can also
 be used as a class decorator in Python 2.6 and better (Python 2.5 and
@@ -561,9 +661,10 @@ Custom View Request Types
 
 You can make use of *custom* view request types by attaching an
 :term:`interface` to the request and specifying this interface in the
-``request_type`` parameter.  For example, you might want to make use
-of simple "content negotiation", only invoking a particular view if
-the request has a content-type of 'application/json'.
+``request_type`` parameter as a dotted Python name.  For example, you
+might want to make use of simple "content negotiation", only invoking
+a particular view if the request has a content-type of
+'application/json'.
 
 For information about using interface to specify a request type, see
 :ref:`using_an_event_to_vary_the_request_type`.