Tutoriels gantry5 niveau avancé

Comprenant certaines options de configuration et de personnalisation avancées pour Gantry 5.

La création d'une nouvelle particule dans Gantry 5 est un processus assez simple. Comme vous allez créer deux fichiers pour la particule, vous allez avoir besoin d'un éditeur de texte.

particle 1

Pour l'intérêt de ce guide, nous allons créer une simple particule pour une page sur un site. Cette particule se compose de trois parties principales. Le Titre, Image, et la Description. Les particules peuvent être autant simples que complexes selon vos besoins, quels qu’ils soient.

Lorsque vous créez vos noms de fichiers, vous devez éviter les caractères spéciaux tels que des tirets, les accents, les espaces.

Création du fichier YAML

Pour créer votre particule, il devrait être plus facile de commencer avec le fichier YAML car cela agit comme un plan d’action pour la particule. Le fichier Twig utilise ce fichier YAML pour en tirer des informations, des paramètres et savoir quels champs sont utilisés dans l’administration comme variables.

particle 2

Vous allez créer ce fichier dans la structure des dossiers de votre template en accédant à TEMPLATE_DIR/custom/particles et en créant un fichier nommé comme example_particle.yaml. Vous pouvez remplacer example_particle par tout ce que vous désirez. Cela se trouve être le nom que nous utilisons pour cette particule d’exemple. Le nom de fichier sera renvoyé à plus tard.

Voici le corps du fichier YAML de notre exemple de particule:

name: Example
description: Displays a Title, Image, and Text on the front end.
type: particle

form:
  fields:
    enabled:
      type: input.checkbox
      label: Enabled
      description: Globally enable to the particles.
      default: true

    title:
      type: input.text
      label: Title
      description: Customize the section title text.   

    image:
      type: input.imagepicker
      label: Image
      description: Select the main image.

    description:
      type: textarea.textarea
      label: Text / HTML
      description: Create or modify your description.

    css.class:
      type: input.text
      label: Class
      description: CSS class name for the particle.

 

Ce YAML est composé de deux parties principales. Tout d'abord, l’entête du fichier qui définit le nom, la description, et le Type. Le nom est ce qui apparaît dans l'administration comme titre de la particule dans les paramètres et les panneaux du Gestionnaire de mise en page. Le Type étant Particle dit à Gantry que ce fichier YAML est utilisé pour créer une particule.

Le paramètre Type avertit Gantry5 que cette particule est une Particle standard , un Atom, ou une Position. Vous allez probablement pas créer des positions puisque une particule de Positions de Module configurable est déjà en place, mais dans le cas où vous créeriez un atome on pourrait lire la ligne, type: atom.

particle 3

La deuxième section définit les formulaires/champs qui apparaissent dans l’administrateur, ainsi que les paramètres par défaut. Ces champs sont ce qui apparaît dans l’administrateur et sont accessible à vos gestionnaires de site. Ils leur donnent la possibilité de faire des choses comme insérer du texte personnalisé, des titres et activer/désactiver les paramètres.

Le premier bloc de champ (enabled) est obligatoire. Il indique à gantry de mettre un interrupteur sur le backend qui permet d'activer/désactiver la particule.

Le reste des champs ici, title, image, description, et css.class fournissent des champs aux gestionnaires de sites afin qu’ils puissent les utiliser pour configurer la particule sans avoir à modifier les fichiers manuellement.

Voici une répartition des paramètres utilisés dans l’exemple ci-dessus et la manière dont ils affectent le fichier :

Réglage

Description

Type Définit le type de champ. Cette valeur détermine si votre utilisateur verra un champ de texte, case à cocher ou tout autre entrée type.
Label Cette étiquette apparaît sur le backend à côté du champ, laissant l'utilisateur de savoir ce qu'il fait / où il est.
Description Ce champ définit l’info-bulle qui apparaît au survol sur l’étiquette. Il est conçu comme un rappel pour l’utilisateur.
Default Ceci définit la valeur par défaut qui s’affiche dans le champ. Si c’est un champ de texte, vous devez entrer le texte. Si c'est une case à cocher, vous devez la définir comme true ou false.

