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