Création d'un thème CMS Grav simple avec Twig, PHP et CSS

Cet article est apparu pour la première fois sur Symfony Station.

Introduction

Si vous lisez ceci, vous savez que créer des sites Web axés sur le contenu est aujourd'hui une tâche trop compliquée.

Mais il existe un système de gestion de contenu qui rend les choses plus faciles et plus simples. Et cela est particulièrement vrai pour les développeurs frontend. C'est Grav CMS.

Je vais personnaliser un thème pour grav.mobileatom.net qui est mon site professionnel principal. Devinez quoi? Cela n’impliquera aucune IA.

Et écrire cet article sera ma façon d'apprendre comment le faire et d'aider la communauté. Vous ne voyez pas beaucoup d'articles sur Grav.

Nous allons couvrir :

(1) Organisation / structure des fichiers
(2) Modèles de brindilles
(3) CSS
(4) Fonctionnalité de brindille
(5) Personnalisation

Si vous ne le savez pas, GravCMS est l'un des nombreux CMS basés sur Symfony.

Les détails techniques de cet article sont pour la plupart paraphrasés de la documentation Grav. Comme je viens de le dire, j'apprends cela moi-même.

Grav dit :

"Le cœur de Grav est construit autour du concept de dossiers et de fichiers de démarques pour le contenu. Ces dossiers et fichiers sont automatiquement compilés en HTML et mis en cache pour des raisons de performances.

Ses pages sont accessibles via des URL directement liées à la structure de dossiers qui sous-tend l'ensemble du CMS. En rendant les pages avec les modèles Twig, vous avez un contrôle total sur l'apparence de votre site, avec pratiquement aucune limitation."

Très bien, jetons un œil aux thèmes.

Thèmes gravitationnels

Les thèmes dans Grav sont construits avec des modèles Twig et vous pouvez en apprendre beaucoup plus sur Twig dans mon article, Twig : Le guide ultime du premier langage de modèles PHP. De plus, nous entrerons dans quelques détails ici.

Comme je l'ai écrit ici, Twig est un langage de création de modèles PHP qui génère des variables dans le HTML des vues dans la programmation MVC (modèles, vues, contrôleurs). Ainsi, cela contribue à la structure du frontend de votre site Web.

Il a été créé par Fabien Ponticier qui a également créé Symfony, ce n'est donc pas une surprise qu'il soit utilisé dans Grav.

Il a noté qu '"un langage de modèle est quelque chose qui vous aide à écrire des modèles qui respectent cette séparation des préoccupations (MVC). Un langage de modèle doit trouver un bon équilibre entre fournir suffisamment de fonctionnalités pour faciliter la mise en œuvre de la logique de présentation et restreindre les fonctionnalités avancées. fonctionnalités pour éviter que la logique métier paralyse vos modèles. "

Que sont exactement les modèles PHP ? Comme indiqué ci-dessus, ils sont utilisés pour séparer la vue de votre application PHP de ses modèles et objets.

Les principales caractéristiques de Twig sont les suivantes :

• Rapide : Twig compile les modèles en code PHP optimisé. La surcharge par rapport au code PHP standard a été réduite au minimum.
• Sécurisé : Twig dispose d'un mode bac à sable pour évaluer le code de modèle non fiable. Ce mode permet à Twig d'être utilisé comme langage de modèle pour les applications où les utilisateurs modifient la conception du modèle.
• Flexible : Twig est alimenté par un lexer et un analyseur flexibles. Cette flexibilité permet au développeur de définir des balises et des filtres personnalisés (nous en parlerons plus tard) et de créer son DSL unique.

Quelques notes finales rapides :

• Les noms des modèles Twig se terminent par .html.twig.
• Vous les configurez avec YAML.
• Et ils fonctionnent bien avec le CSS Vanilla.

Chaque page que vous créez dans Grav via l'interface d'administration fait référence à un fichier modèle Twig. Une bonne pratique consiste à faire correspondre autant que possible les noms de fichiers de modèles aux noms de pages. Ou au moins la structure des dossiers de vos fichiers de contenu.

Par exemple, blog.md serait rendu avec le modèle Twig blog.html.twig

(1) Organisation / structure des fichiers

Ok, regardons comment un thème Grav est structuré.

