- Created new top-level documentation section: "ZCML Directives".

  This section contains detailed ZCML directive information, some of
  which was removed from various narrative chapters.

1 files changed, 12 insertions, 277 deletions

diff --git a/docs/narr/views.rst b/docs/narr/views.rst
index a073bb6d8..5f9eb9140 100644
--- a/docs/narr/views.rst
+++ b/docs/narr/views.rst
@@ -331,254 +331,7 @@ A ZCML ``view`` declaration's ``view`` attribute can also name a
 class.  In this case, the rules described in :ref:`class_as_view`
 apply for the class which is named.
 
-.. _the_view_zcml_directive:
-
-The ``view`` ZCML Directive
-+++++++++++++++++++++++++++
-
-The ``view`` ZCML directive has many possible attributes.  Some of the
-attributes are descriptive or influence rendering.  Other attributes
-are :term:`predicate` attributes, meaning that they imply an
-evaluation to true or false when view lookup is performed.
-
-*All* predicates named in a view configuration must evaluate to true
-in order for the view callable it names to be considered "invokable"
-for a given request.  See :ref:`view_lookup_ordering` for a
-description of how a view configuration matches (or doesn't match)
-during a request.
-
-The possible attributes of the ``view`` ZCML directive are described
-below.  They are divided into predicate and non-predicate categories.
-
-Non-Predicate Attributes
-########################
-
-view
-
-  The Python dotted-path name to the view callable.  This attribute is
-  required unless a ``renderer`` attribute also exists.  If a
-  ``renderer`` attribute exists on the directive, this attribute
-  defaults to a view that returns an empty dictionary (see
-  :ref:`views_which_use_a_renderer`).
-
-permission
-
-  The name of a *permission* that the user must possess in order to
-  call the view.  See :ref:`view_security_section` for more
-  information about view security and permissions.
-
-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.
-
-  .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
-
-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.
-
-  Note that if the view itself returns a response (see
-  :ref:`the_response`), the specified renderer implementation is never
-  called.
-
-  When the renderer is a path, although a path is usually just a
-  simple relative pathname (e.g. ``templates/foo.pt``, implying that a
-  template named "foo.pt" is in the "templates" directory relative to
-  the directory in which the ZCML file is defined), a path can be
-  absolute, starting with a slash on UNIX or a drive letter prefix on
-  Windows.  The path can alternately be a :term:`resource
-  specification` in the form
-  ``some.dotted.package_name:relative/path``, making it possible to
-  address template resources which live in a separate package.
-
-  The ``renderer`` attribute is optional.  If it is not defined, the
-  "null" renderer is assumed (no rendering is performed and the value
-  is passed back to the upstream BFG machinery unmolested).
-
-  .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
-
-wrapper
-
-  The :term:`view name` (*not* an object dotted name) of another view
-  declared elsewhere in ZCML (or via the ``@bfg_view`` decorator)
-  which will receive the response body of this view as the
-  ``request.wrapped_body`` attribute of its own request, and the
-  response returned by this view as the ``request.wrapped_response``
-  attribute of its own request.  Using a wrapper makes it possible to
-  "chain" views together to form a composite response.  The response
-  of the outermost wrapper view will be returned to the user.  The
-  wrapper view will be found as any view is found: see
-  :ref:`view_lookup_ordering`.  The "best" wrapper view will be found
-  based on the lookup ordering: "under the hood" this wrapper view is
-  looked up via ``repoze.bfg.view.render_view_to_response(context,
-  request, 'wrapper_viewname')``. The context and request of a wrapper
-  view is the same context and request of the inner view.  If this
-  attribute is unspecified, no view wrapping is done.
-
-  .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
-
-Predicate Attributes
-####################
-
-name
-
-  The *view name*.  Read the :ref:`traversal_chapter` to understand
-  the concept of a view name.
-
-for
-
-  A Python dotted-path name representing the Python class that the
-  :term:`context` must be an instance of, *or* the :term:`interface`
-  that the :term:`context` must provide in order for this view to be
-  found and called.  This predicate is true when the :term:`context`
-  is an instance of the represented class or if the :term:`context`
-  provides the represented interface; it is otherwise false.
-
-route_name
-
-  *This attribute services an advanced feature that isn't often used
-  unless you want to perform traversal *after* a route has matched.*
-  This value must match the ``name`` of a ``<route>`` declaration (see
-  :ref:`urldispatch_chapter`) that must match before this view will be
-  called.  Note that the ``route`` configuration referred to by
-  ``route_name`` usually has a ``*traverse`` token in the value of its
-  ``path``, representing a part of the path that will be used by
-  traversal against the result of the route's :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.  The presence of this attribute is
-  largely for backwards compatibility with applications written for
-  :mod:`repoze.bfg` version 1.0.  This value may 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.
-
-request_method
-
-  This value can either be one of the strings 'GET', 'POST', 'PUT',
-  '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.
-
-  .. 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 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.
-
-  .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
-
-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.
-
-  .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
-
-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 that has
-  the value ``XMLHttpRequest`` for this view to be found and called.
-  This is useful for detecting AJAX requests issued from jQuery,
-  Prototype and other Javascript libraries.
-
-  .. 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.
-
-  .. 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.
-
-  .. 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.
-
-  .. 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 (e.g. ``dotted.name.one dotted.name.two``, if used in
-  ZCML; Python dotted names to callables separated by spaces).  Use
-  custom predicates when no set of predefined predicates do 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 view callable will be considered viable for a given
-  request.
-
-  .. note:: This feature is new as of :mod:`repoze.bfg` 1.2.
+See :ref:`view_directive` for complete ZCML directive documentation.
 
 .. _mapping_views_to_urls_using_a_decorator_section:
 
@@ -691,7 +444,7 @@ Or replaces the need to add this imperative configuration stanza:
 All arguments to :class:`repoze.bfg.view.bfg_view` are optional.
 Every argument to :class:`repoze.bfg.view.bfg_view` matches the
 meaning of the same-named attribute in ZCML view configuration
-described in :ref:`the_view_zcml_directive`.
+described in :ref:`view_directive`.
 
 If ``name`` is not supplied, the empty string is used (implying
 the default view).
@@ -738,9 +491,8 @@ If ``xhr`` is specified, it must be a boolean value.  If the value is
 If ``accept`` is specified, it must be a mimetype value.  If
 ``accept`` is specified, the view will only be invoked if the
 ``Accept`` HTTP header matches the value requested.  See the
-description of ``accept`` in :ref:`the_view_zcml_directive` for
-information about the allowable composition and matching behavior of
-this value.
+description of ``accept`` in :ref:`view_directive` for information
+about the allowable composition and matching behavior of this value.
 
 If ``header`` is specified, it must be a header name or a
 ``headername:headervalue`` pair.  If ``header`` is specified, and
@@ -748,8 +500,8 @@ possesses a value the view will only be invoked if an HTTP header
 matches the value requested.  If ``header`` is specified without a
 value (a bare header name only), the view will only be invoked if the
 HTTP header exists with any value in the request.  See the description
-of ``header`` in :ref:`the_view_zcml_directive` for information about
-the allowable composition and matching behavior of this value.
+of ``header`` in :ref:`view_directive` for information about the
+allowable composition and matching behavior of this value.
 
 View lookup ordering for views registered with the
 :class:`repoze.bfg.view.bfg_view` decorator is the same as for those
@@ -1387,6 +1139,8 @@ tag):
    <renderer
       factory="repoze.bfg.renderers.json_renderer_factory"/>
 
