pylons.templating
– Render functions and helpers¶
Render functions and helpers
Render functions and helpers¶
pylons.templating
includes several basic render functions,
render_mako()
, render_genshi()
and render_jinja2()
that render templates from the file-system with the assumption that
variables intended for the will be attached to tmpl_context
(hereafter referred to by its short name of c
which it is
commonly imported as).
The default render functions work with the template language loader
object that is setup on the app_globals
object in the project’s
config/environment.py
.
Usage¶
Generally, one of the render functions will be imported in the
controller. Variables intended for the template are attached to the
c
object. The render functions return unicode (they actually
return literal
objects, a subclass of
unicode).
Tip
tmpl_context
(template context) is abbreviated to c
instead of its full name since it will likely be used extensively
and it’s much faster to use c
. Of course, for users that
can’t tolerate one-letter variables, feel free to not import
tmpl_context
as c
since both names are available in
templates as well.
Example of rendering a template with some variables:
from pylons import tmpl_context as c
from pylons.templating import render_mako as render
from sampleproject.lib.base import BaseController
class SampleController(BaseController):
def index(self):
c.first_name = "Joe"
c.last_name = "Smith"
return render('/some/template.mako')
And the accompanying Mako template:
Hello ${c.first name}, I see your lastname is ${c.last_name}!
Your controller will have additional default imports for commonly used functions.
Template Globals¶
Templates rendered in Pylons should include the default Pylons globals
as the render_mako()
, render_genshi()
and
render_jinja2()
functions. The full list of Pylons globals that
are included in the template’s namespace are:
- c – Template context object
- tmpl_context – Template context object
config
– PylonsPylonsConfig
object (acts as a dict)- app_globals – Project application globals object
- h – Project helpers module reference
request
– PylonsRequest
object for this requestresponse
– PylonsResponse
object for this requestsession
– Pylons session object (unless Sessions are removed)url
– Routes url generator objecttranslator
– Gettext translator object configured for current localeungettext()
– Unicode capable version of gettext’s ngettext function (handles plural translations)_()
– Unicode capable gettext translate functionN_()
– gettext no-op function to mark a string for translation, but doesn’t actually translate
Configuring the template language¶
The template engine is created in the projects
config/environment.py
and attached to the app_globals
(g)
instance. Configuration options can be directly passed into the
template engine, and are used by the render functions.
Warning
Don’t change the variable name on app_globals
that the
template loader is attached to if you want to use the render_*
functions that pylons.templating
comes with. The render_*
functions look for the template loader to render the template.
Module Contents¶
-
pylons.templating.
pylons_globals
()¶ Create and return a dictionary of global Pylons variables
Render functions should call this to retrieve a list of global Pylons variables that should be included in the global template namespace if possible.
- Pylons variables that are returned in the dictionary:
c
,h
,_
,N_
, config, request, response, translator, ungettext,url
If SessionMiddleware is being used,
session
will also be available in the template namespace.
-
pylons.templating.
cached_template
(template_name, render_func, ns_options=(), cache_key=None, cache_type=None, cache_expire=None, **kwargs)¶ Cache and render a template
Cache a template to the namespace
template_name
, along with a specific key if provided.Basic Options
template_name
- Name of the template, which is used as the template namespace.
render_func
- Function used to generate the template should it no longer be valid or doesn’t exist in the cache.
ns_options
- Tuple of strings, that should correspond to keys likely to be
in the
kwargs
that should be used to construct the namespace used for the cache. For example, if the template language supports the ‘fragment’ option, the namespace should include it so that the cached copy for a template is not the same as the fragment version of it.
Caching options (uses Beaker caching middleware)
cache_key
- Key to cache this copy of the template under.
cache_type
- Valid options are
dbm
,file
,memory
,database
, ormemcached
. cache_expire
- Time in seconds to cache this template with this
cache_key
for. Or use ‘never’ to designate that the cache should never expire.
The minimum key required to trigger caching is
cache_expire='never'
which will cache the template forever seconds with no key.
-
pylons.templating.
render_mako
(template_name, extra_vars=None, cache_key=None, cache_type=None, cache_expire=None)¶ Render a template with Mako
Accepts the cache options
cache_key
,cache_type
, andcache_expire
.
-
pylons.templating.
render_mako_def
(template_name, def_name, cache_key=None, cache_type=None, cache_expire=None, **kwargs)¶ Render a def block within a Mako template
Takes the template name, and the name of the def within it to call. If the def takes arguments, they should be passed in as keyword arguments.
Example:
# To call the def 'header' within the 'layout.mako' template # with a title argument render_mako_def('layout.mako', 'header', title='Testing')
Also accepts the cache options
cache_key
,cache_type
, andcache_expire
.
-
pylons.templating.
render_genshi
(template_name, extra_vars=None, cache_key=None, cache_type=None, cache_expire=None, method='xhtml')¶ Render a template with Genshi
Accepts the cache options
cache_key
,cache_type
, andcache_expire
in addition to method which are passed to Genshi’s render function.