Chaque thème possède un fichier de définition nommé blueprints.yaml. Il peut également fournir des définitions de formulaire pour le panneau d'administration.

Pour utiliser les options de définition de thème, fournissez les paramètres par défaut dans un fichier your_theme_name.yaml.

Incluez un jpg 303x300 nommé thumbnail.jpg dans la racine du thème.

(2) Modèles de brindilles et plus

Les modèles Twig de votre page Grav doivent se trouver dans un dossier templates/ avec des sous-dossiers pour :

• formulaires/
• modulaire/
• partiels/

Une bonne pratique consiste à développer votre thème en conjecture avec votre contenu. Cette stratégie est l'une des raisons pour lesquelles je suis si investi dans Grav. Fichiers de page = Modèles de brindilles.

Encore une fois, default.md, blog.md, error.md, item.md, modular.md équivaudrait à default.html.twig, blog.html.twig, etc.

Votre thème a besoin d'un dossier css/ pour votre CSS.

Ajoutez également les dossiers images/, fonts/ et js/ à votre racine pour stocker des ressources personnalisées.

Un dossier blueprints/ hébergera le fichier avec vos définitions de formulaire comme mentionné précédemment.

Les plugins sont intégrés aux thèmes Grav via des hooks.

Ainsi, your_theme_name.php hébergera votre logique non-Twig.

Juste pour information, si vous souhaitez créer un thème commercial à vendre à d'autres, vous aurez également besoin de ces fichiers :

• CHANGELOG.md
• LICENCE.md
• LISEZMOI.md
• capture d'écran.jpg
• vignette.jpg

Un modèle de base

Vous pouvez obtenir mon modèle avec juste un modèle Twig par défaut avec Grav.

Mais il est préférable d'utiliser la balise Twig Extends pour définir une mise en page de base via des blocs dans un modèle de base. Ce fichier est stocké dans le sous-dossier partials/ sous le nom base.html.twig. Voir l'image ci-dessus.

Dans vos modèles par défaut et autres modèles spécialisés, utilisez la balise extends pour extraire votre mise en page de base à partir de base.html.twig.

Donc, pour votre fichier default.html.twig utilisant la syntaxe Twig, vous coderiez :

{% extends 'partials/base.html.twig'%}

{%block content %}
  {{page.content | raw}}
{%endblock%}

Le premier ensemble de codes étend le modèle de base qui contient votre mise en page de base.

Le second remplace le contenu du modèle de base par le code de votre nouveau modèle.

(3) Thème CSS

Examinons ensuite le CSS de votre thème Grav. Il existe plusieurs façons de le mettre en œuvre, notamment SCSS. Mais, dans le souci de rester simple, je me concentrerai sur le CSS vanille. C'est court. Ajoutez un fichier custom.css et allez en ville.

(4) Fonctionnalité de brindille

Jetons également un rapide coup d'œil au fonctionnement de Twig.

Les balises Twig comme Extend contrôlent la logique de vos modèles. Ils disent à Twig quoi faire. À mon humble avis, Block est la balise la plus importante.

Les autres incluent :

• cache
• démarquage
• scénario
• style
• interrupteur
• etc

Les filtres Twig sont utiles pour formater et manipuler du texte et des variables.

Ils comprennent :

• date
• évasion
• rejoindre
• inférieur
• tranche
• etc

Les fonctions peuvent générer du contenu et implémenter des fonctionnalités (évidemment). Ils peuvent également faire certaines des mêmes choses que les filtres peuvent faire.

Donc, pour vos modèles, utilisez les balises, les filtres et les fonctions Twig requis pour vos besoins uniques.

Étiquettes de brindille de Grav

En plus des balises que vous choisissez, Grav inclut des balises Twig personnalisées pour étendre ses capacités.

Ils comprennent :

• démarquage
• script (vous pouvez extraire du JavaScript par exemple)
• style
• lien
• interrupteur
• différé (chargement des actifs)
• lancer (exceptions)
• essayer/attraper
• rendu (objets flexibles)
• cache

Configuration du thème

Avec Grav, vous pouvez accéder aux informations de configuration du thème et aux plans à partir de vos fichiers Twig et PHP. Vous pouvez le faire via des objets de thème ou vous pouvez utiliser un plugin Grav avec la syntaxe PHP.

