From 13c923f6eaf56a49897af75e14c1f70d1b26c75b Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Tue, 24 Nov 2009 20:49:16 +0000 Subject: Docs updates. --- docs/narr/hooks.rst | 252 +++++++++++++++++++++++++++++++--------------------- 1 file changed, 153 insertions(+), 99 deletions(-) (limited to 'docs/narr/hooks.rst') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index f5fc4233b..7ed0172fc 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -1,9 +1,9 @@ .. _hooks_chapter: -Using ZCML Hooks -================ +Using Hooks +=========== -ZCML "hooks" can be used to influence the behavior of the +"hooks" can be used to influence the behavior of the :mod:`repoze.bfg` framework in various ways. .. _changing_the_notfound_view: @@ -12,19 +12,82 @@ Changing the Not Found View --------------------------- When :mod:`repoze.bfg` can't map a URL to view code, it invokes a -notfound :term:`view`. The view it invokes can be customized by -placing something like the following ZCML in your ``configure.zcml`` -file. +notfound :term:`view`. The view it invokes can be customized through +application configuration. -.. code-block:: xml - :linenos: +.. topic:: Using ZCML + + If your application uses :term:`ZCML`, you can replace the Not Found + view by placing something like the following ZCML in your + ``configure.zcml`` file. + + .. code-block:: xml + :linenos: + + + + Replace ``helloworld.views.notfound_view`` with the Python dotted name + to the notfound view you want to use. + + Other available attributes of the ``notfound`` ZCML directive are as + follows: + + attr + + The attribute of the view callable to use if ``__call__`` is not + correct (has the same meaning as in the context of + :ref:`the_view_zcml_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:`the_view_zcml_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:`the_view_zcml_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. -Replace ``helloworld.views.notfound_view`` with the Python dotted name -to the notfound view you want to use. Here's some sample code that -implements a minimal NotFound view: +.. topic:: Using Imperative Configuration + + If your application uses :term:`imperative configuration`, you can + replace the Not Found view by using the ``set_notfound_view`` + method of the ``Configurator`` named ``config``: + + .. code-block:: python + :linenos: + + import helloworld.views + config.set_notfound_view(helloworld.views.notfound_view) + + Replace ``helloworld.views.notfound_view`` with a reference to the + Python :term:`view callable` you want to use to represent the Not + Found view. + + See :ref:`configuration_module` for more information about other + arguments to the ``set_notfound_view`` method. + +Here's some sample code that implements a minimal NotFound view: .. code-block:: python :linenos: @@ -41,68 +104,98 @@ implements a minimal NotFound view: This error will be different when the ``debug_notfound`` environment setting is true than it is when it is false. -Other available attributes of the ``notfound`` ZCML directive are as -follows: +.. _changing_the_forbidden_view: -attr +Changing the Forbidden View +--------------------------- - The attribute of the view callable to use if ``__call__`` is not - correct (has the same meaning as in the context of - :ref:`the_view_zcml_directive`; see the description of ``attr`` - there). +When :mod:`repoze.bfg` can't authorize execution of a view based on +the authorization policy in use, it invokes a "forbidden view". The +default forbidden response has a 401 status code and is very plain, +but it can be overridden as necessary using one of the following +mechanisms: - .. note:: This feature is new as of :mod:`repoze.bfg` 1.1. +.. topic:: Using ZCML -renderer + If your application uses :term:`ZCML`, you can replace the + Forbidden view by placing something like the following ZCML in your + ``configure.zcml`` file. - 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:`the_view_zcml_directive`; see the - description of ``renderer`` there). + .. code-block:: xml + :linenos: - .. 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:`the_view_zcml_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. + Replace ``helloworld.views.forbidden_view`` with the Python + dotted name to the forbidden view you want to use. - .. note:: This feature is new as of :mod:`repoze.bfg` 1.1. + Other available attributes of the ``forbidden`` ZCML directive are as + follows: -.. _changing_the_forbidden_view: + attr -Changing the Forbidden View ---------------------------- + The attribute of the view callable to use if ``__call__`` is not + correct (has the same meaning as in the context of + :ref:`the_view_zcml_directive`; see the description of ``attr`` + there). -When :mod:`repoze.bfg` can't authorize execution of a view based on -the authorization policy in use, it invokes a "forbidden view". The -default forbidden response has a 401 status code and is very plain, -but it can be overridden as necessary by placing something like the -following ZCML in your ``configure.zcml`` file. + .. note:: This feature is new as of :mod:`repoze.bfg` 1.1. -.. code-block:: xml - :linenos: + 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:`the_view_zcml_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:`the_view_zcml_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. + +.. topic:: Using Imperative Configuration + + If your application uses :term:`imperative configuration`, you can + replace the Forbidden view by using the ``set_forbidden_view`` + method of the ``Configurator`` named ``config``: + + .. code-block:: python + :linenos: - + import helloworld.views + config.set_forbiddden_view(helloworld.views.forbidden_view) -Replace ``helloworld.views.forbidden_view`` with the Python -dotted name to the forbidden view you want to use. Like any other -view, the forbidden view must accept two parameters: ``context`` and -``request`` . The ``context`` is the context found by the router when -the view invocation was denied. The ``request`` is the current -:term:`request` representing the denied action. Here's some sample -code that implements a minimal forbidden view: + Replace ``helloworld.views.forbidden_view`` with a reference to the + Python :term:`view callable` you want to use to represent the + Forbidden view. + + See :ref:`configuration_module` for more information about other + arguments to the ``set_forbidden_view`` method. + +Like any other view, the forbidden view must accept at least a +``request`` parameter, or both ``context`` and ``request``. The +``context`` (available as ``request.context`` if you're using the +request-only view argument pattern) is the context found by the router +when the view invocation was denied. The ``request`` is the current +:term:`request` representing the denied action. + +Here's some sample code that implements a minimal forbidden view: .. code-block:: python :linenos: @@ -126,45 +219,6 @@ code that implements a minimal forbidden view: an alternate forbidden view. For example, it would make sense to return a response with a ``403 Forbidden`` status code. -Other available attributes of the ``forbidden`` ZCML directive are as -follows: - -attr - - The attribute of the view callable to use if ``__call__`` is not - correct (has the same meaning as in the context of - :ref:`the_view_zcml_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:`the_view_zcml_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:`the_view_zcml_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. - - Changing the response factory ----------------------------- -- cgit v1.2.3