Création du fichier Twig

Le prochain fichier que vous devrez créer, sera déposé dans le même répertoire que le fichier YAML. Nous vous recommandons de le nommer de la même façon que vous avez fait avec le fichier YAML, mais dans le format (name.html.twig). Terminer le nom de fichier avec html.twig dit à Gantry que c’est un fichier Twig, qui est fondamentalement le template du fichier. Il contrôle la façon dont les particules sont rendus, indique le code HTML et détermine la façon dont sont utilisées les variables définies dans le YAML.

Voici le contenu du fichier example_particle.html.twig:

{% extends '@nucleus/partials/particle.html.twig' %}

{% block particle %}
<div class="example_particle {{ particle.css.class }}">
            <div align="center">
              <img src="/{{ url(particle.image) }}" alt="image">
              <h2>{{ particle.title }}</h2>
              <p>{{ particle.description }}</p>
            </div>
        </div>
{% endblock %}

 

Ceci est un exemple très basique d'un fichier Twig, contenant trois parties.

La première partie ({% extends '@nucleus/partials/particle.html.twig' %}) définit le fichier Twig comme étant destiné à une particule. Ceci est un élément incontournable pour tous les fichiers Twig particules.

La deuxième partie est le wrapper de bloc. {% block particle %} et {% endblock %} entourent le bloc contenant la particule. C’est également un composant requis car votre particule ne sera pas restituée correctement sans lui.

La troisième partie est ce qui alimente la particule. C’est l’organe servant à déterminer à quoi ressemblera une particule et qui utilise des renseignements figurant dans le YAML. Dans notre exemple, nous définissons le div class pour example_particle. Cette classe indique à gantry que ce fichier twig collabore avec les informations du fichier compagnon custom_html.yaml .

Le champ de classe CSS utilisé dans cet exemple n’est pas obligatoire. Une CSS peut être appliqué au niveau bloc dans l’administrateur de Gantry 5. Ajout d’un champ de classe ici vous permet d’assigner une classe CSS à un div spécifique au sein de la particule.

Les bits qui sont placés entre accolades comme {{ particle.title|e }} extraient des informations à partir des champs définis dans le YAML et les insérent dans le Twig pour les rendre en frontend.

Le |e qui apparaît après le nom du champ de particules dans notre exemple est un filtre Twig. Vous pouvez trouver une liste de filtres ICI.

Une fois que vous avez créé ces fichiers, vous devriez voir la particule apparaître dans les panneaux Settings et Layout Manager dans l'administrateur Gantry 5.

Obtenir des données de configuration Gantry utilisant Twig

L'un des éléments clés de Gantry est la possibilité de configurer facilement les champs et les options à l'aide des fichiers YAML qui peuvent ensuite être utilisés par les utilisateurs dans l'administrateur Gantry 5 pour configurer le site.

Le fichier YAML crée le champ (ou une option), l'utilisateur configure cette option, définissant la variable que vous pouvez ensuite utiliser pendant le rendu des pages via votre fichier Twig.

Extraire une variable de configuration est assez facile. Vous avez juste besoin d'utiliser la commande gantry.config.get() pour obtenir ces données.

Un exemple de ceci serait d'utiliser la ligne {{ gantry.config.get('styles.base.background') }} pour saisir la couleur d’arrière-plan de base actuellement configurée pour le thème.

Dans notre exemple actuel, nous extayons l'option de configuration pour la particule courante à travers des commandes comme {{ particle.header }} qui obtient la valeur affectée à l’en-tête du champ de cette particule spécifique.

Disons que vous avez voulu obtenir la variable définie par une autre particule. Par exemple, la particule Branding. Vous pouvez extraire cette information à l’aide de {{ gantry.config.get('particles.branding.css.class') }} indique à Gantry de chercher la valeur de classe CSS définie dans la particule Branding. Faire cela va récupérer une valeur par défaut, plutôt qu'une valeur définie dans une instance de particule individuelle à partir du gestionnaire de mise en page ou Menu Editor.

Personnalisation d’une particule existante.