En tant que bonne pratique, ne modifiez pas le fichier your_theme_name.yaml par défaut de votre thème (voir l'image ci-dessus). Remplacez-le dans un dossier user/config/themes.

Pour finir, Twig possède également des objets et des variables personnalisés dont nous ne parlerons pas ici. N'oubliez pas que je garde les choses simples.

Gestionnaire d'actifs

Asset Manager de Grav offre un moyen flexible de gérer les fichiers CSS et JavaScript. Il comprend un pipeline d'actifs pour réduire, compresser et intégrer les actifs.

Il est disponible et accessible dans les hooks d'événements du plugin ou directement dans les thèmes via les appels Twig. Il possède son propre fichier de configuration dans user/config/system.yaml.

Vous pouvez obtenir des informations granulaires au niveau de l'entreprise avec Asset Manager, nous ne les aborderons donc pas plus en détail ici.

Dans le souci de rester simple, je recommande d'utiliser le plugin Assets (voir image ci-dessus). Téléchargez-le depuis l'administrateur Grav. Utilisez-le ensuite pour mettre à jour ou ajouter des éléments si nécessaire.

(5) Personnalisation

Nous avons donc expliqué comment créer un thème Grav simple et rapide. Configurez votre structure, créez vos modèles Twig et ajoutez du CSS et du JavaScript si nécessaire.

Et vous avez vu qu'il existe une variété de façons de créer un thème Grav pour répondre à vos besoins simples ou complexes, mais Grav fournit des caractéristiques et des fonctionnalités pour le rendre encore plus facile. Et c'est ainsi que je vais personnaliser le thème de mon site.

Héritage du thème

Le moyen le plus simple consiste à utiliser l'héritage de thème. J'aime ça car c'est similaire à ce que j'ai fait avec les thèmes WordPress et Drupal.

C'est aussi le moyen préféré de Grav pour personnaliser un thème.

Vous définissez un thème de base dont vous héritez. Par exemple le thème par défaut Quark ou celui que vous avez acheté. Ensuite, vous ajoutez ou modifiez ce que vous souhaitez personnaliser et laissez le thème de base gérer le reste.

Cette stratégie vous permet également de mettre à jour le thème de base sans perdre les personnalisations de votre thème d'héritage.

Il existe plusieurs façons de créer un thème d'héritage. Mais encore une fois, par souci de simplicité, regardons le processus manuel.

Créer un nouveau dossier -> user/themes/your_theme_name pour contenir le thème personnalisé.

Copiez ensuite le fichier YAML du thème dont vous hériterez dans le nouveau dossier. Nommez-le your_theme_name.yaml et changez le nouveau nom du thème partout où vous voyez Quark.

Ensuite, copiez le fichier users/themes/quark/blueprint.yaml dans votre dossier user/themes/your_theme_name.

Maintenant, changez le thème par défaut dans le fichier user/config/system.yaml.

pages :
thème : votre_nom_du_thème

Enfin, pour ajouter des fonctionnalités avancées basées sur les événements, créez un fichier user/themes/your_theme_name/your_theme_name.php.

{% extends 'partials/base.html.twig'%}

{%block content %}
  {{page.content | raw}}
{%endblock%}

Vous avez maintenant configuré les flux de Grav pour qu'ils apparaissent d'abord dans votre_nom_du_thème, puis essaient Quark.

Maintenant, fournissez les modifications de modèles CSS, JS et Twig dont vous avez besoin.

Vous avez terminé. Assez simplement.

Conclusion

Wow. Merci d'avoir lu l'intégralité de l'article.

Vous en savez désormais plus sur les thèmes Grav :

(1) Organisation / structure des fichiers
(2) Modèles de brindilles
(3) CSS
(4) Fonctionnalité de brindille
(5) Personnalisation

Pensez à utiliser Grav pour sa simplicité, notamment lors de la personnalisation des thèmes. Qu'est-ce qu'il n'y a pas à aimer à propos de PHP, Twig, Vanilla CSS et JS. Vous créez même votre contenu en markdown.

Continuez à coder les Symfonistas et les Gravinauts !

Ressources

https://learn.getgrav.org/17/themes

https://twig.symfony.com/

https://twig.symfony.com/doc/3.x/

https://www.drupal.org/docs/contributed-modules/twig-tweak-2x/cheat-sheet

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!