Templates¶

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 becomes 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 be 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.

Reserved variables¶

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 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 module
• owner - the owner (typically an App object) that "controls" the template execution
• own - the controller where the template was rendered
• request - the request whose handler rendered the template
• session - the session object for the user
• location - the relative path for the URL whose handling resulted in the rendering of the template
• location_f - the equivalent to the location variable but including the query part of the location
• config - the reference to the config module to access the the app configuration

Access control¶

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.

Internationalization (i18n)¶

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.