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

1 files changed, 76 insertions, 0 deletions

diff --git a/docs/zcml/forbidden.rst b/docs/zcml/forbidden.rst
new file mode 100644
index 000000000..7540c28cb
--- /dev/null
+++ b/docs/zcml/forbidden.rst
@@ -0,0 +1,76 @@
+.. _forbidden_directive:
+
+``forbidden``
+-------------
+
+When :mod:`repoze.bfg` can't authorize execution of a view based on
+the :term:`authorization policy` in use, it invokes a :term:`forbidden
+view`.  The default forbidden response has a 401 status code and is
+very plain, but it can be overridden as necessary using the
+``forbidden`` ZCML directive.
+
+Attributes
+~~~~~~~~~~
+
+``view``
+
+  The :term:`dotted Python name` to a :term:`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`).
+
+``attr``
+
+  The attribute of the view callable to use if ``__call__`` is not
+  correct (has the same meaning as in the context of
+  :ref:`view_directive`; see the description of ``attr``
+  there).
+
+  .. 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``) used when the view returns a
+  non-:term:`response` object.  This attribute has the same meaning as
+  it would in the context of :ref:`view_directive`; see the
+  description of ``renderer`` there).
+
+  .. 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.  This attribute has the same meaning
+  as it would in the context of :ref:`view_directive`; see the
+  description of ``wrapper`` there).  Note that the wrapper view
+  *should not* be protected by any permission; behavior is undefined
+  if it does.
+
+  .. note:: This feature is new as of :mod:`repoze.bfg` 1.1.
+
+Example
+~~~~~~~
+
+.. code-block:: xml
+   :linenos:
+
+   <forbidden
+       view="helloworld.views.forbidden_view"/>
+
+Alternatives
+~~~~~~~~~~~~
+
+The :meth:`repoze.bfg.configuration.Configurator.set_forbidden_view`
+method performs the same job as the ``forbidden`` ZCML directive.
+
+See Also
+~~~~~~~~
+
+See also :ref:`changing_the_forbidden_view`.