+See also :ref:`renderer_directive`.
+
 .. _view_security_section:
 
 View Security
@@ -1463,29 +1217,6 @@ Use of the imperative configuration method
 :meth:`repoze.bfg.configuration.configurator.add_static_view` is
 completely equivalent to using ZCML for the same purpose.
 
-The ZCML directive can accept three attributes:
-
-name
-
-  The (application-root-relative) URL prefix of the static directory.
-  For example, to serve static files from ``/static`` in most
-  applications, you would provide a ``name`` of ``static``.
-
-path
-
-  A path to a directory on disk where the static files live.  This
-  path may either be 1) absolute (e.g. ``/foo/bar/baz``) 2)
-  Python-package-relative (e.g. (``packagename:foo/bar/baz``) or 3)
-  relative to the package directory in which the ZCML file which
-  contains the directive (e.g. ``foo/bar/baz``).
-
-cache_max_age
-
-  The number of seconds that the static resource can be cached, as
-  represented in the returned response's ``Expires`` and/or
-  ``Cache-Control`` headers, when any static file is served from this
-  directive.  This defaults to 3600 (5 minutes).
-
 Here's an example of a ``static`` ZCML directive that will serve files
 up ``/static`` URL from the ``/var/www/static`` directory of the
 computer which runs the :mod:`repoze.bfg` application.
@@ -1533,9 +1264,13 @@ directive's ``path`` is ``/path/to/static``,
 subdirectories recursively, and any subdirectories may hold files;
 these will be resolved by the static view as you would expect.
 
+See :ref:`static_directive` for detailed information.
+
 .. note:: The ``<static>`` ZCML directive is new in :mod:`repoze.bfg`
    1.1.
 
+.. _generating_static_resource_urls:
+
 Generating Static Resource URLs
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~