expose(template=None,
allow_json=None,
format=None,
content_type=None,
fragment=False,
as_format=' default ' ,
accept_format=None,
**options)
| source code
|
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="application/json") will choose JSON output for either
case: tg_format=json as a parameter or Accept: application/json 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 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.
All additional keyword arguments are passed as keyword args to the render
method of the template engine.
|