Checklist.

1 files changed, 239 insertions, 0 deletions

diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst
index 8a7b86f2d..84a02f114 100644
--- a/docs/narr/urldispatch.rst
+++ b/docs/narr/urldispatch.rst
@@ -344,6 +344,18 @@ each other.  For routes added via the
 order that routes are evaluated is the order in which they are added
 to the configuration imperatively.
 
+For example, route configuration statements with the following
+patterns might be added in the following order:
+
+.. code-block:: text
+
+   members/:def
+   members/abc
+
+In such a configuration, the ``members/abc`` pattern would *never* be
+matched; this is because the match ordering will always match
+``members/:def`` first and ``members/abc`` will never be reached.
+
 .. index::
    pair: route; factory
 
@@ -379,6 +391,222 @@ can maintain a separate :term:`ACL`, as in
 wish to combine URL dispatch with :term:`traversal` as documented
 within :ref:`hybrid_chapter`.
 
+Route Configuration Arguments
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Route configuration statements may specify a large number of
+arguments.
+
+Many of these arguments are :term:`route predicate` arguments.  A
+route predicate argument specifies that some aspect of the request
+must be true for the associated route to be considered a match during
+the route matching process.
+
+Other arguments are view configuration related arguments.  These only
+have an effect when the route configuration names a ``view``.
+
+Other arguments are ``name`` and ``factory``.  These are required
+arguments but represent neither a predicate nor view configuration
+information.
+
+Non-Predicate Arguments
++++++++++++++++++++++++
+
+``name``
+
+  The name of the route, e.g. ``myroute``.  This attribute is
+  required.  It must be unique among all defined routes in a given
+  application.
+
+``factory``
+
+  A reference to a Python object (often a function or a class) that
+  will generate a :mod:`repoze.bfg` :term:`context` object when this
+  route matches. For example, ``mypackage.models.MyFactoryClass``.  If
+  this argument is not specified, the traversal root factory will be
+  used.
+
+Predicate Arguments
++++++++++++++++++++
+
+``path``
+
+  The path of the route e.g. ``ideas/:idea``.  This argument is
+  required.  See :ref:`route_path_pattern_syntax` for information
+  about the syntax of route paths.  If the path doesn't match the
+  current URL, route matching continues.
+
+``xhr``
+
+  This value should be either ``True`` or ``False``.  If this value is
+  specified and is ``True``, the :term:`request` must possess an
+  ``HTTP_X_REQUESTED_WITH`` (aka ``X-Requested-With``) header for this
+  route to match.  This is useful for detecting AJAX requests issued
+  from jQuery, Prototype and other Javascript libraries.  If this
+  predicate returns ``False``, route matching continues.
+
+``request_method``
+
+  A string representing an HTTP method name, e.g. ``GET``, ``POST``,
+  ``HEAD``, ``DELETE``, ``PUT``.  If this argument is not specified,
+  this route will match if the request has *any* request method.  If
+  this predicate returns ``False``, route matching continues.
+
+``path_info``
+
+  This value represents a regular expression pattern that will be
+  tested against the ``PATH_INFO`` WSGI environment variable.  If the
+  regex matches, this predicate will return ``True``.  If this
+  predicate returns ``False``, route matching continues.
+
+``request_param``
+
+  This value can be any string.  A view declaration with this argument
+  ensures that the associated route will only match 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 as the argument 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 route to
+  "match" the current request.  If this predicate returns ``False``,
+  route matching continues.
+
+``header``
+
+  This argument represents an HTTP header name or a header name/value
+  pair.  If the argument contains a ``:`` (colon), it will be
+  considered a name/value pair (e.g. ``User-Agent:Mozilla/.*`` or
+  ``Host:localhost``).  If the value contains a colon, the value
+  portion should be a regular expression.  If the value does not
+  contain a colon, the entire value will be considered to be the
+  header name (e.g. ``If-Modified-Since``).  If the value evaluates to
+  a header name only without a value, the header specified by the name
+  must be present in the request for this predicate to be true.  If
+  the value evaluates to a header name/value pair, the header
+  specified by the name must be present in the request *and* the
+  regular expression specified as the value must match the header
+  value.  Whether or not the value represents a header name or a
+  header name/value pair, the case of the header name is not
+  significant.  If this predicate returns ``False``, route matching
+  continues.
+
+``accept``
+
+  This value represents a match query for one or more mimetypes in the
+  ``Accept`` HTTP request header.  If this value is specified, it must
+  be in one of the following forms: a mimetype match token in the form
+  ``text/plain``, a wildcard mimetype match token in the form
+  ``text/*`` or a match-all wildcard mimetype match token in the form
+  ``*/*``.  If any of the forms matches the ``Accept`` header of the
+  request, this predicate will be true.  If this predicate returns
+  ``False``, route matching continues.
+
+``custom_predicates``
+
+  This value should be a sequence of references to custom predicate
+  callables.  Use custom predicates when no set of predefined
+  predicates does what you need.  Custom predicates can be combined
+  with predefined predicates as necessary.  Each custom predicate
+  callable should accept two arguments: ``context`` and ``request``
+  and should return either ``True`` or ``False`` after doing arbitrary
+  evaluation of the context and/or the request.  If all callables
+  return ``True``, the associated route will be considered viable for
+  a given request.  If any custom predicate returns ``False``, route
+  matching continues.  Note that the value ``context`` will always be
+  ``None`` when passed to a custom route predicate.
+
+View-Related Arguments
+++++++++++++++++++++++
+
+``view``
+
+  A reference to a Python object that will be used as a view callable
+  when this route matches. e.g. ``mypackage.views.my_view``.
+  
+``view_context``
+
+  A reference to a class or an :term:`interface` that the
+  :term:`context` of the view should match for the view named by the
+  route to be used.  This argument is only useful if the ``view``
+  attribute is used.  If this attribute is not specified, the default
+  (``None``) will be used.
+
+  If the ``view`` argument is not provided, this argument has
+  no effect.
+
+  This attribute can also be spelled as ``for_`` or ``view_for``.
+
+``view_permission``
+
+  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 argument has
+  no effect.
+
+  This argument can also be spelled as ``permission``.
+
+``view_renderer``
+
+  This is either a single string term (e.g. ``json``) or a string
+  implying a path or :term:`resource specification`
+  (e.g. ``templates/views.pt``).  If the renderer value is a single
+  term (does not contain a dot ``.``), the specified term will be used
+  to look up a renderer implementation, and that renderer
+  implementation will be used to construct a response from the view
+  return value.  If the renderer term contains a dot (``.``), the
+  specified term will be treated as a path, and the filename extension
+  of the last element in the path will be used to look up the renderer
+  implementation, which will be passed the full path.  The renderer
+  implementation will be used to construct a response from the view
+  return value.  See :ref:`views_which_use_a_renderer` for more
+  information.
+
+  If the ``view`` argument is not provided, this argument has
+  no effect.
+
+  This argument can also be spelled as ``renderer``.
+
+``view_request_type``
+
+  A reference to an :term:`interface` representing a :term:`request
+  type`.  If this argument is not specified, any request type will be
+  considered a match for the view associated with this route.
+
+  If the ``view`` argument is not provided, this argument has
+  no effect.
+
+  This argument can also be spelled as ``request_type``.
+
+``view_containment``
+
+  This value should be a reference to a Python class or
+  :term:`interface` that a parent object in the :term:`lineage` must
+  provide in order for the view related to this route 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`` argument is not provided, this argument has no
+  effect.
+
+``view_attr``
+
+  The view machinery defaults to using the ``__call__`` method of the
+  view callable (or the function itself, if the view callable is a
+  function) to obtain a response dictionary.  The ``attr`` value
+  allows you to vary the method attribute used to obtain the response.
+  For example, if your view was a class, and the class has a method
+  named ``index`` and you wanted to use this method instead of the
+  class' ``__call__`` method to return the response, you'd say
+  ``attr="index"`` in the view configuration for the view.  This is
+  most useful when the view definition is a class.
+
+  If the ``view`` argument is not provided, this argument has no
+  effect.
+
 Route Matching
 --------------
 
@@ -400,10 +628,21 @@ otherwise known as :term:`context finding`.  During view lookup, if
 any ``view`` argument was provided within the matched route
 configuration, the :term:`view callable` it points to is called.
 
+When a route configuration is declared, it may contain :term:`route
+predicate` arguments.  All route predicates associated with a route
+declaration must be ``True`` for the route configuration to be used
+for a given request.
+
+If any predicate in the set of :term:`route predicate` arguments
+provided to a route configuration returns ``False``, that route is
+skipped and route matching continues through the ordered set of
+routes.
+
 If no route matches after all route patterns are exhausted,
 :mod:`repoze.bfg` falls back to :term:`traversal` to do :term:`context
 finding` and :term:`view lookup`.
 
+
 .. index::
    pair: URL dispatch; matchdict