Tutoriels gantry5 niveau avancé

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.

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.

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.

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

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.

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.

Comme vous pouvez le voir, l'expérience utilisateur dans l'administrateur Gantry est plus naturelle et...