Handlers are Python functions that are responsible for processing the remote clients request and storing the results of this request in the interface namespace. The templates then read this interface and format the results.
There is a one to one correspondence between handlers and templates: exactly one handler function corresponds to exactly one template. We have already seen how to define a handler function for a specific template. You must subclass Draco's Handler class (found in draco.handler) and put it in a file named __handler__.py in the same directory as the template. Methods in this class correspond to templates with the same name plus the default extension. So, for example, the following Python fragment defines a handler function for the template hello.dsp4.1.
from draco.handler import Handler class MyHandler(Handler): def hello(self, path, args): pass
The handler function is passed path and args parameters that
together describe the request. The path parameter contains a list of
path components that were given after the template name. Empty path
components are eliminated. This parameter corresponds to CGI's
$PATH_INFO
parameter.
The args parameter is a namespace describing the GET and POST parameters that were passed with the request. The namespace is indexed by variable name. The values are either Python strings -- in the case of simple parameters -- or a FileUpload instance -- in the case of a file upload parameter. If there were multiple parameters with the same name, a list of strings and FileUpload instances is returned.
The results of the action performed in the handler are communicated to the template via the interface. The interface is a namespace that can contain variables of any Python type including class instances.
Handlers can also be used for authentication purposes. To control access to a certain resource, you can define a method __authenticate__ in your handler class. This function controls access to all templates in the directory.
template) |
AUTH_OK
. If not,
AUTH_DENY
should be returned instead. Note that the template
argument is the name of the requested template without extension.
Both AUTH_OK
and AUTH_DENY
are data members of the
Handler class:
If Draco finds no handler for a requested template, it checks whether a handler function with the name __default__ is defined in the handler class. If it is, it is used as the handler function for the template. This can be used to implement a "catch all" handlers for all requests in a directory.
path, args) |
If the default handler is not found, Draco performs the same as if the handler were empty. A template can still exist but it will have an empty interface. This can be used for serving static html pages, while still having some of Draco's advantages like session management and image size detection.
Oppositely, it is also possbible to have a handler without an accompanying template. In this case, the handler function itself is responsible for writing the output to the client. This can be done using the response object, see section 5.2.5. A handler without template is useful when for example you want to generate an image on the fly.
The normal way to finish a http request is to return from the handler function. The template (if it exists) will be parsed and written to the client. The HTTP request exits with a code 200 (HTTP_OK).
There are two other ways to exit from a handler. The first way is to raise one of the HttpResponse exceptions, which can be useful in error situations. For more information on these exceptions, see section 5.1. The second way to exit from a handler is to call a nonreturing function. Draco's response object contains two function that do not return: redirect() and exit().