### Navigation

- index
- modules |
- next |
- previous |
- TurboGears 2.1.5 documentation »
- Search:
- Extended Table of Contents »
- The Gears in Detail »
- Modules »

# `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` – Pylons `PylonsConfig` object (acts as a dict)
- app_globals – Project application globals object
- h – Project helpers module reference
- `request` – Pylons `Request` object for this request
- `response` – Pylons `Response` object for this request
- `session` – Pylons session object (unless Sessions are removed)
- `url` – Routes url generator object
- `translator` – Gettext translator object configured for current locale
- `ungettext()` – Unicode capable version of gettext’s ngettext function (handles plural translations)
- `_()` – Unicode capable gettext translate function
- `N_()` – 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 a Bunch of variables that should be available in all templates.

  These variables are:

  WARNING: This function should not be called from outside of the render() code. Please consider this function as private.

  quote_plus
    the urllib quote_plus function
  url
    the turbogears.url function for creating flexible URLs
  identity
    the current visitor’s identity information
  session
    the current beaker.session if the session_filter.on it set in the app.cfg configuration file. If it is not set then session will be None.
  locale
    the default locale
  inputs
    input values from a form
  errors
    validation errors
  request
    the WebOb Request Object
  config
    the app’s config object
  auth_stack_enabled
    A boolean that determines if the auth stack is present in the environment
  predicates
    The `repoze.what.predicates` module.

`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`, or `memcached`.
  `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`, and `cache_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`, and `cache_expire` in addition to method which are passed to Genshi’s render function.

app_globals
  One instance of Globals is created during application initialization and is available during requests via the ‘app_globals’ variable. Useful for any given object which should be shared across the application.
c
  The template context object, available when a template is being processed. `c` is an alias for `tmpl_context`
g
  The application globals object. `g` is an alias for `app_globals`
h
  A reference to the project helpers module.
tmpl_context
  The template context object, a place to store all the data for use in a template. This includes form data, user identity, and the like.