Module controllers

Validate input.

Parameters:

• form (a form instance) - a form instance that must be passed throught the validation process... you must give a the same form instance as the one that will be used to post data on the controller you are putting the validate decorator on.
• validators (dictionnary or schema instance) - individual validators to use for parameters. If you use a schema for validation then the schema instance must be the sole argument. If you use simple validators, then you must pass a dictionnary with each value name to validate as a key of the dictionnary and the validator instance (eg: tg.validators.Int() for integer) as the value.
• failsafe_schema (???) - TODO: complete this docstring fail-safe schema.
• failsafe_values (???) - TODO: complete this docstring replacements for erroneous inputs
• state_factory (???) - TODO: complete this docstring callable which returns the initial state instance for validation

Exposes a method to the web.

By putting the expose decorator on a method, you tell TurboGears that
the method should be accessible via URL traversal. Additionally, expose
handles the output processing (turning a dictionary into finished
output) and is also responsible for ensuring that the request is
wrapped in a database transaction.

You can apply multiple expose decorators to a method, if
you'd like to support multiple output formats. The decorator that's
listed first in your code without as_format or accept_format is
the default that is chosen when no format is specifically asked for.
Any other expose calls that are missing as_format and accept_format
will have as_format implicitly set to the whatever comes before
the ":" in the template name (or the whole template name if there
is no ":". For example, <code>expose("json")</code>, if it's not
the default expose, will have as_format set to "json".

When as_format is set, passing the same value in the tg_format
parameter in a request will choose the options for that expose
decorator. Similarly, accept_format will watch for matching
Accept headers. You can also use both. expose("json", as_format="json",
accept_format="text/javascript") will choose JSON output for either
case: tg_format=json as a parameter or Accept: text/javascript as a
request header.

Passing allow_json=True to an expose decorator
is equivalent to adding the decorator just mentioned.

Each expose decorator has its own set of options, and each one
can choose a different template or even template engine (you can
use Kid for HTML output and Cheetah for plain text, for example).
See the other expose parameters below to learn about the options
you can pass to the template engine.

Take a look at the
<a href="tests/test_expose-source.html">test_expose.py</a> suite
for more examples.

@param template "templateengine:dotted.reference" reference along the
        Python path for the template and the template engine. For
        example, "kid:foo.bar" will have Kid render the bar template in
        the foo package.
@keyparam format format for the template engine to output (if the
        template engine can render different formats. Kid, for example,
        can render "html", "xml" or "xhtml")
@keyparam content_type sets the content-type http header
@keyparam allow_json allow the function to be exposed as json
@keyparam fragment for template engines (like Kid) that generate
        DOCTYPE declarations and the like, this is a signal to
        just generate the immediate template fragment. Use this
        if you're building up a page from multiple templates or
        going to put something onto a page with .innerHTML.
@keyparam mapping mapping with options that are sent to the template
        engine
@keyparam as_format designates which value of tg_format will choose
        this expose.
@keyparam accept_format which value of an Accept: header will
        choose this expose.
@keyparam html deprecated in favor of template
@keyparam validators deprecated. Maps argument names to validator
        applied to that arg
@keyparam inputform deprecated. A form object that generates the
        input to this method

Redirect (via cherrypy.HTTPRedirect). Raises the exception instead of returning it, this to allow users to both call it as a function or to raise it as an exception.