Documentazione Gantry 5 per Joomla!

Concetti fondamentali per iniziare con un template framework di nuova generazione.

Tutti i template (temi) Gantry 5 sono forniti con particelle che svolgono diverse funzionalià. Ma non è detto che un tema Gantry deve avere le stesse particelle di un'altro. A volte si potrebbe desiderare di includere in un template, una particella presente in un altro template che svolge una certa funzionalità. Questo tutorial mostra il modo sicuro per copiare le particelle tra un template e l'altro, e che non saranno sovrascritte dagli aggiornamenti del template.


Per lo scopo di questo tutorial, il template da cui vogliamo copiare la particella lo chiamiamo "tema origine" e il template dove si desidera copiare è il "tema destinatario".

AVVISI
1. Se si copia una particella da un tema all'altro, e successivamente si verifica un bug in quella particella, il problema verrà risolto solo nel tema origine (tramite una release di aggiornamento del tema). È quindi vostra responsabilità di controllare gli aggiornamenti del tema origine e vedere se la particella è stata cambiata, il che significa che sarebbe poi necessario aggiornare la particella anche nel tema destinatario.
2. Può darsi che il tema origine abbia uno stile CSS speciale per una pagina/luogo in cui viene utilizzata la particella. Questo non può essere replicato copiando la particella.
3. Non si tratta di cambiare alcuna funzionalità: si sta copiando la particella "così com'è".

Di che cosa sono fatte le particelle

Una particella è costituita da queste cose:
- Un file YAML (testo semplice) che indica a Gantry 5 quali campi vengono utilizzati dalla particella.
- Un file TWIG (testo semplice) che utilizza questi campi per renderizzare il risultato sulla pagina.
- Un file SCSS (testo semplice) che contiene il file SASS/CSS per creare lo stile della particella visualizzata nella pagina.
- Facoltativamente, una particella può contenere uno o più file JS (testo semplice) con codice JavaScript/jQuery per svolgere certe funzioni nella particella.

* Tutte le particelle specifiche per il tema si trovano in: THEMENAME/particles
* Tutti i file SCSS delle particelle risiedono in: THEMENAME/scss/THEMENAME/particles
* Tutti i file JS risiedono in: THEMENAME/js

Termini utilizzati
THEMENAME è il nome del template (esempio: hydrogen, helium);
PARTICLENAME è il nome della particella (esempio: slideshow, logo, cookie consent, accordion, google maps);

Copiare la particella

È molto importante fare la copia in modo che tutti i successivi aggiornamenti del tema non sovrascrivano ciò che avete fatto. Le fasi riportate di seguito assicurano che sia così.

Ecco i passaggi per fare la copia dal tema origine al tema destinatario. Fatte attenzione che si copia solo il file del tema origine, non la cartella(e) in cui risiede.
1. Copiare THEMENAME/particles/PARTICLENAME.html.twig in THEMENAME/custom/particles
NOTA: Se non esiste la cartella "custom" la dovete creare a mano.
2. Copiare THEMENAME/particles/PARTICLENAME.yaml in THEMENAME/custom/particles
3. Copiare THEMENAME/scss/THEMENAME/_PARTICLENAME.scss in THEMENAME/custom/scss (annotare il trattino basso all'inizio del nome del file)
4. Per qualsiasi file JS che si sa di essere richiesto dalla particella, copiare THEMENAME/js/JSFILENAME.js in THEMENAME/custom/js
5. Se non si dispone già di un file. scss personalizzato, è necessario crearne uno (file di testo semplice). Il file scss personalizzato deve essere inserito in THEMENAME/custom/scss. Il tuo file SCSS personalizzato deve avere questa dichiarazione come prima riga:{code lang:css showtitle:false}@import "dependencies";{/code}La successiva cosa da fare è assicurarsi che anche il file SCSS della particella sia caricato. Lo facciamo inserendolo nel nostro file SCSS personalizzato aggiungento questa riga:{code lang:css showtitle:false}@import "PARTICLENAME";{/code}NOTA: Non è necessario prefissare il PARTICLENAME con un trattino basso.

6. Se la particella utilizza un file JS separato, allora potrebbe essere necessario caricare quel file JS (verificare se viene caricato in PARTICLENAME.html.twig. In caso affermativo, non è necessario caricarlo). Lo si fa nel tema destinatario nel Base Outline nella scheda Page Settings.

inserimento custom javascript page settings

7. La particella che si sta copiando può avere anche una dipendenza da una libreria JS (ad esempio jQuery, Mootools, ecc.) quindi potrebbe essere necessario assicurarsi che anche la libreria corretta sia caricata. Questo viene fatto sempre nella scheda Page Settings (Impostazioni pagina) del Base Outline trascinando l'atomo JavaScript Frameworks nella sezione Atoms (se non ne avete già uno) e quindi modificando le impostazioni dell' atomo per passare da un framework all'altro.

inserimento javascript atom

8. Andare alla scheda Styles del Base Outline e fare clic su Recompile CSS.

Questo è tutto!
Ora dovresti essere in grado di utilizzare la particella del tema origine nel tuo nuovo tema destinatario.