Tuto Grav - Customiser votre thème (template) avec Inheritance

En modifiant votre thème Grav directement dans les fichiers de base, toute mise à jour du thème peut potentiellement remplacer les modifications effectuées. En copiant le thème cela pourrait être OK mais les mises à jour et les correctifs de votre thème central devront être fusionnés manuellement sur le thème copié.

Il existe une méthode simple et adapté à cela: Inheritance (héritage).

Grav fait un usage intensif de PHP streams à travers son architecture pour permettre aux ressources (fichiers de base) d'être personnalisables. L'utilisation classique de ces "streams" se fait au niveau de la configuration du système. On peut donc remplacer (customiser) les options système, fichiers YAML utilisateur, mais aussi les fichiers "environment-based configuration".

Les Streams sont également utilisés au niveau des thèmes (fichiers Twig , CSS et JavaScript).

Commençons par créer un nouveau thème pour customiser le template de base antimatter

1. Créer un nouveau dossier: user/themes/mytheme pour héberger votre nouveau thème.
2. Créez un nouveau fichier thème YAML: /user/themes/mytheme/mytheme.yaml avec le contenu suivant:

   streams:
    schemes:
      theme:
        type: ReadOnlyStream
        prefixes:
          '':
            - user/themes/mytheme
            - user/themes/antimatter

3. Changez votre thème par défaut pour utiliser votre nouveau thème mytheme en éditant les options pages: Thème: du fichier de configuration user / config / system.yaml :

   pages: 
    thème: mytheme

Avec ces 3 étapes, Vous avez créé un nouveau thème appelé mytheme, vous avez mis en place le flux de sorte qu'il va d'abord regarder dans le thème mytheme, puis continuer avec le thème initial antimatter. Donc, en substance, antimatter est bien le thème de base du nouveau thème mytheme.

Ex : Apporter une modification CSS

Le type de modification la plus courante consiste à ajouter des CSS personnalisés. La valeur par défaut du thème antimatter supporte déjà la possibilité d'utiliser un fichier custom.css :  css / custom.css . On fait donc la manip sur le thème mytheme: On créé un répertoire css; on y met un fichier vide custom.css dans lequel nous allons pouvoir y rajouter les codes que l'on veut.

mytheme
├── css
│ └── custom.css
└── mytheme.yaml

Dans ce thème, nous allons mettre un code css simple et checker si cela fonctionnent comme attendu:

body a { color: #f00; }

Si vous rechargez votre navigateur pointant vers votre site Grav, vous devriez voir que les liens passent de la couleur bleu de base au rouge:

Si vous affichez la source, vous verrez ce qui se passe en partie "head"

<link href = "/user/themes/antimatter/css-compiled/nucleus.css"  Type = "text / css" rel = "stylesheet" />
<link href = "/user/themes/antimatter/css-compiled/template.css"  Type = "text / css" rel = "stylesheet" />
<link href = "/user/themes/mytheme/css/custom.css"  Type = "text / css" rel = "stylesheet" />
<link href = "/user/themes/antimatter/css/font-awesome.min.css"  Type = "text / css" rel = "stylesheet" />
<link href = "/user/themes/antimatter/css/slidebars.min.css"  Type = "text / css" rel = "stylesheet" />

Tous les fichiers réguliers CSS proviennent du thème antimatter, tandis que le nouveau custom.css est chargé automatiquement à partir du thème mytheme.

Apporter une modification de template (fichier twig)

Créer votre propre thème avec la méthode "inhéritance" vous permet donc d'apporter des modifications que vous juger nécessaire et importante.

Un exemple de modification fichier twig :

Vous voulez modifier le menu principal pour ajouter un liens statique à la fin de celui-ci. Le fichier twig correspondant se trouve dans templates/partials/navigation.html.twig . Vous créez les répertoires templates/partials, et copier le fichier à jour navigation.html.twig dans le répertoire partials.

mytheme
├── mytheme.yaml
└── templates
    └── partials
        └── navigation.html.twig

Ensuite, éditez le fichier navigation.html.twig et ajoutez vos personnalisations. Dans ce cas, nous allons tout simplement ajouter un lien vers le sitegetgrav.org à la fin de nos liens normaux:

...
<ul class = "navigation">
    {% Si% config.themes.antimatter.dropdown.enabled}
        {{_self.loop (Pages)}}
    {% Autre%}
        {% Pour la page dans pages.children%}
            {% Si page.visible%}
                {% Ensemble current_page = (page.active ou page.activeChild)? 'Actif': ''%}
                <li class = "{{}} current_page">
                    <a href= "{{ page.url }}">
                        {% Si page.header.icon%} <i class = "fa fa - {{}} page.header.icon"> </ i> {% endif%}
                        {{}} Page.menu
                    </a>
                </ li>
            {% fin si %}
        {% Endfor%}
    {% fin si %}
    <li> <a href= "http://getgrav.org"> GetGrav.org </a> </ li>
</ ul>  

Enregistrez le fichier et rechargez la page. Vous devriez voir vos modifications en live:

Personnalisation avancée

Si vous souhaitez ajouter une nouvelle fonctionnalité JavaScript par exemple, vous aurez probablement besoin d'ajouter un fichier .js à votre thème. Sur le principe de l'exemple ci-dessus vous devez modifier le fichier templates/partials/base.html.twig et le mettre dans le répertoire partials .

Si vous souhaitez faire une personnalisations CSS poussée en dehors du fichier custom.css, vous pouvez copier le dossier complet SCSS / pour y effectuer vos changements. Attention, Grav ne contient pas de compilateur intégré. Vous devez compiler en local (voir article Compilateur SCSS - Installation et utilisation sous Windows (Ruby, SASS)) et transférer vos fichiers compilés dans le répertoire themes/mytheme/css-compiled

Vous pouvez bien sûr personnaliser toute partie du thème original, juste être conscient que plus vous personnalisez, plus vous substituez, plus votre thème personnalisé sera divergeant / thème de base qu'il hérite. Cela peut bloquer à un moment.

Si il arrive un moment où vous ne voulez vraiment plus compter sur le thème de base, vous pouvez vous contenter de copier les éléments manquants du template de base et de supprimer l’appel à celui ci dans le fichier /user/themes/mytheme/mytheme.yaml.