Modèles

Lorsqu’un blog reçoit une requête, nous faisons d’abord correspondre son chemin à une route (supposons la route post pour /hello-world). Ensuite, nous récupérons les données nécessaires depuis notre base de données, puis nous appelons le fichier de modèle Twig défini dans cette route (post.twig).

À l’intérieur de ce fichier, vous pouvez inclure d’autres fichiers ou même utiliser l’héritage. Vous pouvez même appeler notre API de données pour récupérer plus de données (plus d’informations ci-dessous) !

Twig

Nous utilisons Twig 3.0 pour le templating. C’est un langage puissant avec de nombreuses balises, filtres et fonctions intégrés. Twig dispose également d’une documentation agréable et facile à suivre, ce qui est l’une des raisons pour lesquelles nous avons choisi Twig plutôt que d’autres langages de modèles. Si vous ne l’avez jamais utilisé, parcourez la page Twig pour les concepteurs de modèles, et vous aurez une idée de son fonctionnement. En gros, c’est du HTML avec des super-pouvoirs.

Modèles

Ce dossier contient les fichiers de modèles. Il existe plusieurs types de fichiers de modèles

Variables de thème

• Le développeur de thème (vous) crée le thème
• Le blogueur crée le contenu (données)
• HB combine le thème et les données et génère le blog

Lors du rendu des modèles twig, nous envoyons les données dans votre fichier de modèle sous forme d’objets. Vous utiliserez ces données pour générer une belle interface utilisateur.

Il y a 4 objets principaux dans HB : Blog, Post, Tag, et Author. Ces objets sont expliqués dans la page API de données.

Chaque route obtient des variables différentes. Nous préfixons chaque variable avec _ afin qu’elle n’entre pas en conflit avec les variables que vous définissez dans les fichiers de thème (évidemment, vous ne devriez pas préfixer vos variables avec _ dans le modèle Twig)

Espaces réservés

Vous devez placer certains espaces réservés dans votre thème pour faire fonctionner certaines choses.

Il est absolument nécessaire d’envoyer tous les espaces réservés (sauf _lang) à travers le filtre template pour qu’ils soient rendus comme des modèles.

{{ _head | template }}

Assistants Twig

Nous fournissons quelques fonctions et filtres Twig personnalisés pour faciliter l’écriture des modèles.

Fonctions

• data - une fonction pour appeler l’API de données. Voir Récupération de données ci-dessous.

{% set posts = data(endpoint="posts", filter="author.slug=user") %}

• icon - une fonction pour obtenir une icône.

{{ icon('bootstrap', 'arrow-down', 20, 20) }}

Définition de la fonction : icon(iconLibrary, iconName, width, height)

• Tous les noms d’icônes sont en minuscules, et les mots sont séparés par - (arrow-down).
• Ces bibliothèques d’icônes sont prises en charge

• bootstrap
• fontawesomeIcônes gratuites uniquement
• ajouter -regular aux icônes normales (calendar-regular)
• ajouter -solid aux icônes pleines (calendar-solid)
• Ne rien ajouter pour les icônes de marque (github)
• ionicons
• heroicons
• ajouter -solid aux icônes pleines (archive-solid)
• ajouter -outline aux icônes en contour (archive-outline)
• octicons
• css.gg

En interne, nous utilisons la bibliothèque open-source php-svg-icons. Si vous avez besoin d'ajouter d'autres bibliothèques d'icônes, veuillez y envoyer une PR.

Filtres

• asset_url - un filtre pour lier des ressources
• Transforme un nom de fichier de ressource en son URL absolue.
• Ajoute l'horodatage de dernière mise à jour comme paramètre de requête (pour contourner le cache du navigateur lors des mises à jour)

{{ 'script.js' | asset_url }}

<script src="{{ 'script.js' | asset_url }}"></script>

// se transforme en :

<script src="https://subdomain.hyvorblogs.io/assets/script.js?v=12931923993"></script>

• asset - un filtre pour imprimer directement des ressources (uniquement pour les ressources textuelles comme les SVG)

{{ 'beauty.svg' | asset }}

• pagination_page_url - un filtre pour convertir un numéro de page en URL complète

<a href="{{ _pagination.page_prev | pagination_page_url }}">Page précédente</a>

• lang - un filtre pour les traductions. Apprenez-en plus dans internationalisation.
• lang_by_number - Voir chaînes conditionnelles basées sur un nombre.
• language_variant_url - Voir sélecteur de langue
• toc - un filtre pour générer une table des matières à partir d'une chaîne HTML.

  {{ _post.content | toc }}

  Par défaut, tous les titres sont inclus dans la table des matières. Vous pouvez définir les niveaux à inclure comme suit :

  {{ _post.content | toc('2,3') }}

Récupération de données

Utilisez la fonction data pour récupérer des données depuis notre API de données.

<!-- Récupérer les données -->
{% set recent_posts = data(endpoint="posts", sort="published_at DESC", limit="5") %}

<!-- Afficher l'interface -->
<div id="recent-posts">
	{% for post in recent_posts.data %} {% include '_recent-post-card.twig' with post %} {% endfor %}
</div>

Utilisez l’argument nommé endpoint pour définir le point de terminaison de l’API. Vous pouvez définir tous les autres paramètres simplement en les envoyant comme arguments nommés à la fonction Twig data (Ex : sort="published_at DESC").

Routes personnalisées

Il existe deux façons d’ajouter des routes personnalisées :

• Le blogueur peut ajouter des routes personnalisées depuis la console (voir la documentation).
• Les développeurs de thèmes peuvent définir des routes personnalisées en ajoutant des fichiers nommés route-{route}.twig au dossier templates.

La première option est plus robuste, et elle offre un moyen plus facile de définir automatiquement les variables d’entrée _posts (par filtrage), _tag, _author, etc. afin que vous puissiez y accéder sans appeler l’API de données. Mais, en tant que développeur de thème, vous devrez utiliser la deuxième option.

Par exemple, disons que vous décidez que votre thème doit avoir une page listant tous les auteurs du blog. Vous pouvez ajouter un fichier route-authors.twig au dossier templates. Si le blog reçoit une requête vers /authors, ce modèle sera rendu automatiquement.