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.
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.
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:
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.
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.
If SessionMiddleware is being used, session will also be available in the template namespace.
Cache and render a template
Cache a template to the namespace template_name, along with a specific key if provided.
Basic Options
Caching options (uses Beaker caching middleware)
The minimum key required to trigger caching is cache_expire='never' which will cache the template forever seconds with no key.
Render a template with Mako
Accepts the cache options cache_key, cache_type, and cache_expire.
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, and cache_expire.
Render a template with Genshi
Accepts the cache options cache_key, cache_type, and cache_expire in addition to method which are passed to Genshi’s render function.