Creare temi

Tutto ciò che scrivi in FolioPress — pagine, articoli, tag — vive separato da come viene mostrato. Quel livello di presentazione è un tema, e questa guida ne smonta uno: la cartella, i template, il file di impostazioni ed esattamente quali dati riceve ogni template. Se sei a tuo agio con HTML e CSS, hai tutto ciò che serve.

Un tema è una cartella

Cambia tema e le stesse pagine, gli stessi articoli e lo stesso menu vengono ridisegnati — nulla del contenuto cambia, solo il suo abito. Un tema è una cartella con tre cose dentro: un file di impostazioni, i template e le risorse statiche.

Quattro template sono obbligatori — base.html, home.html, page.html e post.html — e un tema che ne è privo non si carica. Tutto il resto è facoltativo: un archivio dei tag, una pagina di ricerca, pagine di errore personalizzate, un layout dedicato a una pagina specifica e una cartella locales/ per le parole del tema stesso. I temi si modificano direttamente nell’amministrazione, sotto Temi, si esportano in zip e si importano in un altro sito.

Da un URL a una pagina

Aiuta vedere cosa fa FolioPress con una richiesta prima ancora che il tuo template giri, perché spiega perché i template sono così brevi.

Due cose da notare. La lingua viene letta dal prefisso dell’URL, quindi /it-it/chi-siamo e /about sono la stessa pagina in due lingue, e il contesto consegnato al tuo template è già in quella giusta — ogni titolo, slug, voce di menu e contenuto. E il template viene scelto per te: per una pagina il cui slug nella lingua principale è about, FolioPress cerca prima page-about.html e ripiega su page.html. Non c’è nulla da collegare.

Una struttura, molte pagine

I template sono Jinja2 — HTML con due tipi di parentesi in più. {{ page.title }} stampa un valore. {% if page.poster_image_url %} … {% endif %} è un’istruzione: cicli, condizioni ed ereditarietà.

base.html contiene tutto ciò che ogni pagina condivide — l’<head>, la navigazione, il selettore della lingua, il piè di pagina, gli script — con un unico spazio vuoto al centro. Ogni altro template inizia allo stesso modo e riempie quello spazio:

{% extends "base.html" %}

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

Tutto ciò che si ripete tra i template — una scheda articolo, una barra di paginazione — va in partials/ e si include con {% include "partials/post-card.html" %}.

theme.yml: il pannello delle impostazioni

È qui che un tema si descrive e configura alcuni comportamenti, senza toccare un template. Ecco cosa usano i temi inclusi:

title: "Ink"
description: "Un tema pulito e minimale"
version: "1.0.0"
author: "FolioPress"

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

settings:                    # libero; disponibile nei template come theme_settings
  primary_color: "#2563eb"

home:
  posts: 10                  # quanti articoli riceve la pagina iniziale
  order_by: "-published_at"  # i più recenti prima
  has_pagination: false      # un taglio, o veri collegamenti di pagina?
  image_ratios:
    poster: "16:9"           # cosa offre qui lo strumento di ritaglio dell’amministrazione
    gallery: "free"

page:  { posts: 10, order_by: "-published_at", has_pagination: false }
post:  { posts: 3,  order_by: "-published_at" }   # articoli correlati sotto un articolo
tag:   { posts: 12, order_by: "-published_at", has_pagination: true }

page-about:                  # override per una pagina, tramite il suo slug nella lingua principale
  image_ratios: { poster: "1:1" }
post-tutorials:              # override per gli articoli il cui primo tag ha questo slug
  image_ratios: { poster: "4:3" }

Cosa vede ogni template

Un template non va mai a prendersi nulla. Riceve un insieme di valori pronti all’uso — FolioPress lo chiama il contesto — e stampa ciò che gli serve. Parte dell’insieme è uguale in ogni pagina; il resto dipende dal template che viene renderizzato.

Comune a tutti i template

L’oggetto page

La stessa forma, che sia una pagina, un articolo o una voce di qualsiasi elenco di articoli:

Elenchi di articoli

Ogni elenco di articoli arriva con una paginazione della stessa forma: has_pagination, current_page, total_pages, has_previous, has_next, previous_page, next_page e pagination_urls con first, previous, next e last — None dove non c’è dove andare. Con `has_pagination` disattivato in `theme.yml`, l’elenco viene semplicemente tagliato a `posts` e gli indicatori restano falsi.

Le lingue e il selettore

Due dei campi lingua vengono calcolati per te. short_code è il solo codice della lingua — EN — a meno che il sito abbia attiva anche un’altra variante della stessa lingua, nel qual caso mantiene la regione: EN-US ed EN-GB. menu_label segue la stessa regola con i nomi: English, oppure English (US) ed English (UK). È esattamente la regola usata dal selettore della lingua dell’amministrazione, così il sito e l’amministrazione non sono mai in disaccordo su un’etichetta. Un selettore completo è quindi breve:

{% 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 punta già alla stessa pagina in ogni lingua — lo slug tradotto, o la pagina iniziale se quella traduzione non esiste ancora —, quindi un selettore non costruisce mai un URL da solo.

Le parole del tema stesso

Il contenuto lo traduce l’autore nell’amministrazione. Le parole proprie di un tema — “Leggi tutto”, “Cerca”, “Tutti i diritti riservati” — le traduce il tema, in templates/locales/<lingua>.json:

{
  "Read more": "Leggi tutto",
  "Search": "Cerca",
  "Change language": "Cambia lingua"
}

Racchiudi la frase in {{ t('Read more') }} e apparirà nella lingua del visitatore. Una frase assente dal file di quella lingua ripiega sul file della lingua principale, poi sulla frase stessa — così un tema tradotto a metà funziona comunque, semplicemente in inglese dove la traduzione non è ancora stata scritta. I file viaggiano con il tema quando viene esportato.

Una pagina con il proprio layout

Una landing page, un modulo di contatto, una griglia portfolio — a volte una pagina merita un layout di cui nessun’altra ha bisogno. Aggiungi un template chiamato page-<slug>.html, dove <slug> è lo slug di quella pagina nella lingua principale, e FolioPress lo userà per quella pagina in ogni lingua. Cancella il file e la pagina torna silenziosamente a 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 %}

La pagina che un amministratore sceglie come pagina del modulo di contatto riceve un piccolo extra: is_contact_page è vero, contact_form_action è dove il modulo deve inviare, e contact_guard_token / contact_honeypot_field sono due campi nascosti che tengono fuori i bot. Dopo un invio, contact_status ti dice se mostrare un ringraziamento o un errore.

Parti da un tema che funziona

Il modo più rapido per costruire un tema è aprire uno di quelli inclusi — ognuno ha una demo dal vivo — e leggerlo accanto a questa pagina. Duplicalo nell’amministrazione, cambia il CSS, poi i template, e avrai qualcosa di tuo senza mai essere partito da un file vuoto.