Targeting template engines

diecutter supports several template engines. This section explains how diecutter chooses the engine for a given template.

As a summary, diecutter follows the scenario below:

Notice that diecutter sets a diecutter-engine header in responses.

Note

In the examples below, let’s communicate with a diecutter server using Python requests.

This diecutter serves diecutter’s demo templates.

The diecutter_url variable holds root URL of diecutter service, i.e. something like http://diecutter.io/api/.

In query string

If the HTTP request has a known engine in query string, then diecutter uses it to render the template. Here is an example using jinja2:

>>> greetings_url = diecutter_url + 'greetings.txt?engine=jinja2'
>>> response = requests.post(greetings_url, {'name': 'world'})
>>> print response.text
Hello world!
>>> print response.headers['Diecutter-Engine']
jinja2

Here is an example using django:

>>> greetings_url = diecutter_url + 'greetings-django.txt?engine=django'
>>> response = requests.post(greetings_url, {'name': 'world'})
>>> print response.text
Hello world!

>>> print response.headers['Diecutter-Engine']
django

If you try to use an unknown template engine, then you get a 406:

>>> greetings_url = diecutter_url + 'greetings.txt?engine=unknown'
>>> response = requests.post(greetings_url, {'name': 'world'})
>>> response.status_code
406

Default engine

In case no specific engine was resolved for the current request, diecutter fallbacks to default engines. Default engines are setup in configuration:

  • diecutter.engine is the default engine used to render files;
  • diecutter.filename_engine is the default engine used to render filenames.

The configuration itself defaults to jinja2.

>>> greetings_url = diecutter_url + 'greetings.txt'
>>> response = requests.post(greetings_url, {'name': 'world'})
>>> print response.text
Hello world!
>>> print response.headers['Diecutter-Engine']
jinja2

diecutter-engine header in responses

diecutter sets the value of used engine as Diecutter-Engine header.

>>> greetings_url = diecutter_url + 'greetings.txt'
>>> response = requests.post(greetings_url, {'name': 'world'})
>>> print response.headers['Diecutter-Engine']
jinja2

Supported engines

Ask the diecutter server API index to get the list of engines:

>>> response = requests.get(diecutter_url)
>>> response.json()['engines']
[u'django', u'filename', u'jinja2']

Unsupported engines

diecutter returns a HTTP 406 error code in case an unsupported template engine was asked:

>>> greetings_url = diecutter_url + 'greetings.txt?engine=unknown'
>>> response = requests.post(greetings_url, {'name': 'world'})
>>> response.status_code
406