La substitution de paramètres de particules

Les particules sont extrêmement souples. Vous pouvez accéder à leurs paramètres sur plusieurs niveaux et modifier leurs paramètres par défaut pour l’ensemble du site, un outline spécifique, ou même une instance dans le gestionnaire de mise en page ou le Menu Editor.

Les particules viennent chacun avec leur propre jeu de paramètres par défaut qui peuvent ( ou pas ) être configurés dans le fichier YAML de la particule. Ces valeurs par défaut sont ensuite héritées par le schéma de base dans le panneau des paramètres par défaut de la particule. A partir de là, vous pouvez modifier ces valeurs par défaut dans l'outline de Base, les Sous Outlines, et même dans le cas de la particules spécifique instance tel qu'elle apparaît dans le Gestionnaire de mise en page, Éditeur de menu, Module ou Widget.

Voici une présentation rapide des niveaux différents d’héritage d’une particule.

Niveau	Description
Fichier YAML de particule	Les valeurs par défaut attribuées dans ce fichier agissent comme les valeurs par défaut de niveau supérieur absolu pour la particule.Ces valeurs sont remplacées par les modifications apportées dans les outlines de base, sous Outlines.
Valeurs par défaut de particules de l'Outline de base	Les modifications apportées dans le panneau Particle Defaults dans le schéma de Base deviennent les valeurs globales par défaut pour le site.
Valeurs par défaut de particules de l'Outline	Le panneau Particle Defaults à ce niveau définit les valeurs par défaut pour la particule telle qu'elle existe dans ce schéma particulier, affectant seulement les outlines.
Valeur par défaut de particules individuelles dans le Gestionnaire de mise en page, éditeur de menu, le module ou un widget	Les modifications apportées à ce niveau sont les paramètres surchargés pour la particule dans cette seule instance ou tout ce qui est directement héritéedes instances.

 

En bref, l'héritage pour les paramètres de particules fonctionne comme ceci: Fichier YAML de particule > Valeurs par défaut de particules de l'Outline de base > Valeurs par défaut de particules de l'Outline > Instance individuelle et chaque étape héritant et / ou modifiant les réglages de la précédente.

Panneau Particle defaults de l' Outline de Base

Dans le Outline de Base, vous pouvez définir les paramètres par défaut pour n’importe quelle particule dans le panneau d'administration Particle Defaults. Les réglages placés ici deviennent les valeurs par défaut globales applicables à tous les outlines et instances de particules individuelles, sauf contrordre. Ceci est l'endroit où vous devriez placer vos paramètres les plus couramment utilisés pour une particule donnée.

Par exemple, si vous souhaitez que votre particule logo utilise la même source image sur toutes vos pages, sauf une ou deux, Vous devez définir cette image ici et remplacer en utilisant soit les Paramètres de contour appliquée à ces pages d'exception, ou dans les instances individuelles de particules dans le gestionnaire de mise en page.

Panneau Particle Defaults de l'Outline (autre que celui de base)

Dans les outlines qui ne sont pas définies comme la valeur par défaut, vous pouvez remarquer que le panneau d'administration Particle Defaults a grisés les Paramètres de particules pour la plupart (si ce n'est tous) de vos particules. En changeant un paramètre et / ou en sélectionnant la case à cocher sur le côté droit de la boîte de paramètres pour cette particule, vous pouvez remplacer les paramètres par défaut pour l'outline.

Maintenant, chaque particule placée dans le gestionnaire de mise en page pour ce profil particulier aura ces nouveaux paramètres par défaut.

Paramètres individuels de particules dans le Gestionnaire de mise en page

Lorsque vous placez une particule dans le gestionnaire de mise en page d'un outline, vous créez une instance. Cette instance permet de régler les paramètres de particules pour cette particule spécifique, qui ne touchent pas d'autres instance de cette particule. Si, par exemple, vous voulez voir le logo apparaître différemment dans une instance, vous devez modifier ses paramètres ici.

Dans l'exemple ci-dessus, nous avons changé la valeur Start Year pour la particule en utilisant son panneau de configuration dans le Gestionnaire de mise en page. La case cochée à la droite du champ indique qu'il est remplacé alors que les autres champs restent gris et sans contrôle. Ces paramètres sont hérités des niveaux de défaut plus élevés.

