From 7d1da854e77b56ab6e50f0b8a3e0e61d8ebfb7a7 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 25 May 2009 01:37:25 +0000 Subject: IForbiddenAppFactory -> IForbiddenResponseFactory. --- docs/narr/hooks.rst | 42 +++++++++++++++++++++++------------------- 1 file changed, 23 insertions(+), 19 deletions(-) (limited to 'docs') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index aefa95046..6428408e8 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -124,40 +124,44 @@ sample code that implements a minimal NotFound application factory: ``debug_notfound`` environment setting is true than it is when it is false. -Changing the Forbidden Application ----------------------------------- +Changing the Forbidden Response +------------------------------- When :mod:`repoze.bfg` can't authorize execution of a view based on -the security policy in use, it creates and invokes a Forbidden WSGI -application. The application it invokes can be customized by placing -something like the following ZCML in your ``configure.zcml`` file. +the security policy in use, it invokes a "forbidden response factory". +Usually this forbidden response factory is serviced by the currently +active :term:`security policy`, but it can be overridden as necessary +by placing something like the following ZCML in your +``configure.zcml`` file. .. code-block:: xml :linenos: - + Replace ``helloworld.factories.forbidden_app_factory`` with the Python -dotted name to the WSGI application factory you want to use. Here's -some sample code that implements a minimal Unauthorized application -factory: +dotted name to the forbidden response factory you want to use. The +response factory 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 response factory: .. code-block:: python from repoze.bfg.chameleon_zpt import render_template_to_response - def forbidden_app_factory(context, request): + def forbidden_response_factory(context, request): return render_template_to_response('templates/login_form.pt') -.. note:: When an Forbidden application factory is invoked, it is - passed the WSGI environ and the WSGI ``start_response`` handler by - :mod:`repoze.bfg`. Within the WSGI environ will be a key named - ``repoze.bfg.message`` that has a value explaining why the action - was forbidden. This error will be different when the - ``debug_authorization`` environment setting is true than it is when - it is false. A WebOb ``Response`` object is a valid WSGI - application, by the way. +.. note:: When an forbidden response factory is invoked, it is passed + the request as the second argument. An attribute of the request is + ``environ``, which is the WSGI environment. Within the WSGI + environ will be a key named ``repoze.bfg.message`` that has a value + explaining why the current view invocation was forbidden. This + error will be different when the ``debug_authorization`` + environment setting is true than it is when it is false. .. warning:: the default forbidden application factory sends a response with a ``401 Unauthorized`` status code for backwards -- cgit v1.2.3