Si vous souhaitez remplacer une particule existante et faire des changements personnalisés à la source de cette particule, vous pouvez le faire en la copiant dans votre répertoire TEMPLATE_DIR/custom et en changeant le ou les fichiers copiés. Ces changements vont remplacer la particule existante de Gantry, de Joomla, ou du thème.

Voici un tableau pour vous aider à déterminer où placer les fichiers YAML et Twig copiés.

Répertoire de fichiers d'origine

Répertoire de fichiers dupliqués

Répertoire de fichiers dupliqués alternatif

media/gantry5/engines/nucleus/particles TEMPLATE_DIR/custom/particles TEMPLATE_DIR/custom/engine/particles
TEMPLATE_DIR/particles TEMPLATE_DIR/custom/particles  

 

Lorsque vous créez une nouvelle particule, vous remarquerez que les champs d’entrée définies dans le fichier YAML varient en fonction de ce que vous essayez d’accomplir.

particle 2

Dans la capture d’écran ci-dessus, vous remarquerez que plusieurs différents types de champs de saisie sont présents. Même l’interrupteur vert dans le coin supérieur droit est un champ défini dans le fichier YAML.

Voici le fichier YAML de la particule :

 

name: Example
description: Displays a Title, Image, and Text on the front end.
type: particle

form:
  fields:
    enabled:
      type: input.checkbox
      label: Enabled
      description: Globally enable to the particles.
      default: true

    title:
      type: input.text
      label: Title
      description: Customize the section title text.   

    image:
      type: input.imagepicker
      label: Image
      description: Select the main image.

    description:
      type: textarea.textarea
      label: Text / HTML
      description: Create or modify your description.

    css.class:
      type: input.text
      label: Class
      description: CSS class name for the particle.

 

 

Il existe plusieurs types différents de champs présentés dans cet exemple,. input.checkbox, input.text, input.imagepicker, et textarea.textarea peuvent être trouvés dans l'exemple précédent. Ci-dessous, nous avons détaillé les types de champs de base inclus dans Gantry 5.

Types de champs Input HTML

Il existe deux principaux types d’entrées prises en charge par Gantry. Les premieres sont des types d’entrées HTML basiques. Gantry les prends en charge par souci de simplicité, ce qui rend vous plus facile la création de particules et vous permets de profiter de tout ce que vous propose le HTML. Ces types incluent notamment :

  • collection.list

  • input.checkbox | Displays a checkbox (default: true=checked / false=unchecked)

    title:       type: input.checkbox       label: Your lable.       description: Your description.       default: true
  • input.color

  • input.date

  • input.datetime-local

  • input.datetime

  • input.email

  • input.file

  • input.group

  • input.hidden

  • input.image

  • input.month

  • input.number

  • input.password

  • input.radio

  • input.range

  • input.reset

  • input.search

  • input.submit

  • input.tel

  • input.text

    title:       type: input.text       label: Your label.       description: Your description
  • input.time

  • input.url

  • input.week

  • textarea.textarea

Types de champs d'entrée spécifiques à Gantry

Les seconds sont des types spécifiques à Gantry qui utilisent des fonctionnalités exclusives de Gantry tels que le fameux sélecteur de couleurs et le selecteur d’image Ces types prennent ce qu’offrent les types d'entrée de vanilla HTML et les améliore pour les rendre plus puissants, plus faciles à utiliser, et exceptionnellement robustes.

Type de champ

Description

input.block-variations Permet de choisir entre les variations de blocs pris en charge par Gantry, vous donnant un moyen rapide d'affiner la façon dont la particule apparaît en frontend.
input.colorpicker Ouvre le Sélecteur de couleurs de Gantry qui vous permet de choisir rapidement une couleur à partir d'outils affichant la teinte, la saturation, la brillance, et une roue de couleur.
input.filepicker Ouvre le navigateur de fichiers de Gantry, vous permettant de sélectionner un fichier à utiliser.
input.fonts Ouvre le sélecteur de polices Gantry qui vous permet de visualiser et de tester plus de 670 polices de la bibliothèque Google Font.
input.icon Ouvre le sélecteur d’Icone Gantry qui affiche et vous permet de sélectionner des icônes FontAwesome à utiliser dans le champ.
input.imagepicker Ouvre le navigateur de fichiers de Gantry, vous permettant de sélectionner une image à utiliser.
input.videopicker Ouvre le navigateur de fichiers de Gantry, vous permettant de sélectionner un fichier vidéo à utiliser.
select.selectize Affiche un ensemble pré-créé des options pour permettre à l'utilisateur de choisir.
select.date Affiche un ensemble pré-créé de formats de date pour permettre aux utilisateurs de choisir.

