Tutoriel gantry 5 - Créer une nouvelle particule (Particle)

Particules, Particules .... Le fer de lance du nouveau Framework Gantry 5. Les particules peuvent faire toutes sortes de choses comme vous permettre d'insérer un petit bloc de code HTML jusqu'à présenter un grand bloc d'informations détaillées, avec des images, des liens, des textes, et plus encore sur votre site Web.

Par défaut le template Hydrogen nous propose 10 particules.

Seul la particule "Sample content" est gérée dans le répertoire particlessous forme de 2 fichiers : sample.html.twiget sample.yaml.

Les templates payants RocketTheme possèdent un grand nombre de particules dédiées.

Nous allons, dans un premier temps, voir comment créer une nouvelle particule simple composée de trois parties principales : Le titre, image et description et bientôt une particule un peu plus complexe pour une galerie de photo sous forme de grille.

Vous aurez juste besoin d'un éditeur de texte pour créer nos deux fichiers (.twig et .yaml) pour chaque nouvelle particule sans oublier notre feuille de style spécifique.

Nous faisons donc une customisation. Comme nous l'avons vu dans nos tutoriels précédent, nous devons créer nos nouvelles particules dans le répertoire custom

hydrogen
├── custom
│ └── particules 
│   └── exemple.html.twig
│   └── exrmple.yalm

Création d'une particule simple : titre, image et description

Comme exemple, nous allons donc créer cette particules composée de trois parties principales. Le titre, l'image et la description. Les particules peuvent être simples mais aussi complexes selon votre besoin spécifique.

Création du fichier YAML

un fichier YAML est une sérialisation de données, lisible par un néophyte , facilitant donc la configuration des plans pour les options de votre particule .

Lors de la création de votre particules, il peut être plus facile de commencer avec ce fichier YAML que cela agit comme le plan directeur pour la particule. Le fichier TWIG (rendu html du fichier YALM) utilisera donc son fichier compagnon YAML pour extraire les informations nécessaires à la particule (réglages, champs, variables).

Rappel de l'emplacement des 2 fichiers dans votre site.

Voici le corps du fichier YAML pour notre exemple de particules:

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.

Le fichier YAML est constitué de deux parties principales, la tête du fichier (header) et les formes / champs de la particule:

La tête du fichier comporte le nom, la description et le type.

• Le Nom est ce qui apparaît dans l'administration gantry 5 au niveau du titre de la particule dans les onglets "Setting"et "Layout manager".
• Le type = particules dit à Gantry que ce fichier YAML est utilisé pour créer une particule.

Un aperçu de votre fichier YALM dans votre administration Gantry 5.

La deuxième partie présente les formes / champs qui apparaissent dans l'administration, ainsi que les paramètres par défaut de vos particules. Ils leur donnent la possibilité d'inclure dans votre paricule du texte personnalisé, un titres ou une image.

Le premier bloc de champ enabledest nécessaire. Il indique à Gantry de mettre un interrupteur sur le backend ce qui permet d'activer ou de désactiver la particule.

Les autres champs, title, image, description, et css.classsont des champs personnalisés servant à configurer la particule sans avoir à modifier les fichiers manuellement.

Regardons les paramètres utilisés dans l'exemple ci-dessus et comment ils affectent le fichier:

Un article complet sera dédié aux Types pour les fichiers YAML

Création du fichier TWIG

Le prochain fichier que vous devrez créer se placera dans le même répertoire que le fichier YAML. Nous vous conseillons de le nommer de la même manière que le fichier YAML, avec le format (nom.html.twig). Mettre à fin du nom du fichier html.twigdit à Gantry que c'est un fichier Twig : c'est basiquement le template de la particule. Il contrôle comment les particules sont rendus, indique le HTML, les class et détermine la façon dont les variables définies dans le YAML sont utilisés.

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="{{ particle.image }}" alt="image">
              <h2>{{ particle.header }}</h2>
              <p>{{ particle.description }}</p>
            </div>
        </div>
{% endblock %}

Ceci est un exemple très simple d'un fichier TWIG, contenant trois parties.

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

La deuxième partie est l'encapsuleur de bloc "Bloc wrapper". {% block particle %}et {% endblock %}entourent le bloc qui contient la particule. Ceci est également un composant requis pour votre particules.

La troisième partie est le contenu interne de la particule. Ceci est le corps utilisée pour déterminer comment une particule sera vu. Elle utilise l'information définie dans le YAML. Dans notre exemple, nous avons mis la div class à example_particle. Cette class indique que ce fichier Gantry TWIG travaille avec les informations de son fichier compagnon custom_html.yaml.

Le champ de classe CSS utilisée dans cet exemple n'est pas nécessaire. Une CSS peut être appliquée au niveau bloc dans l'administrateur Gantry 5. L'ajout d'un champ de classe à ce niveau vous permet d'attribuer une classe CSS à une div spécifique au sein de la particule.

Les données qui sont placés entre accolades comme {{particle.header | e}}permettent l'extraction des informations à partir des champs définis dans le fichier YAML et de les insérer dans le fichier TWIG pour le rendu sur le web.

L'| 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 Settings (paramètres) et le Layout Manager (Gestionnaire de mise en page) en administration Gantry 5.

Fichier TWIG : Tirer partie de l'utilisation des données de configuration Gantry (non présente dans la particule)

Un des éléments clés du Gantry 5 est la possibilité de mettre en place facilement des champs et des options à l'aide des fichiers YAML qui peuvent ensuite être utilisés et configurés par les utilisateurs dans l'administration Gantry 5.

Le fichier YAML crée le champ (ou l'option), l'utilisateur configure cette option, définissant ainsi la variable utilisée lors de rendu de page à travers votre fichier TWIG.

Configurer une variable est assez facile. Vous avez juste besoin d'utiliser le code gantry.config.get()pour aller chercher ces données.

Comme exemple on peut citer {{ gantry.config.get('styles.base.background') }}pour utiliser la couleur de base de votre fond actuellement réglé par le thème.

Dans notre exemple simple, nous utilisons l'option de configuration de la particule au travers des commandes comme {{ particle.header }}qui va chercher la valeur définie pour le headerpour cette particule spécifique.

Supposons que vous vouliez utiliser la variable qui est défini sur une autre particule. Par exemple, la particule "Branding". Vous pouvez aller chercher ces informations en utilisant {{ gantry.config.get('particles.branding.css.class') }}qui demande à Gantry d'utiliser la valeur de la class CSS de classe de la particule "Branding". Ceci vous permettra de saisir la valeur par défaut, plutôt que de définir une valeur définie individuellement pour chaque particule.

Personnalisation d'une particule existante

Si vous souhaitez remplacer une particule existante et apporter des modifications personnalisées à la source de cette particule, vous pouvez le faire en la copiant dans le répertoire TEMPLATE_DIR/custom et ainsi modifier le(les) fichier(s) dupliqués. Ces changements vont remplacer le rendu de la particules existante du noyau de Gantry.

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

Fichier scss par particle

Comme vous l'avez vu, on peut determiner des styles spécifiques par particule, soit au niveau des variables, soit directement dans le fichier TWIG. Il est judicieux de créé un fichier scss par particule avec ses styles.

Le fichier nommé maparticule.scss ou l'on trouve nos feuilles de style sera appelé à partir du fichier custom.scss avec la commande@import 'maparticule';