From a0b40cc8aa58c557c30840c906fcba3401bb91cf Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 12 Jan 2009 05:12:57 +0000 Subject: - An interface specific to the HTTP verb (GET/PUT/POST/DELETE/HEAD) is attached to each request object on ingress. The HTTP-verb-related interfaces are defined in ``repoze.bfg.interfaces`` and are ``IGETRequest``, ``IPOSTRequest``, ``IPUTRequest``, ``IDELETERequest`` and ``IHEADRequest``. These interfaces can be specified as the ``request_type`` attribute of a bfg view declaration. A view naming a specific HTTP-verb-matching interface will be found only if the view is defined with a request_type that matches the HTTP verb in the incoming request. The more general ``IRequest`` interface can be used as the request_type to catch all requests (and this is indeed the default). All requests implement ``IRequest``. The HTTP-verb-matching idea was pioneered by `repoze.bfg.restrequest `_ . That package is no longer required, but still functions fine. --- docs/narr/views.rst | 43 +++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 41 insertions(+), 2 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 8cb00767a..3b60d1394 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -264,13 +264,52 @@ View Request Types You can optionally add a *request_type* attribute to your ``view`` declaration, which indicates what "kind" of request the view should be -used for. For example: +used for. If the request type for a request doesn't match the request +type that a view defines as its ``request_type`` argument, that view +won't be called. + +For example: .. code-block:: xml :linenos: + +The above example registers a view for the ``IPOSTRequest`` type, so +it will only be called if the request is a POST request. Even if all +the other specifiers match (e.g. the model type is the class +``.models.Hello``, and the view_name is ``handle_post``), if the +request verb is not POST, it will not be invoked. This provides a way +to ensure that views you write are only called via specific HTTP +verbs. + +The least specific request type is ``repoze.bfg.interfaces.IRequest``. +All requests are guaranteed to implement this request type. It is +also the default request type for views that omit a ``request_type`` +argument. + +:mod:`repoze.bfg` also makes available more specific request types +matching HTTP verbs. When these are specified as a ``request_type`` +for a view, the view will be called only when the request has an HTTP +verb (aka HTTP method) matching the request type. See +:ref:`interfaces_module` for more information about available request +types. + +Custom View Request Types +------------------------- + +You can make use of *custom* view request types. For example: + +.. code-block:: xml + :linenos: + +