Champs selectize

select.selectize et select.date nécessitent tous les deux un peu de configuration supplémentaire dans le fichier YAML de la particule pour fonctionner correctement dans l’administrateur de gantry. Voici un exemple d’un type de champ select.selectize du champ de particules YAML.

 

target:
      type: select.selectize
      label: Target
      description: Target browser window when item is clicked.
      placeholder: 'Select...'
      default: _blank
      options:
          _parent: Self
          _blank: New Window

 

 

l’utilisation de Selectize plusieurs fois dans une seule page peut affecter les performances. Si vous êtes dans une situation où vous avez besoin d'utiliser ce type d'entrée à plusieurs reprises dans un petit espace, vous pourriez essayer select.select à la place. Cela a à peu près la même capacité avec moins de coûts de performance. Une bonne règle de base est que si vous n'avez pas besoin de la fonction de recherche, vous devez utiliser select.select.

Vous remarquerez les paramètres options énumérés ici. Dans ce cas, les valeurs de _parent et _blank sont utilisés avec les balises Self et New Window. L’utilisateur verra les balises dans l’administrateur de Gantry. Choisir l'un ou l'autre définit la valeur du champ à la valeur associée de l'option.

selectize

Comme vous pouvez le voir, l'expérience utilisateur dans l'administrateur Gantry est plus naturelle et plus facile pour l'utilisateur. Au lieu de saisir la fenêtre cible pour un lien manuellement, ils choisissent simplement entre ces deux options prédéfinies, qui nourrissent le fichier Twig de la particule pendant le rendu de page.

L’utilisation du type de champ select.date est très similaire. La différence ici est que vous donnez à quelqu'un l'option dans la façon dont les dates s'affichent. Dans l'exemple ci-dessous, nous avons mis en place une variété d'options différentes.

 

date.formats:
      type: select.date
      label: Target
      description: Select preferred date format.
      default: l, F d, Y
      placeholder: 'Select...'
      selectize:
        allowEmptyOption: true
      options:
        '': None
        'l, F d, Y': Date1
        'F d': Date2
        'd M': Date3
        'D, M d, Y': Date4
        'D, M d, y': Date5
        'l': Date6
        'l j F Y': Date7

 

 

Vous trouverez ci-dessous comment ces paramètres YAML apparaissent dans l’administrateur Gantry5.

date

Gantry Alertes, Notes et Styling

A côté des entrées HTML et Gantry, il y en a beaucoup d'autres. Ces entrées peuvent être utilisées pour alerter les utilisateurs ou simplement ajouter un peu de style à l'admin Gantry. Avec les notes, vous pouvez créer des sous-sections et ajouter d'autres informations directement disponibles par l'utilisateur. Les types suivants sont inclus :

  • seperator.note

title:
      type: separator.note
      class: alert alert-info
      content: '<h1>Your HTML GOES HERE</h1><p>Write what you wan

 

Modifier la classe de seperator.note par une classe qui correspond à votre template.
Les classes standard sont:

 

     class: alert alert-success
      class: alert alert-info
      class: alert alert-warning
      class: alert alert-danger    

 

 

Il y a beaucoup de différentes options à votre disposition. Comme vous pouvez le constater d'après ce petit guide, Les particules sont un élément puissant de la bonne marche de Gantry, et peuvent utiliser plusieurs fonctionnalités pour faciliter le vie de l’utilisateur.

Onglets de réglages des particules

Cette fonctionnalité est uniquement disponible dans gantry 5.3.2 et ultérieur.

