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.