Thema’s maken

Alles wat je in FolioPress schrijft — pagina’s, berichten, tags — staat los van hoe het wordt getoond. Die presentatielaag is een thema, en deze gids haalt er een uit elkaar: de map, de sjablonen, het instellingenbestand en precies welke gegevens elk sjabloon krijgt. Wie vertrouwd is met HTML en CSS heeft alles wat nodig is.

Een thema is een map

Wissel van thema en dezelfde pagina’s, berichten en hetzelfde menu worden opnieuw getekend — aan de inhoud verandert niets, alleen aan de kleding. Een thema is een map met drie dingen erin: een instellingenbestand, sjablonen en statische bestanden.

Vier sjablonen zijn verplicht — base.html, home.html, page.html en post.html —, een thema zonder deze laadt niet. Al het andere is optioneel: een tagarchief, een zoekpagina, eigen foutpagina’s, een eigen lay-out voor één specifieke pagina en een map locales/ voor de eigen teksten van het thema. Thema’s bewerk je rechtstreeks in het beheer onder Thema’s, exporteer je als zip en importeer je in een andere website.

Van een URL naar een pagina

Het helpt om te zien wat FolioPress met een verzoek doet voordat je sjabloon überhaupt draait, want het verklaart waarom sjablonen zo kort zijn.

Twee dingen vallen op. De taal wordt uit het URL-voorvoegsel gelezen, dus /nl-nl/over-ons en /about zijn dezelfde pagina in twee talen, en de context die je sjabloon krijgt, is al in de juiste taal — elke titel, slug, menu-item en inhoud. En het sjabloon wordt voor je gekozen: voor een pagina waarvan de slug in de hoofdtaal about is, zoekt FolioPress eerst page-about.html en valt terug op page.html. Er hoeft niets aangesloten te worden.

Eén casco, veel pagina’s

Sjablonen zijn Jinja2 — HTML met twee extra soorten accolades. {{ page.title }} drukt een waarde af. {% if page.poster_image_url %} … {% endif %} is een instructie: lussen, voorwaarden en overerving.

base.html bevat alles wat elke pagina deelt — de <head>, de navigatie, de taalkiezer, de voettekst, de scripts — met één gat in het midden. Elk ander sjabloon begint hetzelfde en vult dat gat:

{% extends "base.html" %}

{% block content %}
  <h1>{{ page.title }}</h1>
  {{ page.content | safe }}
{% endblock %}

Alles wat zich over sjablonen heen herhaalt — een berichtkaart, een paginering — hoort in partials/ en wordt ingevoegd met {% include "partials/post-card.html" %}.

theme.yml: het instellingenpaneel

Hier beschrijft een thema zichzelf en stelt het een paar gedragingen in, zonder een sjabloon aan te raken. Dit is wat de meegeleverde thema’s gebruiken:

title: "Ink"
description: "Een schoon, minimalistisch thema"
version: "1.0.0"
author: "FolioPress"

meta:
  supports_dark_mode: true
  responsive: true
  categories: [minimal, portfolio]

settings:                    # vrij in te vullen; in sjablonen beschikbaar als theme_settings
  primary_color: "#2563eb"

home:
  posts: 10                  # hoeveel berichten de startpagina krijgt
  order_by: "-published_at"  # nieuwste eerst
  has_pagination: false      # afkappen, of echte paginalinks?
  image_ratios:
    poster: "16:9"           # wat de bijsnijder in het beheer hier aanbiedt
    gallery: "free"

page:  { posts: 10, order_by: "-published_at", has_pagination: false }
post:  { posts: 3,  order_by: "-published_at" }   # gerelateerde berichten onder een bericht
tag:   { posts: 12, order_by: "-published_at", has_pagination: true }

page-about:                  # overschrijving voor één pagina, via haar slug in de hoofdtaal
  image_ratios: { poster: "1:1" }
post-tutorials:              # overschrijving voor berichten waarvan de eerste tag deze slug heeft
  image_ratios: { poster: "4:3" }

Wat elk sjabloon kan zien

