Après avoir téléchargé et installé votre thème géré par Gantry, vous pouvez le personnaliser pour apporter des modifications allant au-delà de ses paramètres et des options de particule inclus.
Par exemple, vous pouvez ajouter un champ de texte en backend qui vous permettra de facilement modifier le texte dans une zone spécifique de la page. Vous pouvez également ajouter des champs et des fonctionnalités aux particules de base de Gantry5, ainsi qu’à tout ce qui est inclus dans le thème lui-même.
La clé pour surcharger les fichiers est le dossier /custom
à l’intérieur du dossier de thème principal. Ce dossier est l'endroit où vous pouvez placer les substitutions et les fichiers supplémentaires que vous aimeriez ajouter au thème sans risque de casser ou de perdre ces données lors d'une mise à jour de thème.
Nous recommandons de comparer les fichiers mis à jour sur votre version personnalisée après avoir effectué une mise à jour afin de voir si des changements qui ont été apportés seraient bénéfiques à utiliser dans votre remplacement.
Personnalisation des fichiers du thème
Dans cet exemple, nous allons ajouter un champ à la section de réglage Settings dans le panneau administratif de mise en page Layout qui vous permettra d'utiliser l'image picker pour créer une image d'arrière-plan d'une section particulière du site. Ce changement nécessite deux fichiers à copier dans le répertoire /custom
et à modifier. Dans ce cas, nous utilisons le template gratuit Hydrogen pour notre exemple.
Sur la photo ci-dessus voici la section Showcase du site, qui comprend la particule Sample Content, inclus dans le theme Hydrogen. La particule elle-même ne définit l'image de fond nulle part dans son fichier twig, et dans ce cas, nous voulons créer cette capacité pour chaque section indépendemment de ses particules ou positions.
Dans Hydrogen la première chose que nous devons faire est d’ajouter le sélecteur d’Image aux options pour chaque section. Cela permettra à l’utilisateur de définir l’image d’arrière-plan de la section.
Pour ce faire, vous devrez créer une substitution de section.yaml
situé dans /media/gantry5/engines/nucleus/admin/blueprints/layout/
. Pour créer la surcharge, vous devez copier ce fichier et le coller dans /TEMPLATE_DIR/custom/admin/blueprints/layout/
.
Voici à quoi ressemble le fichier avant nos changements :
name: Section description: Layout section. type: section form: fields: boxed: type: select.selectize label: Layout description: Select the Layout container behavior. 'Inherit' refers to Page Settings. isset: true selectize: allowEmptyOption: true options: '': Inherit 0: Fullwidth (Boxed Content) 2: Fullwidth (Flushed Content) 1: Boxed 3: Remove Container class: type: input.selectize label: CSS Classes description: Enter CSS class names. default: extra: type: collection.keyvalue label: Tag Attributes description: Extra Tag attributes. key_placeholder: Key (data-*, style, ...) value_placeholder: Value exclude: ['id', 'class']
Pour ajouter l’option d’arrière-plan, il nous suffit de créer un champ input.imagepicker
. Vous pouvez voir notre copie du fichier modifiée ci-dessous.
name: Section description: Layout section. type: section form: fields: boxed: type: select.selectize label: Layout description: Select the Layout container behavior. 'Inherit' refers to Page Settings. isset: true selectize: allowEmptyOption: true options: '': Inherit 0: Fullwidth (Boxed Content) 2: Fullwidth (Flushed Content) 1: Boxed 3: Remove Container class: type: input.selectize label: CSS Classes description: Enter CSS class names. default: extra: type: collection.keyvalue label: Tag Attributes description: Extra Tag attributes. key_placeholder: Key (data-*, style, ...) value_placeholder: Value exclude: ['id', 'class'] background: type: input.imagepicker label: Background
La prochaine chose à faire est de créer une surcharge du fichier actuel section.html.twig
. Ce fichier se trouve dans : /media/gantry5/engines/nucleus/templates/layout
. Pour créer un remplacement pour ce fichier qui ne soit pas écrasé lors d'une mise à jour de thème, vous devriez le copier et le coller dans /templates/TEMPLATE_DIR/custom/engine/templates/layout
. Vous devez créer le chemin d'accès du répertoire si il n'existe pas déjà.
Voici le fichier section.html.twig
avant nos modifications:
{% set tag_type = segment.subtype|default('section') %} {% set attr_id = segment.attributes.id ?: 'g-' ~ segment.id %} {% set attr_class = segment.attributes.class %} {% set attr_extra = '' %} {% set boxed = segment.attributes.boxed %} {% if boxed is not null %} {% set boxed = boxed|trim == '' ? gantry.config.page.body.layout.sections : boxed %} {% endif %} {% if segment.attributes.extra %} {% for attributes in segment.attributes.extra %} {% for key, value in attributes %} {% set attr_extra = attr_extra ~ ' ' ~ key|e ~ '="' ~ value|e('html_attr') ~ '"' %} {% endfor %} {% endfor %} {% endif %} {% set html %} {% if segment.children %} {% for segment in segments %} {% include '@nucleus/layout/' ~ segment.type ~ '.html.twig' with { 'segments':segment.children } %} {% endfor %} {% endif %} {% endset %} {% if html|trim %} {% if boxed is not null and (boxed == 0 or boxed == 2) %} {% set html %} <div class="g-container">{{ html|raw }}</div> {% endset %} {% endif %} {% set html %} {% if boxed == 2 %}{% set attr_class = attr_class ~ ' g-flushed' %}{% endif %} {% set attr_class = attr_class ? ' class="' ~ attr_class|trim ~ '"' %} <{{ tag_type }} id="{{ attr_id }}"{{ attr_class|raw }}{{ attr_extra|raw }}> {{ html|raw }} </{{ tag_type }}> {% endset %} {% if boxed == 1 %} <div class="g-container">{{ html|raw }}</div> {% else %} {{ html|raw }} {% endif %} {% endif %}
Ce que nous aimerions faire pour cet exemple est d'ajouter un div qui entoure le HTML, ajoutant l'arrière-plan que l'utilisateur a ajouté depuis le champ Sélecteur d'image dans les paramètres de la Section. Pour ce faire, nous devont diriger la div vers l'attribut défini dans le fichier section.
.
Voici le même fichier avec les changements :
{% set tag_type = segment.subtype|default('section') %} {% set attr_id = segment.attributes.id ?: 'g-' ~ segment.id %} {% set attr_class = segment.attributes.class %} {% set attr_background = segment.attributes.background %} {% set attr_extra = '' %} {% set boxed = segment.attributes.boxed %} {% if boxed is not null %} {% set boxed = boxed|trim == '' ? gantry.config.page.body.layout.sections : boxed %} {% endif %} {% if segment.attributes.extra %} {% for attributes in segment.attributes.extra %} {% for key, value in attributes %} {% set attr_extra = attr_extra ~ ' ' ~ key|e ~ '="' ~ value|e('html_attr') ~ '"' %} {% endfor %} {% endfor %} {% endif %} {% set html %} {% if segment.children %} {% for segment in segments %} {% include '@nucleus/layout/' ~ segment.type ~ '.html.twig' with { 'segments':segment.children } %} {% endfor %} {% endif %} {% endset %} {% if html|trim %} {% if boxed is not null and (boxed == 0 or boxed == 2) %} {% set html %} <div class="g-container">{{ html|raw }}</div> {% endset %} {% endif %} {% set html %} {% if boxed == 2 %}{% set attr_class = attr_class ~ ' g-flushed' %}{% endif %} {% set attr_class = attr_class ? ' class="' ~ attr_class|trim ~ '"' %} <{{ tag_type }} id="{{ attr_id }}"{{ attr_class|raw }}{{ attr_extra|raw }}> {% if attr_background %}<div class="section-background" style="background-image: url(/{{ url(attr_background) }})">{% endif %} {{ html|raw }} {% if attr_background %}</div>{% endif %} </{{ tag_type }}> {% endset %} {% if boxed == 1 %} <div class="g-container">{{ html|raw }}</div> {% else %} {{ html|raw }} {% endif %} {% endif %}
Une fois que vous avez fait ces changements, vous devriez maintenant être en mesure d'accéder à l'administrateur Gantry et ajouter une image à votre section, enregistrez le changement, et vérifiez-le sur votre site.
Matrice des Répertoires du Theme
Voici un guide de référence rapide pour vous aider à naviguer dans la structure du répertoire d'un thème Gantry, ainsi que les endroits où vous pouvez mettre vos modifications personnalisées dans le répertoire custom
.
Les fichiers de template
Tous les fichiers situés dans les sous-répertoires des répertoires listés ci-dessous seraient également ajoutés au répertoire personnalisé afin de surcharger un fichier stocké dedans. Par exemple, scss/hydrogen/_core.scss
devrait être copié et modifié dans le répertoire custom
en tant que custom/scss/hydrogen/_core.scss
.
La première table des dossiers a comme racine le répertoire ROOT/templates/TEMPLATE_DIR/
où ROOT
est le répertoire racine du site Joomla et TEMPLATE_DIR
est le répertoire de template pour le template poussé par Gantry. Il contient des fichiers spécifiques au thème.
Répertoire |
Description |
---|---|
admin | Contient un répertoire images comme les images du thème utilisées dans l'administrateur Gantry ainsi que toutes autres ressources admin. |
blueprints | Contient les champs de réglage de style et d'autres éléments abstraits nécessaires au thème. |
blueprints/styles | Contient des fichiers YAML mettant en place les champs et les paramètres pour les réglages de style configurables qui apparaissent dans le panneau d'administration Styles. |
fonts | Contient des polices personnalisées utilisées par le thème. |
gantry | Contient presets.yaml qui contient les paramètres de style prédéfinis. Contient également theme.yaml qui définit le panneau d’administration About. |
language | Contient les fichiers de langue utilisés dans Gantry. |
layouts | Contient les fichiers YAML qui composent les paramètres pour les presets Layout situés dans le gestionnaire de Layout. |
particles | Contient des particules personnalisées ou surchargées pour ajouter ou modifier des fonctionnalités au thème. |
scss | Contient tous les fichiers SCSS non spécifiques à la plate-forme joomla pour le thème et est divisé en plusieurs sous-répertoires et fichiers. |
html | Comme vous le feriez normalement dans tout template, dans le dossier html vous pouvez mettre toute substitution pour les composants / modules. Par exemple html/com_content/article/default.php . plus de détails |
Fichiers du moteur
Le lot suivant est spécifique au framework Gantry, et non au thème. Ces dossiers se trouvent dans le répertoire ROOT/media/gantry5
, qui contient des données utilisées par le framework, indépendamment du thème.
Le répertoire ROOT/media/gantry5/assets/
contient des ressources tierces utilisées par Gantry 5. Ceci comprend le paquet de polices Font Awesome's, Images de logo de gantry, etc.
Les répertoires suivants à la racine du répertoire ROOT/media/gantry5/engines/nucleus
. Ce répertoire abrite les fichiers qui appartiennent au moteur Nucleus, qui est le cœur du système de mise en page Gantry 5. Il fournit les CSS de base, mise en page du contrôle, base de fichiers pour la création de thème, etc..
Lorsque vous créez des copies de ces fichiers personnalisés, vous devez les mettre dans TEMPLATE_DIR/custom/engine/
pour indiquer que ce sont des répertoires spécifiques au moteur et qui ne font pas partie des données spécifique au thème.
Répertoire : |
---|
admin/blueprints |
layouts |
particles |
scss |
templates |
templates/content |
templates/partials |
twig |
twig/partials |
Fichiers Administration
Les fichiers de composant de l’administration de Gantry sont situés dans le répertoire ROOT/administrator/components/com_gantry5/
. Ces fichiers contrôlent l’apparence de l’admin de gantry, ses panneaux, et quelles données ces panneaux affichent. Pratiquement tout ce qui n’est pas particulièrement contrôlé par Joomla peut être modifié à partir du template.
La substitution de ces fichiers est une action pointue qui ne devrait être effectuée seulement si vous êtes absolument certain que vous devez. La grande majorité des utilisateurs aura besoin de ne modifier aucun de ces fichiers.
Des copies personnalisées de ces fichiers pourront être placées dans TEMPLATE_DIR/custom/admin
avec les mêmes chemins de répertoire que l'on trouve dans le répertoire principal com_gantry5
. Par exemple, ROOT/administrator/components/com_gantry5/templates/pages/about/about.html.twig
serait copié vers TEMPLATE_DIR/custom/admin/templates/pages/about/about.html.twig
.