= 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)]]