Using a single chapter for the API docs and a single chapter for the ZCML directives made it hard to read.

1 files changed, 233 insertions, 0 deletions

diff --git a/docs/zcml/route.rst b/docs/zcml/route.rst
new file mode 100644
index 000000000..d3181bdf6
--- /dev/null
+++ b/docs/zcml/route.rst
@@ -0,0 +1,233 @@
+.. _route_directive:
+
+``route``
+---------
+
+The ``route`` directive adds a single :term:`route configuration` to
+the :term:`application registry`.
+
+Attributes
+~~~~~~~~~~
+
+``path``
+
+  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 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 :term:`dotted Python 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``
+
+  The :term:`dotted Python name` to a function that will be used as a
+  view callable when this route matches.
+  e.g. ``mypackage.views.my_view``.
+
+``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.
+
+  .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
+
+``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.
+
+  .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
+
+``path_info``
+
+  The value of this attribute represents a regular expression pattern
+  that will be tested against the ``PATH_INFO`` WSGI environment
+  variable.  If the regex matches, this predicate will be true.  If
+  this predicate returns false, route matching continues.
+
+  .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
+
+``request_param``
+
+  This value can be any string.  A view declaration with this
+  attribute 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 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 route to "match" the current request.  If this predicate
+  returns false, route matching continues.
+
+  .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
+
+``header``
+
+  The value of this attribute represents an HTTP header name or a
+  header name/value pair.  If the value contains a ``:`` (colon), it
+  will be considered a name/value pair (e.g. ``User-Agent:Mozilla/.*``
+  or ``Host:localhost``).  The *value* of an attribute that represent
+  a name/value pair 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.
+
+  .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
+
+``accept``
+
+  The value of this attribute 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.
+
+  .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
+
+``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.
+
+  .. note:: This feature is new as of :mod:`repoze.bfg` 1.2.
+
+``view_context``
+
+  The :term:`dotted Python name` to a class or an interface that the
+  :term:`context` of the view should match for the view named by the
+  route to be used.  This attribute is only useful if the ``view``
+  attribute is used.  If this attribute is not specified, the default
+  (``None``) will be used.
+
+  If the ``view`` attribute is not provided, this attribute has no
+  effect.
+
+  This attribute can also be spelled as ``view_for`` or ``for_``;
+  these are valid older spellings.
+
+``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 attribute has no
+  effect.
+
+  This attribute 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`` attribute is not provided, this attribute has no
+  effect.
+
+  This attribute can also be spelled as ``renderer``.
+
+  .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
+
+``view_request_type``
+
+  A :term:`dotted Python name` to an 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`` attribute is not provided, this attribute has no
+  effect.
+
+  This attribute can also be spelled as ``request_type``.
+
+``view_containment``
+
+  This value should be a :term:`dotted Python name` 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.
+
+  .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
+
+``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`` attribute is not provided, this attribute has no
+  effect.
+
+  .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
+
+Alternatives
+~~~~~~~~~~~~
+
+You can also add a :term:`route configuration` via:
+
+- Using the :meth:`repoze.bfg.configuration.Configurator.add_route` method.
+
+See Also
+~~~~~~~~
+
+See also :ref:`urldispatch_chapter`.