Sjablonen

Finch gebruikt het Jinja-Dart-package als sjabloonengine. Sjablonen bevinden zich in de map die is geconfigureerd via FinchConfigs.widgetsPath en gebruiken de extensie die is ingesteld in FinchConfigs.widgetsType (standaard: j2.html).

Een sjabloon renderen

Roep rq.renderView(path: '...') aan met het pad relatief ten opzichte van widgetsPath, zonder de bestandsextensie:

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

Geef data door aan het sjabloon met rq.addParam() of rq.addParams() vóórdat je renderView aanroept:

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

Sjabloonsyntaxis

Finch gebruikt standaard Jinja2-syntaxis. De scheidingstekens zijn configureerbaar in FinchConfigs, maar zijn standaard:

Syntaxis	Doel
`{{ expression }}`	Geeft een variabele of expressie weer
`{% tag %}`	Controlestructuren: `if`, `for`, `block`, `include`, enz.
`{# comment #}`	Commentaar (wordt niet gerenderd)

Variabelen

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

Controlestructuren

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

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

Insluiten

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

Uitbreiden / blokken

{# 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 %}

Gebruik van gebundelde (Map) sjablonen

Voor gecompileerde binaries kunnen sjablonen tijdens runtime niet van schijf worden gelezen. Gebruik jinjaMapTemplate in FinchConfigs om sjablonen te bundelen als een Map<String, String>:

// Gegenereerd door: finch build of finch runner
final mapTemplates = {
  'pages/home.j2.html': '<h1>{{ title }}</h1>',
  // ...
};

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

De finch serve-watcher genereert deze map automatisch opnieuw wanneer sjabloonbestanden wijzigen.

Aangepaste sjabloonfuncties (localEvents)

Voeg globale functies toe die vanuit elk sjabloon aanroepbaar zijn:

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

In het sjabloon (gebruik de $l.-prefix voor lokale events):

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

Aangepaste filters (localLayoutFilters)

Voeg Jinja-filters toe:

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

In het sjabloon:

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

Ingebouwde Finch-sjabloonvariabelen

Deze zijn automatisch beschikbaar in elk sjabloon:

{{ isLocalDebug }}        — true in ontwikkelmodus
{{ data }}                — alle addParam()-data
{{ session }}             — huidige sessie-map
{{ $rq }}                 — het Request-object

Zie Template Events voor de volledige lijst met $e.*- en $t()-hulpmiddelen.

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>

Op deze pagina