Vous pouvez accéder à ces paramètres spécifiques à l'instance en sélectionnant la roue dentée sur le côté droit de la particule dans le gestionnaire de configuration.

La substitution de fichiers Source des particules

Parfois, les modifications que vous souhaitez apporter à une particule nécessitent de modifier les fichiers sources qui composent le fichier. La source pour toutes les particules inclut des fichiers Twig et YAML.

Dans cet exemple, nous allons ajouter un lien à la particule Copyright qui va directement à la page d’accueil du site depuis le nom du détenteur du copyright. C’est juste un petit exemple de ce que vous pouvez modifier.

Dans l'image ci-dessus, vous verrez la Particule Copyright sur le côté gauche. Il n’y a aucun lien ou quoi que ce soit inclus dans le noyau des particules. Si vous voulez que le nom du titulaire du droit d’auteur devienne un lien vers son site Web, vous pouvez ajouter quelques changements simples aux fichiers source de la particule.

La première chose que vous devez faire est de copier les fichiers copyright.html.twig et copyright.yaml situés dans ROOT/media/gantry5/engines/nucleus/particles/ et coller les copies dans TEMPLATE_DIR/custom/particles. Si le répertoire particles n'existe pas encore dans votre dossier custom, vous devrez le créer.

La particule que vous recherchez peut se trouver dans un endroit différent. Par exemple, une particule spécifique d’un template qui est venu avec un template et n’est pas directement lié à gantry se trouve dans /THEME_DIR/particles.

En dupliquant les fichiers et en plaçant les copies dans le dossier custom, vous protégez les modifications des mises à jour. Cela garantit que vos modifications ne sont pas effacés lorsque vous mettez à jour soit le framework de Gantry soit le thème.

Ce que vous faites sur les fichiers de particule en double dans votre dossier TEMPLATE_DIR/custom/particles surchargera ce qui apparaît dans le fichier d'origine.

Parce que nous ajoutons un nouveau champ à la particule Copyright, nous devrons modifier le fichier YAML. Voici ce à quoi le fichier copyright.yaml YAML ressemble avant les changements.

name: Copyright
description: Display copyright information.
type: particle

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

    date.start:
      type: input.text
      label: Start Year
      description: Select the copyright start year.
      default: now

    date.end:
      type: input.text
      label: End Year
      description: Select the copyright end year.
      default: now

    owner:
      type: input.text
      label: Copyright owner
      description: Add copyright owner name.
 

Cela crée les champs qui apparaissent dans le panneau Settings de l'administrateur Gantry, ainsi que dans toutes les instances dans le Gestionnaire de layout où la particule Copyright a été placée. Ces paramètres sont alors liés au fichier Twig de la particule. Dans ce cas, nous ajoutons un champ de lien afin que les utilisateurs puissent ajouter un lien à la particule.

Nous pouvons créer le champ lien en ajoutant ce qui suit à la fin du fichier YAML.

    site:
      type: input.url
      label: Copyright Link
      description: Add the link to the copyright owner's site.

 

Maintenant, vous remarquerez que le nouveau champ apparaît dans le backend.

Le fichier copyright.html.twig doit également être changé, afin d'intégrer les nouvelles données et de créer le lien. Ci-dessous le contenu du fichier d'origine Twig:

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

{% set start_date = particle.date.start|trim in ['now', ''] ? 'now'|date('Y') : particle.date.start|e %}
{% set end_date = particle.date.end|trim in ['now', ''] ? 'now'|date('Y') : particle.date.end|e %}

{% block particle %}
Copyright ©
{% if (start_date != end_date) %}{{ start_date|e }} - {% endif %}
{{ end_date|e }}
{{ particle.owner|e }}
{% endblock %}

 

La ligne {{ particle.owner|e }} doit être modifiée pour ajouter le lien sur la base de la variable assignée via le fichier YAML. Dans cet exemple, nous allons le remplacer par ces trois lignes:

{% if particle.site %}<a href="/{{ particle.site | default(gantry_base) }}">{% endif %}
{{ particle.owner }}
{% if particle.site %}</a>{% endif %}

 

Maintenant, dans le frontend du site, la particule apparaît avec un lien sur le nom du propriétaire du droit d'auteur.
C’est juste un petit exemple de ce que vous pouvez faire pour étendre les fonctionnalités d’une particule à l’aide de Twig et YAML.