= Request Handlers = A request handler is a neutral name for what some other frameworks call “controllers” or “views”. It is simply a Python function that accepts the request and response objects as parameters, and returns a response. {{{ #!python from diva.templating import output, render @output('index.html') def index(request, response): return render(message='Hello, world!') }}} This defines a function called `index` that will respond to requests by rendering the template `index.html`. == URL Parts as Parameters == Any dynamic parts of the URLs defined in the UrlRouting are passed to the request handler as additional parameters. For example: {{{ #!python from datetime import datetime from diva import app from diva.templating import output, render @output('index.html') def monthly(request, response, year, month): return render(month=datetime(year, month, 1)) app.routing.add('/archives/{year:\d+}/{month:\d+}/', monthly) }}} Note that in this particular case, the values for `year` and `month` are automatically converted to numbers, due to the use of the `\d+` pattern in the route path. == Rendering Genshi Templates == The `diva.templating` module provides convenience functions for rendering Genshi templates. First, there's the `@output` decorator, which you use to specify the name of the template file, the serialization method, the response MIME type and encoding, and other serialization options such as the `DOCTYPE` to use and so on. {{{ #!python from diva.templating import output, render @output('index.html', method='html', doctype='html-strict') def index(request, response): return render(message='Hello, world!') }}} Note that all of the arguments to `@output` are optional. For example, you can omit the template file name for a response that doesn't involve template rendering, and just use the `mimetype` and `encoding` options: {{{ #!python @caching(max_age=timedelta(days=7)) @output(mimetype='text/css', encoding='utf-8') def style(request, response, font_size=1): return 'html { font-size: %sem; }' % font_size }}} If you do want to render a template, use the `render()` function to return a Genshi stream from the request handler. You pass any template data into the `render()` function as keyword arguments, and it will generate an output stream from the template based on the template data. The `render()` function also lets you override the template filename specified using the `@output` decorator: simple pass the template name as the first (and only) positional argument into `render()`. === Default Template Data === Diva makes a number of objects available for use in Genshi templates by default: `app`:: The [ApplicationObject Application] object `abs_url()`:: Function for converting relative paths to absolute URLs `attrgetter`:: Function from the Python `operator` module `classes`:: Helper function to generate CSS class names for use in HTML templates `date`:: Python `date` class from the `datetime` module `datetime`:: Python `datetime` class from the `datetime` module `_()` / `gettext()`:: Function for translating a message `HTML()`:: Function to parse a string as HTML and return a markup stream `group`:: Helper function for splitting flat lists up into groups of items (like columns) `groupby`:: Function from the Python `itertools` module `itemgetter`:: Function from the Python `operator` module `ngettext()`:: Function for translating a message including plural forms `path_to()`:: Function for generating URLs based on the [UrlRouting routing configuration] `request`:: The `Request` object `response`:: The `Response` object `separated`:: Helper function that adds separator strings to a list of strings `time`:: Python `time` class from the `datetime` module `timedelta`:: Python `timedelta` class from the `datetime` module `truncate`:: Helper function that truncates a string to a specified limit of characters `XML()`:: Function to parse a string as XML and return a markup stream == Builtin Request Handlers == Diva comes with a couple of generic request handlers that can be used as-is with some parameterization in UrlRouting. `diva.routing:delegate`:: Delegate request processing to a different WSGI application. `diva.routing:redirect`:: Send an HTTP redirect to a different URL `diva.static:directory`:: Serve static files from a specific directory `diva.static:file`:: Serve a specific static file `diva.templating:view`:: Render a given template == API Documentation == [[PythonDoc(trunk, diva.http)]] [[PythonDoc(trunk, diva.templating)]]