Templates

Finch uses the Jinja Dart package as its template engine. Templates live in the directory configured by FinchConfigs.widgetsPath and use the extension set in FinchConfigs.widgetsType (default: j2.html).

Rendering a Template

Call rq.renderView(path: '...') with the path relative to widgetsPath, without the file extension:

// Loads: widgetsPath/pages/home.j2.html
return rq.renderView(path: 'pages/home');

Pass data to the template using rq.addParam() or rq.addParams() before calling renderView:

rq.addParams({
  'title': 'My Page',
  'user': user.toJson(),
  'items': items.map((i) => i.toJson()).toList(),
});
return rq.renderView(path: 'pages/home');

Template Syntax

Finch uses standard Jinja2 syntax. The delimiters are configurable in FinchConfigs but default to:

Syntax	Purpose
`{{ expression }}`	Output a variable or expression
`{% tag %}`	Control flow: `if`, `for`, `block`, `include`, etc.
`{# comment #}`	Comment (not rendered)

Variables

{{ title }}
{{ user.name }}
{{ user['email'] }}

Control flow

{% if user %}
  <p>Hello, {{ user.name }}</p>
{% else %}
  <p>Please log in.</p>
{% endif %}

{% for item in items %}
  <li>{{ item.title }}</li>
{% endfor %}

Include

{% include 'partials/header.j2.html' %}

Extends / blocks

{# layout.j2.html #}
<!DOCTYPE html>
<html>
<head><title>{% block title %}{% endblock %}</title></head>
<body>
  {% block content %}{% endblock %}
</body>
</html>

{# pages/home.j2.html #}
{% extends 'layout.j2.html' %}

{% block title %}Home{% endblock %}

{% block content %}
  <h1>{{ title }}</h1>
{% endblock %}

Using Bundled (Map) Templates

For compiled binaries, templates cannot be read from disk at runtime. Use jinjaMapTemplate in FinchConfigs to bundle templates as a Map<String, String>:

// Generated by: finch build or finch runner
final mapTemplates = {
  'pages/home.j2.html': '<h1>{{ title }}</h1>',
  // ...
};

FinchConfigs configs = FinchConfigs(
  jinjaMapTemplate: mapTemplates,
  widgetsType: 'j2.html',
);

The finch serve watcher automatically regenerates this map when template files change.

Custom Template Functions (localEvents)

Add global functions callable from any template:

// In app.dart
Request.localEvents.addAll({
  'currentYear': () => DateTime.now().year,
  'formatDate': (String iso) => iso.substring(0, 10),
});

In the template (use $l. prefix for local events):

<footer>© {{ $l.currentYear() }}</footer>
<span>{{ $l.formatDate(post.createdAt) }}</span>

Custom Filters (localLayoutFilters)

Add Jinja filters:

Request.addLocalLayoutFilters({
  'upper': (value) => value.toString().toUpperCase(),
  'excerpt': (value) {
    var s = value.toString();
    return s.length > 100 ? '${s.substring(0, 100)}…' : s;
  },
});

In the template:

{{ post.title | upper }}
{{ post.body | excerpt }}

Built-in Finch Template Variables

These are available in every template automatically:

{{ isLocalDebug }}        — true in development mode
{{ data }}                — all addParam() data
{{ session }}             — current session map
{{ $rq }}                 — the Request object

See Template Events for the full list of $e.* and $t() helpers.

Complete Example

<!DOCTYPE html>
<html lang="{{ $e.ln }}" dir="{{ $t('dir') }}">
<head>
  <meta charset="UTF-8">
  <title>{{ $t(title) }}</title>
  {{ assets.css() }}
</head>
<body>
  <nav>
    {% if user %}
      <a href="/logout">{{ user.name }}</a>
    {% else %}
      <a href="/login">Login</a>
    {% endif %}
  </nav>

  <main>
    {% block content %}{% endblock %}
  </main>

  {{ assets.js() }}
</body>
</html>

On This Page