Templates in Appier are rendered using Jinja2. Learning its syntax is not the purpose of this guide and is best learned from its website.
Here's how to render a template and return it as a response:
import appier
class CatController(appier.Controller):
@appier.route("/cats", "GET")
def list(self):
return self.template(
"cat/list.html.tpl"
)
The list
handler in this example would render the template in
templates/cats/list.html.tpl
(read the Structure
documentation for more details on how the app file structure works).
To improve the example, we would need to retrieve the cats and use
them in the template:
cats = models.Cat.find()
return self.template(
"cat/list.html.tpl",
cats = cats
)
Any keyword arguments passed to the template
method become available in the template:
<table>
{% for cat in cats %}
<tr>
<td>{{ cat.name }}</td>
</tr>
{% endfor %}
</table>
At the moment, the only detail specific to Appier that is worth noticing is how to resolve
URLs for handlers specified in controllers. Here's how you would render a link to the
list
handler in CatController
:
<a href="{{ url_for('cat.list') }}">List Cats</a>
The url_for
method will resolve a path relative to the host. In order to resolve an absolute path
(links sent out in emails must be absolute URLs for example) do the following:
<a href="{{ url_for('cat.list', absolute = True) }}">List Cats</a>
The absolute
named argument will make the resolved URL prefixed with the value specified
in the BASE_URL
configuration setting. To learn more, read the Configuration
documentation.
Here's how to access static resources in the app:
<img src="{{ url_for('static', filename = 'images/cats/felix.png') }}" />
The previous example will output a link to static/images/cats/felix.png
from
the root of your app location. All static resources like CSS, Javascript, Images,
and others, should be stored inside the static
directory (read the Structure
documentation for more details on how the app file structure works).
In case you want the resource to be compressed to lessen bandwidth usage, you can pass the compress
flag.
<img src="{{ url_for('static', filename = 'images/cats/felix.png', compress = True) }}" />
In this example, the flag will have a behaviour appropriate to the specified resource. In this case, it would return a JPEG instead of a PNG (the JPEG would be created on-the-fly and cached, so future requests won't trigger compression again).
It's also possible to retrieve the current location (both relative and absolute) using the
location
value for the URL resolution.
<a href="{{ url_for('location', absolute = True) }}">Loop Link</a>
This example returns the absolute URL for the current location in handling by Appier.
A series of variables are injected into the template for easy reference. For example, if you wanted to print the email of the currently logged-in user (provided is the email is set in the session object), you could do the following:
<p>Logged in as {{ session.email }}</p>
Here is the of variables that are always accessible in a template:
appier
- the reference to the (top-level) appier moduleowner
- the owner (typically an App object) that "controls" the template executionown
- the controller where the template was renderedrequest
- the request whose handler rendered the templatesession
- the session object for the userlocation
- the relative path for the URL whose handling resulted in the rendering of the templatelocation_f
- the equivalent to thelocation
variable but including the query part of the locationconfig
- the reference to the config module to access the app configuration
The template can be processed in such a way, as to show different content depending on whether a user is logged in or not, and what access rights that user has. To learn more, read the Access Control documentation.
To support multiple languages, specify the locale before the extension of each template.
For example, if you had an index template named index.html.tpl
, and wanted to add support
for English and Portuguese, you should have the following two files instead: index.pt_pt.html.tpl
and index.en_us.html.tpl
.