Vediamo in questa guida gantry come fare l'override di una particella per aggiungere delle funzionalità, ma prima di tutto tengo a specificare che le impostazioni delle particelle possono essere configurate sui livelli diversi. Partiamo con una descrizione di questi livelli.

Pannello Settings Base Outline

All'interno del'Outline predefinito è possibile configurare le impostazioni globali per qualsiasi particella dal Pannello Settings. Queste impostazioni diventano dei valori predefiniti globali e si applicano a tutti i outline e a tutte le istanze delle particelle, tranne in quei casi dove è stato fatto un override.

Pannello Settings Non-Base Outline

All'interno degli outline che non sono predefiniti, si nota che i campi delle impostazioni sono oscurati. Selezionando la casella checkbox accanto al campo desiderato si abilita la posibilità di poter editare il contenuto di quel campo inserendo così un valore personalizzato.
Adesso, tutte le particelle presenti in Layout Manager avranno questo nuovo valore predefinito.

Impostazioni individuali delle particelle in Layout Manager

In Layout Manager, quando si trascina una determinata particella sul layout si crea un'istanza della particella stessa. Questa istanza permette di modificare le impostazioni della particella, modifiche che non influiscono sulle altre istanze di quella determinata particella.

Override delle impostazioni di una particella

Possono essere casi in cui le impostazioni di una determinata particella non sono sufficienti per le nostre esigenze e vogliamo modificare il codice sorgente. Il codice sorgente per tutte le particelle si trova in un file Twig e in un file YAML.
Prendiamo come esempio pratico la particella Copyright.

In questa anteprima abbiamo la particella Copyright sul lato sinistro. Si nota che non esiste un link per il testo personalizzato Titolare Copyright. Se vogliamo far si che quel testo diventa un collegamento ipertestuale allora dobbiamo editare alcuni file effettuando in questo modo un override.

Per prima cosa da fare è di copiare i file copyright.html.twig e copyright.yaml che si trovano in ROOT/media/gantry5/engines/nucleus/particles/ e di incollarli in TEMPLATE_DIR/custom/particles.
Se all'interno della cartella custom non esiste la cartella particles, in questo caso bisogna crearla.

Ecco il file copyright.yaml prima delle modifiche:
{code lang:yaml showtitle:false}

name: Copyright
description: Display copyright information.
type: particle
icon: fa-copyright

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.

{/code}

Questi sono i campi che compaiono in pannello di configurazione Gantry e in tutte le istanze in Layout Manager dove viene inserita la particella Copyright.
Queste impostazioni vengono collegate con il file Twig della particella.
In questo caso particolare vogliamo inserire un campo aggiuntivo tipo collegamento ipertestuale e collegarlo al testo inserito nel campo Copyright owner.

Dunque, aggiungiamo il seguente codice alla fine del file YAML.
{code lang:yaml showtitle:false}site:
      type: input.url
      label: Copyright Link
      description: Add the link to the copyright owner's site.{/code}

Come si vede, il codice inserito nel file YAML fa comparire un nuovo campo chiamato Copyright Link in cui inseriamo il nostro collegamento.
Però, per far funzionare questo bisogna editare anche il file copyright.html.twig.
Ecco il file originale prima delle modifiche.
{code lang:twig showtitle:false}{% 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|raw }}
{% endblock %}{/code}
Dobbiamo modificare adesso la riga {{ particle.owner|raw }} per aggiungere il link in base alla variabile assegnata nel file YAML. Quindi, la riga in questione verrà sostituita con il seguente codice
{code lang:twig showtitle:false}{% if particle.site %}<a href="/{{ particle.site | default(gantry_base) }}">{% endif %}
{{ particle.owner }}
{% if particle.site %}{% endif %}{/code}
Adesso, in frontend, il testo Titolare Copyright compare come collegamento all'indirizzo inserito nel campo Copyright Link.