Per creare un template Joomla! con il framework Gantry 5 abbiamo bisogno inanzitutto di fare un'Introduzione alle particelle Gantry per capire il concetto e ulteriormente creare soltanto le particelle che ci servono. Vediamo adesso in questa guida passo passo di cosa abbiamo bisogno e come procedere.

La creazione di una nuova Particella in Gantry 5 è un processo abbastanza semplice e per realizzarlo abbiamo bisogno di un semplice editor di testo per la creazione di due file, un file YAML e un file Twig. Il mio consiglio è di utilizzare Blocco note oppure il più professionale Notepad++ che permette anche una formattazione del codice in base al linguaggio utilizzato.

In questa guida creeremo una semplice particella da inserire ulteriormente nel nostro layout. Questa particella è costituita da tre elementi principali: Un'immagine, un titolo e una descrizione.

Creazione del file YAML

Durante il processo di creazione delle particelle, è più facile iniziare con la creazione del file YAML in quanto questo funge da modello per la particella. Il file Twig utilizza questo file YAML per prendere le informazioni, le impostazioni, e scoprire quali campi vengono utilizzati per le variabili.

Inanzitutto si deve creare una cartella particles dentro la cartella custom del template g5_hydrogen per avere una struttura delle cartelle del genere: g5_hydrogen/custom/particles. Adesso con l'editor di testo creiamo un file chiamato esempio_particella.yaml. Ovvio che potete chiamarlo anche pippo, però è importante che viene chiamato con un nome significativo per la funzionalità che questa particella dovrebbe svolgere. Ad esempio, se creiamo una particella per slideshow la chiamiamo slideshow.yaml , per una particella che deve mostrare la mappa di google la chiamiamo googlemaps.yaml e così via.

Adesso inseriamo il seguente codice nel file YAML :
{code lang:yaml showtitle:false}name: Esempio
description: Mostra Titolo, Immagine e Testo lato front end.
type: particle

form:
  fields:
    enabled:
      type: input.checkbox
      label: Enabled
      description: Abilita particella.
      default: true

    title:
      type: input.text
      label: Titolo
      description: Inserisci un titolo.   

    image:
      type: input.imagepicker
      label: Immagine
      description: Seleziona un immagine.

    description:
      type: textarea.textarea
      label: Text / HTML
      description: Crea o modifica la descrizione.

    css.class:
      type: input.text
      label: Classe CSS
      description: Nome classe CSS per questa particella.{/code}
Il contenuto del file YAML è costituito da due sezioni principali.
Nella prima sezione, che contiene le prime 3 righe, vengono configurati il nome, la descrizione e il tipo di particella.
Il nome (name) è quello che appare in Gantry Admin come il titolo della particella. Il tipo (type) particle significa che Gantry utilizza questo file YAML per creare una particella.

Adesso andiamo in Base Outline > Particle Defaults per vedere l'anteprima della particella e riempiamo i campi con i dati desiderati.
La seconda sezione invece fornisce il form con i campi che appaiono nel'amministrazione, come impostazioni predefinite. Questi campi sono accessibili e configurabili molto facilmente dai utenti senza scrivere una riga di codice o di saper programmare, essattamente come si compila un semplice form di contatto. Questi campi danno la possibilità di fare molte cose come ad esempio inserire del testo personalizzato, scrivere dei titoli e abilitare o disabilitare la particella.

Il primo blocco dei campi (enabled:) è necessario, e trasmette a Gantry di mettere un interruttore (switch) che consente all'utente di abilitare/disabilitare la particella. Il resto dei campi quali title, image, description, e css.class forniscono agli amministratori del sito la possibilità di configurare la particella senza dover modificare alcun file.

Ecco qui una tabella con le impostazioni utilizzate in questo esempio e come queste impostazioni influiscono.

Creazione del file Twig

