| ===================== |
| Framework Integration |
| ===================== |
| |
| Starting with Jinja 1.1 it's possible to embed Jinja into some of the existing |
| frameworks a lot easier. When speaking of frameworks we only refer to `Pylons`_ |
| which has a working implementation of the TurboGears template specification. |
| |
| Since the whole situation is problematic because of various reasons (kid |
| specific, uses dotted names for template loading, package name prefix etc.) |
| we worked around some of the problems by using pylons specific workarounds. |
| |
| Jinja also ships an implementation for a hypothetical template abstraction layer |
| called `General Template Interface`_ which isn't implemented by any existing |
| framework so far. This specification however tries to solve the problems that |
| exist in Buffet. |
| |
| |
| Buffet |
| ====== |
| |
| The buffet specification proposes that templates are named in dotted names. That |
| means `foo.bar` and not `foo/bar.html`. The dotted notation has the disadvantage |
| that you cannot specify the filename extension. In recent pylons versions it's |
| however possible to load templates with their native path too if you prefix the |
| template name with a foreslash (`/foo/bar.html`). If you don't specify the |
| extension it will assume `.html` for the dotted notation. |
| |
| Here the list of configuration values: |
| |
| ======================= ====================================================== |
| ``jinja.extension`` The template extension when templates are loaded using |
| the dotted notation. Defaults to ``html``. |
| ``jinja.environment`` If this is provided it must be the only configuration |
| value and it's used as jinja environment. In that |
| case all other configuration parameters except of |
| ``jinja.extension`` are ignored. |
| ``jinja.searchpath`` If provided a new file system loader with this |
| search path is instanciated. |
| ``jinja.package`` Name of the python package containing the |
| templates. If this and ``package_path`` is |
| defined a `PackageLoader` is used. |
| ``jinja.package_path`` Path to the templates inside of a package. |
| ``jinja.loader_func`` Function that takes the name of the template to |
| load. If it returns a string or unicode object |
| it's used to load a template. If the return |
| value is None it's considered missing. |
| ``jinja.getmtime_func`` Function used to check if templates requires |
| reloading. Has to return the UNIX timestamp of |
| the last template change or 0 if this template |
| does not exist or requires updates at any cost. |
| ``jinja.use_memcache`` Set this to ``True`` to enable memory caching. |
| This is usually a good idea in production mode, |
| but disable it during development since it won't |
| reload template changes automatically. |
| This only works in persistent environments like |
| FastCGI. |
| ``jinja.memcache_size`` Number of template instance you want to cache. |
| Defaults to ``40``. |
| ``jinja.cache_folder`` Set this to an existing directory to enable |
| caching of templates on the file system. Note |
| that this only affects templates transformed |
| into python code. Default is ``None`` which means |
| that caching is disabled. |
| ``jinja.auto_reload`` Set this to `False` for a slightly better |
| performance. In that case of `getmtime_func` |
| not being provided this won't have an effect. |
| ======================= ====================================================== |
| |
| All other options that start with `jinja.` are automatically forwarded to the |
| environment constructor. |
| |
| In pylons for example you can use jinja as buffet plugin like this: |
| |
| Edit the `yourproject/config/middleware.py` and add this to `config.init_app`: |
| |
| .. sourcecode:: python |
| |
| config.add_template_engine('jinja', '', { |
| 'jinja.package': 'yourapplication', |
| 'jinja.package_path': 'res/templates', |
| 'jinja.use_memcache': True |
| }) |
| |
| Note that it's a good idea to set the second parameter to an empty string. |
| It's meant to be used as replacement for the turbogears package name but |
| Jinja assumes that the name of the template does not include the package |
| path. |
| |
| .. admonition:: Note |
| |
| Special note for pylons users. Jinja will be unable to request attributes |
| from the special `c` object, unless you set `strict_c` to `True` in the |
| `environment.py`: |
| |
| .. sourcecode:: python |
| |
| return pylons.config.Config(tmpl_options, map, paths, strict_c=True) |
| |
| You can then render the template in the view like this: |
| |
| .. sourcecode:: python |
| |
| class ExampleController(BaseController): |
| |
| def index(self): |
| c.title = "Your Page" |
| c.message = 'hi' |
| return render_response('jinja', 'test_template') |
| |
| def download(self): |
| c.title = "Downloads" |
| c.downloads = [1, 2, 3] |
| return render_response('jinja', '/downloads.html') |
| |
| With the settings from above rendering the `index` action will result in |
| rendering the template ``res/templates/test_template.html`` where res is |
| a folder in the ``yourapplication`` python package. |
| |
| The `downloads` action uses the pylons specific leading foreslash notation. |
| |
| |
| General Template Interface |
| ========================== |
| |
| Because nobody implemented this specification so far it's not documented here |
| but in the sourcecode of the `plugin module`_. The specification itself is |
| explained on the pocoo trac on the `General Template Interface`_ wiki page. |
| |
| |
| Django |
| ====== |
| |
| Using Jinja in django is straightforward because django has a pretty low |
| level response interface. Just have a look at the `developer recipies`_, |
| there are some examples for django. Starting with Jinja 1.2 there is also |
| a contrib module that simplifies using Jinja in an unicode enabled django. |
| |
| Quickstart |
| ---------- |
| |
| To get started execute the following code at the bottom of your settings.py |
| or in some general application file such as urls.py or a central module. The |
| only thing that matters is that it's executed right *after* the settings |
| were set up and *before* `django.contrib.jinja` is imported:: |
| |
| from jinja.contrib import djangosupport |
| djangosupport.configure() |
| |
| What this does is setting up a Jinja environment for this django instance |
| with loaders for `TEMPLATE_DIRS` etc. It also converts a couple of default |
| django filters such as `date` and `timesince` which are not available in |
| Jinja per default. If you want to change the list you can provide others |
| by passing a list with filter import names as `convert_filters` keyword |
| argument. |
| |
| All other keyword arguments are forwarded to the environment. If you want |
| to provide a loader yourself pass it a loader keyword argument. |
| |
| Rendering Templates |
| ------------------- |
| |
| To render a template you can use the functions `render_to_string` or |
| `render_to_response` from the `django.contrib.jinja` module:: |
| |
| from django.contrib.jinja import render_to_response |
| resp = render_to_response('Hello {{ username }}!', { |
| 'username': req.session['username'] |
| }, req) |
| |
| `render_to_string` and `render_to_response` take at least the name of |
| the template as argument, then the optional dict which will become the |
| context. If you also provide a request object as third argument the |
| context processors will be applied. |
| |
| `render_to_response` also takes a forth parameter which can be the |
| content type which defaults to `DEFAULT_CONTENT_TYPE`. |
| |
| Converting Filters |
| ------------------ |
| |
| One of the useful objects provided by `django.contrib.jinja` is the |
| `register` object which can be used to register filters, tests and |
| global objects. You can also convert any filter django provides in |
| a Jinja filter using `convert_django_filter`:: |
| |
| from django.contrib.jinja import register, convert_django_filter |
| from django.template.defaultfilters import floatformat |
| |
| register.filter(convert_django_filter(floatformat), 'floatformat') |
| |
| Available methods on the `register` object: |
| |
| ``object (obj[, name])`` |
| Register a new global as name or with the object's name. |
| Returns the function object unchanged so that you can use |
| it as decorator if no name is provided. |
| |
| ``filter (func[, name])`` |
| Register a function as filter with the name provided or |
| the object's name as filtername. |
| Returns the function object unchanged so that you can use |
| it as decorator if no name is provided. |
| |
| ``test (func[, name])`` |
| Register a function as test with the name provided or the |
| object's name as testname. |
| Returns the function object unchanged so that you can use |
| it as decorator if no name is provided. |
| |
| ``context_inclusion (func, template[, name])`` |
| Register a function with a name provided or the func object's |
| name in the global namespace that acts as subrender function. |
| |
| func is called with the callers context as dict and the |
| arguments and keywords argument of the inclusion function. |
| The function should then process the context and return a |
| new context or the same context object. Afterwards the |
| template is rendered with this context. |
| |
| Example:: |
| |
| def add_author(context, author=None): |
| if author is not None: |
| author = Author.objects.get(name=author) |
| context['author'] = author |
| return context |
| |
| register.context_inclusion(add_author, 'author_details.html', |
| 'render_author_details') |
| |
| You can use it in the template like this then:: |
| |
| {{ render_author_details('John Doe') }} |
| |
| ``clean_inclusion (func, template[, name[, run_processors]])`` |
| Works like `context_inclusion` but doesn't use the calles |
| context but an empty context. If `run_processors` is `True` |
| it will lookup the context for a `request` object and pass |
| it to the render function to apply context processors. |
| |
| |
| |
| .. _Pylons: http://www.pylonshq.com/ |
| .. _General Template Interface: http://trac.pocoo.org/wiki/GeneralTemplateInterface |
| .. _plugin module: http://trac.pocoo.org/browser/jinja/trunk/jinja/plugin.py |
| .. _developer recipies: devrecipies.txt |