Een sjabloon haalt nooit zelf iets op. Het krijgt een bundel kant-en-klare waarden — FolioPress noemt dat de context — en drukt af wat het nodig heeft. Een deel van de bundel is op elke pagina hetzelfde; de rest hangt af van welk sjabloon wordt gerenderd.

Gemeenschappelijk voor alle sjablonen

Het page-object

Dezelfde vorm, of het nu een pagina, een bericht of een item in een berichtenlijst is:

Berichtenlijsten

Elke berichtenlijst komt met een paginering van dezelfde vorm: has_pagination, current_page, total_pages, has_previous, has_next, previous_page, next_page en pagination_urls met first, previous, next en last — None waar er niets meer is. Staat `has_pagination` in `theme.yml` uit, dan wordt de lijst gewoon afgekapt op `posts` en blijven de vlaggen onwaar.

Talen en de kiezer

Twee van de taalvelden worden voor je berekend. short_code is alleen de taalcode — EN — tenzij de website ook een andere variant van dezelfde taal heeft ingeschakeld; dan behoudt hij zijn regio: EN-US en EN-GB. menu_label volgt dezelfde regel met namen: English, of English (US) en English (UK). Dat is precies de regel van de taalkiezer in het beheer, zodat website en beheer het nooit oneens zijn over een label. Een volledige kiezer is daarom kort:

{% if languages | length > 1 %}
<button type="button" aria-label="{{ t('Change language') }}">
  {{ current_language.short_code }}
</button>
<ul>
  {% for lang in languages.values() | sort(attribute='menu_label') %}
  <li>
    {% if lang.code == current_language.code %}
      <span aria-current="true">{{ lang.menu_label }}</span>
    {% else %}
      <a href="{{ language_switch_urls[lang.code] }}" hreflang="{{ lang.code }}">{{ lang.menu_label }}</a>
    {% endif %}
  </li>
  {% endfor %}
</ul>
{% endif %}

language_switch_urls wijst al naar dezelfde pagina in elke taal — de vertaalde slug, of de startpagina als die vertaling nog niet bestaat —, dus een kiezer bouwt nooit zelf een URL.

De eigen teksten van het thema

Inhoud vertaalt de auteur in het beheer. De eigen teksten van een thema — “Lees verder”, “Zoeken”, “Alle rechten voorbehouden” — vertaalt het thema, in templates/locales/<taal>.json:

{
  "Read more": "Lees verder",
  "Search": "Zoeken",
  "Change language": "Taal wijzigen"
}

Omsluit de zin met {{ t('Read more') }} en hij verschijnt in de taal van de bezoeker. Ontbreekt een zin in het bestand van die taal, dan valt hij terug op het bestand van de hoofdtaal, en daarna op de zin zelf — een half vertaald thema blijft dus werken, alleen in het Engels waar de vertaling nog niet is geschreven. De bestanden reizen mee met het thema bij het exporteren.

Een pagina met een eigen lay-out

Een landingspagina, een contactformulier, een portfoliorooster — soms verdient één pagina een lay-out die geen andere nodig heeft. Voeg een sjabloon toe met de naam page-<slug>.html, waarbij <slug> de slug van die pagina in de hoofdtaal is, en FolioPress gebruikt het voor die pagina in elke taal. Verwijder het bestand en de pagina keert stilletjes terug naar page.html.

{# templates/page-about.html #}
{% extends "base.html" %}
{% block content %}
<section class="about">
  <img src="{{ page.poster_image_url }}" alt="">
  <h1>{{ page.title }}</h1>
  {{ page.content | safe }}
</section>
{% endblock %}

De pagina die een beheerder als contactformulierpagina kiest, krijgt iets extra’s: is_contact_page is waar, contact_form_action is waar het formulier naartoe moet, en contact_guard_token / contact_honeypot_field zijn twee verborgen velden die bots buiten houden. Na een inzending zegt contact_status of je een bedankje of een fout moet tonen.

Begin met een thema dat werkt

De snelste manier om een thema te bouwen is een van de meegeleverde te openen — elk heeft een live demo — en het naast deze pagina te lezen. Dupliceer het in het beheer, pas de CSS aan, dan de sjablonen, en je hebt iets eigens zonder ooit met een leeg bestand te zijn begonnen.