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:
- engine in query string;
- default engine.
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