Il prossimo file necessario da creare e un file twig e dovrebbe essere creato nella stessa directory del file YAML. Si consiglia di assegnarli lo stesso nome del file YAML, ma nel formato nome.html.twig.
La parte finale del nome del file html.twig dice a Gantry che questo è un file Twig, che in pratica è il template del file. Questo controlla come vengono interpretate le particelle, specifica il codice HTML, e determina come vengono utilizzate le variabili definite nel file YAML.
Ecco quindi il contenuto del file esempio_particella.html.twig :
{code lang:twig showtitle:false}{% extends '@nucleus/partials/particle.html.twig' %}

{% block particle %}
<div class="esempio_particella {{ particle.css.class }}">
            <div align="center">
              <img src="/{{ url(particle.image) }}" alt="image">
              <h2>{{ particle.title }}</h2>
              <p>{{ particle.description }}</p>
            </div>
        </div>
{% endblock %}{/code}
Questo è un esempio molto semplice di un file Twig, contenente tre parti.

La prima parte ({% extends '@nucleus/partials/particle.html.twig' %}) definisce il file Twig come particella. Questa riga è un elemento essenziale e dovrebbe essere presente in tutti i file Twig delle particelle.
La seconda parte è un contenitore o un blocco di codice che dovrebbe iniziare con {% block particle %} e finire con {% endblock %}. Anche queste 2 righe sono essenziali per il funzionamento della particella.
La terza parte è il vero cuore della particella. Questo è il corpo, utilizzato per determinare come una particella guarderà e utilizzerà le informazioni presenti nel file YAML.

Nel nostro esempio, abbiamo impostato la classe div a esempio_particella. Questa classe dice a Gantry che il file twig sta lavorando con le informazioni prese dal file esempio_particella.yaml.

Il codice inserito tra le parentesi graffe, come ad esempio {{particle.title|e}} estraie le informazioni dai campi impostati nel file YAML e le inserisce nel file Twig per interpretarle sul front-end.

Dopo aver creato questi file, andiamo in Layout Manager del Outline desiderato e la trasciniamo in una posizione.
Con Apply & Save il gioco è fatto !
Adesso possiamo vedere il risultato sul front-end e magari facciamo un pensiero di visitare il Castello di Dracula :)

Ottenere dati di configurazione Gantry con l'utilizzo di Twig

Uno dei componenti chiave di Gantry è la possibilità di impostare facilmente dei campi e delle opzioni tramite i file YAML che possono essere utilizzati successivamente dagli utenti in Gantry Admin per configurare il sito. Il file YAML crea il campo (oppure l'opzione), l'utente configura tale opzione, definendo così la variabile che si può utilizzare quando viene interpretata la pagina attraverso il file Twig.
Ottenere una variabile di configurazione è abbastanza facile. Per estrarre questo dato si deve utilizzare il commando gantry.config.get(). Ad esempio possiamo utilizzare il codice {{ gantry.config.get('styles.base.background') }} per ottenere il colore dello sfondo predefinito del template.

Nel esempio precedente abbiamo ottenuto le opzioni di configurazione della particella attraverso il commando {{particle.header{}, che fornisce il valore del campo header. Quindi il commando {{ particle.title }} prende il titolo (il valore del campo title) della particella e lo formatta utilizzando un'intestazione h2. Semplice no ?

Supponiamo ora che vogliamo ottenere una variabile impostata in un'altra particella. Ad esempio, la particella Branding. Questa informazione la otteniamo utilizzando il commando {{gantry.config.get('particles.branding.css.class')}} che informa Gantry di utilizzare il valore impostato nel campo CSS Class della particella "Branding". In questo modo si utilizzerà il valore predefinito, piuttosto che un valore impostato in una singola istanza della particella in Layout Manager o il Menu Editor.

Personalizzazione di una particella esistente

Se si desidera fare override di una Particella esistente e apportare delle modifiche, è possibile farlo copiando i file necessari nella cartella template_dir/custom e modificarli ulteriormente, procedura simile come si fa con override in joomla. Così funziona l'override di una particella del core di Gantry, della piattaforma o del template.

Ecco una tabella per aiutarvi a capire dove posizionare i file YAML e i file Twig duplicati.