Tutoriels gantry5 niveau avancé

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

 

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 %}

Les préréglages de mise en page sont des éléments de base que le Layout Manager utilise comme point de départ pour vous permettre de personnaliser la mise en page de votre site. Chaque preset vous donne une nouvelle série de sections, chacune liée à un style, affirmant l'aspect et la convivialité du site. Vous pouvez ensuite placer des particules et positions dans ces sections, ajouter des lignes, et organiser la page de la façon dont vous voulez qu'elle ressorte.

Si vous ne trouvez pas un preset qui réponde à vos besoins, vous pouvez en créer un nouveau.

C’est très facile pour un développeur qualifié de créer un Preset de mise en page. Il s’agit soit de prendre un Preset de mise en page existante et de lui ajouter ou supprimer des sections, soit de construire une toute nouvelle disposition prédéfinie à partir de zéro, si vous y êtes disposé.

 

Contrairement à l'ajout de lignes dans une section, la création d'une nouvelle section (soit de manière autonome ou comme une barre latérale) vous donne la possibilité de créer du style CSS personnalisé qui affecte la nouvelle zone de la page.

Il est important de noter qu’il s’agit d’une action pointue, et les thèmes Gantry 5 ne comprennent généralement la pas prise en charge intégrée de style pour les nouvelles sections. Vous devrez ajouter vous-même le style, soit en le reliant à une section existante soit en le créant de toutes pièces dans votre fichier custom.scss situé dans THEME_DIR/custom/scss.

Images des Presets

Il y a une section des fichiers YAML pour les préréglages de mise en page qui s’occupe de l'image du preset. C’est est une part importante du fichier parce qu'il crée l'image d'aperçu que vous voyez lorsque vous naviguez sur l'interface d'administration Outlines. Il peut servir de référence rapide pour l’outline, vous donnant un coup d'oeil rapide sur ce à quoi le template ressemble sans avoir à visiter le gestionnaire de mise en page.

Gantry comprend un jeu de ces images parmi lesquelles vous pouvez choisir. Ils sont situés dans le répertoire SITE_ROOT/administrator/components/com_gantry5/images/layouts/ et peut être facilement référencé avec un lien de flux. Par exemple, si vous voulez faire un lien vers le fichier 2-col-left.png dans ce dossier, vous pouvez utiliser URL: gantry-admin://images/layouts/2-col-left.png comme l’image du preset.

Création d'un nouveau Preset de mise en page

La création d'une nouvelle mise en page préréglée est assez simple. La première chose que vous devez faire est de créer un nouveau fichier YAML dans THEME_DIR/custom/layouts. Pour notre exemple, nous allons nommer ce fichier example1.yaml.

Voici l'exemple de code qui sera dans notre nouveau fichier YAML:

 

version: 2
 
 preset:
   image: gantry-admin://images/layouts/default.png
 
 layout:
   /header/:
     -
       - menu
 
   /main/:
     -
       - position-breadcrumbs
     -
       - system-messages
     -
       - system-content
 
   /mainbottom/:
     -
       - position-mainbottom
 
   /footer/:
     -
       - position-footer
     -
       - copyright 40
       - spacer 30
       - branding 30
 
   offcanvas:
     -
       - mobile-menu

 

 

 

Ceci est une mise en page prédéfinie de base, comportant trois sections comprises dans le style d'origine du thème (header, main, et footer) avec une section supplémentaire ajoutée (mainbottom) qui n’est pas inclus dans le thème original. Nous ne recommandons pas l'ajout de nouvelles sections si vous ne devez pas le faire, mais cela peut être fait en l'ajoutant dans une mise en page Preset personnalisée.

Une fois que vous avez ajouté une nouvelle section, elle s'affichera sans style en dehors des valeurs par défaut du modèle. Pour ajouter votre propre style, vous pouvez le faire via le fichier custom.scss situé dans THEME_DIR/custom/scss. Par exemple, si vous vouliez que la balise H1 soit rendue rouge, vous devez ajouter la ligne #g-mainbottom h1 {color: red;}.

Les sections Gantry apparaissent dans SCSS sous la balise g- (nom de la section). La section main serait g-main, par exemple. Ceci est fait pour séparer les noms de votre section d’autres affectations de style tierces potentiellement conflictuelles.

Comment créer une Section de barre latérale (Sidebar)

Dans cette section, nous allons expliquer comment créer une nouvelle disposition prédéfinie avec double barre latérale. Chaque section de barre latérale représente un block à l’intérieur du conteneur grid qui composent les sections Main, Sidebar 1, et Sidebar 2. Vous pouvez trouver plus d’informations sur le fonctionnement des sidebars dans le Guide du gestionnaire de mise en page.

La première chose que vous aurez à faire est de créer un nouveau fichier YAML dans THEME_DIR/custom/layouts.