tabs example

Si vous avez une particule qui a beaucoup de paramètres de configuration en frontend, vous pouvez (dans Gantry 5.3.2+) choisir de créer des onglets au sein du back-end de la particule pour séparer les options afin de faciliter la navigation et la configuration.

Pour ce faire, vous allez créer un container dans le fichier YAML de la particule pour y encapsuler des données par onglets. Voici un exemple d’un fichier YAML avec trois onglets simples :

 

name: My Awesome Particle
description: Just makes everything look awesome
type: particle
icon: fa-table

form:
  fields:
    enabled:
      type: input.checkbox
      label: Enabled
      description: Globally enable this particle
      default: true

    tabs:
      type: container.tabs
      fields:
        tab_display:
          label: Display
          fields:
            inside:
              type: input.text
              label: Inside Tab 1
              description: This field is inside Tab 1

        tab_readmore:
          label: Read More
          fields:
            ...

        tab_misc:
          label: Misc
          fields:
            ...

    outside:
      type: input.text
      label: Outside After
      description: This field is outside and after the tabs

 

 

Vous remarquerez ici l’utilisation de container.tabs pour mettre en place le conteneur qui encapsule les trois onglets. À l’intérieur de ces onglets, vous pouvez placer n’importe quel champs que vous placeriez normalement dans l’admin de votre particule. Les champs que vous souhaitez voir toujours rester disponible, quel que soit l'onglet sélectionné, peuvent l’être à l'extérieur des onglets contenant.

Comme les onglets sont enveloppés dans un conteneur, ils peuvent être placé sn'importe où dans l'YAML, cela signifie que vous pouvez avoir des champs avant et après.

Les label des onglets définissent le titre de l'onglet en frontend. Il n'y a pas d'exigence sur le nommage de l'onglet dans l'YAML.

Lors de l'utilisation de champs dans des onglets twig, vous pouvez y accéder normalement. Il n'y a pas du tout besoin de faire référence à l’onglet. Par exemple, si vous vouliez imprimer la sortie du champ appelé inside dans l’exemple ci-dessus, vous appelleriez juste {{ particle.inside }}. Comme tabs est un conteneur, vous n'avez pas besoin de référencer l'ensemble de la structure, comme {{ particle.tabs.tab_display.inside }} (<- wrong).

Votre nom pour les onglets peuvent également être n'importe quoi. Nous avons utilisé tab_readmore et tab_display à titre d'exemples. Vos onglets pourraient être nommés _tab0 ou santaclause. Cela n’affecterait pas le fonctionnement du tout. Une bonne habitude serait de préfixer tabs et les noms d’onglet avec un underscore (_tab_display), de telle sorte que, à première vue, vous sauriez que vous pouvez ignorer ceux-ci.

Une collection est un champ dont la valeur finale est un tableau (array). Dans Gantry nous n'avons que 2 collections, list et keyvalue (Attributs de balises). Vous êtes tous très familier avec la liste, qui est communément utilisée et permet de créer les éléments d'entrée à la volée.

Lorsque vous enregistrez une collection, votre valeur est un tableau, et dans votre template Twig, il faut faire défiler ce tableau afin d’en extraire et d’avoir accès à chaque élément d’entrée individuelle. Voici comment une collection fonctionne et comment c’est destiné à être utilisé, mais c’est très différent d'un container.

Un containeur est juste une définition structurelle utilisée habituellement, pour la plupart en interne, pour représenter ce à quoi le champ doit ressembler. Gantry a toujours eu 1 container, nommé set, on n'a jamais vraiment bien utilisé, mais il est là.

Bien que la structure YAML du conteneur soit une liste imbriquée, vraiment l’action générale s’enchaine en permanence en interne du champ Twig, pour rendre effectivement dans l'admin de la même façon que vous voyez dans mon gif ci-dessus. Les champs existants à l'intérieur de chaque onglet, vont encore être sauvés comme s’ils étaient au niveau supérieur, ils ne sont pas vraiment imbriqués dans les onglets, d’un point de vue Formulaire.

 

Contact
Parlons social
Recevoir des nouvelles du site