Guida

La struttura dei contenuti

            
          ├─ assets         Contiene tutti i file statici, gli scess ed i file javascript.
             ├─ img         * Immagini di base utilizzate nel tema.
             ├─ js          * Tutti i javascript che non vengono inglobati tramite webpack ed il file app.js di configurazione.
             ├─ scss        * File scss, divisi in cartelle per funzionalità, da modificare per editare lo stile del tema.
             └─ webfonts    * Fonts usati nel tema.
          ├─ data       
          └─ layout         Contiene i file che possono essere usati come base per le pagine.
             ├─ default     * Template applicato di default a tutte le pagine che vengono create nella cartella pages.
             ├─ styleguide  * Template applicato alle pagine usate come styleguide.
          └─ pages          Contiene tutte le pagine del tema e quelle della styleguide.
             ├─ index       * Pagina di apertura del tema, da aggiornare manualmente, per visualizzare la lista contenuti del tema.
             ├─ styleguide  * Tutte le pagine della Styleguide.
             ├─ layout      * Tutte le pagine esempio
          └─ partials       Contiene tutti gli snippet html da includere nelle pagine.
              
            

La cartella src / contiene tutti i file sorgente da editare e che produrranno, una volta compilato il bundle, una cartella dist / con il tema pronto per la produzione.

Per avviare la compilazione del tema, dopo l'installazione, basta eseguire il comando:

                
          yarn start
                
              

Durante lo sviluppo, Gulp aggiorna continuamente la cartella dist / con nuove versioni dei file, visibili all'indirizzo: http://localhost:8000/

Per compilare una build di produzione, basta eseguire il comando:

                  
          yarn build
                  
                

Le caratteristiche del Tema

Questo tema utilizza il sistema di compilazione Gulp per automatizzare il processo di compilazione di Sass, elaborazione di JavaScript, copia di file e altro.

In particolare:

• Copia delle risorse

  Gulp copierà qualsiasi cosa sia contenuta nella cartella src/assets così com'è nella cartella assets del progetto finale. I file Sass, quelli JavaScript e le immagini non fanno parte di questo processo di copia, in quanto soggetti alla compilazione.

• Compilazione delle Pagine

  La cartella src/ contiene tre cartelle usate per la generazione delle pagine HTML: pages/, layouts/, e partials/. Il compilatore chiamato Panini viene utilizzato per elaborare le varie pagine del progetto, inserendole in un modello di default e inserendo eventuali snippet di codice HTML. Tutto ciò viene reso possibile dal linguaggio di templating Handlebars.
  Per approfondire, Panini ha una sua pagina dedicata.

• Compilazione dei file Sass

  I file Scss vengono compilati in CSS mediante Libsass (via node-sass). Il file src/assets/scss/app.scss importa tutti i moduli node installati, come ad esempio Foundation and Motion UI. Tutti i file Sass aggiunti dovranno essere richiamati in questo file, per essere compilati.

  Il CSS prodotto è un normale CSS. Viene anche creata una mappa sorgente, che può essere letta dagli strumenti per sviluppatori (come ad esempio Chrome Web Inspector).

  Quando si compila per la produzione, il CSS viene anche compresso con clean-css, e minimizzato con UnCSS. UnCSS esegue la scansione dell'HTML delle pagine e rimuove le classi non utilizzate.

• Compilazione del JavaScript

  I file JavaScript vengono compilati tramite Babel (con il plugin es2015).

  Il file principale è in src/assets/js/app.js, e importa Foundation, jQuery, whatInput, Highlight, lo script custom Toc e FontAwesome. Qualsiasi altro javascript si voglia includere nel pacchetto va richiamato in questo file, dopo aver inserito il file nella cartella js, oppure installato il modulo con node o yarn.

  Nella compilazione viene creata una mappa che esegue la mappatura ai file originali. Per impostazione predefinita, il file app.js in bundle non è compresso. Durante la creazione per la produzione, il file viene eseguito tramite UglifyJS per la compressione. L'intero processo di raggruppamento è gestito da Webpack, che gestisce tutte le risorse e le dipendenze e le compila in un unico file.

  Se non hai dimestichezza con import o module bundling, puoi approfondire qui:

  • What are ES6 imports
  • Beginner’s guide to webpack
  • Beginner’s guide to JavaScript Modules.

• Compressione delle immagini

  Di default tutte le immagini vengono copiate così come sono dalla cartella assets/img nella cartella dist. Durante la compilazione per la produzione, le immagini vengono eseguite tramite gulp-imagemin per la compressione. Il plugin supporta file JPEG, PNG, SVG e GIF.

• BrowserSync

  Il pacchetto tema crea un BrowserSync server, che si apre su http://localhost:8000. Da questo URL è possibile vedere tutte le pagine compilate. Mentre il server è in esecuzione, ogni volta che salvi un file, tutte le pagine aperte si aggiorneranno automaticamente, permettendoti di vedere le modifiche in tempo reale mentre lavori.

Approfondimento: SCSS

                  
          @import 'nome-del-modulo';
                  
                

Gestione dei Layouts

I layout attualmente creati sono due:

• default.html

  Questo layout si applica automaticamente a tutte le pagine create nella cartella pages /

• styleguide.html

  Questo layout serve per le pagine che andremo a creare nella cartella styleguide /. Per poter usare questo template è necessario aggiungere il codice:

                        
            ---
            layout: styleguide
            title: Nome della pagina che vogliamo creare
            ---
                        
                      

  all'inizio della nuova pagina della guida che creiamo.
  Con lo stesso metodo è possibile creare altri layout da associare a nuove tipologie di pagine, semplicemente creando un template nella cartella layouts nome-layout.html e richiamandone il titolo in testa alla pagina con questo markdown:

                        
            ---
            layout: nome-layout
            title: Nome della pagina che vogliamo creare
            ---
                        
                      

Inoltre, mentre nel layout default.html il contenuto della pagina viene sostituito all'interno del tag body, nel layout styleguide.html abbiamo due colonne preimpostate. Il markup che dovremo scrivere nelle pagine sarà solo quello relativo al contenuto della pagina stessa, in quanto la colonna di sinistra, con l'indice dei contenuti, viene generata automaticamente leggendo tutti gli h3 con un qualsiasi id inseriti nel contenuto della pagina.

Creazione delle Pagine

Qualsiasi file .html venga creato all'interno della cartella pages / verrà compilato come una pagina. In ogni pagina è necessario inserire solo il contenuto del tag body che vogliamo creare, perché il markup restante è preimpostato nel layout di default.

Le pagine nella cartella styleguide / devono avere come intestazione il markdown che indica il template da applicare

               
          ---
          layout: styleguide
          title: Nome della pagina che vogliamo creare
          ---
              
            

La pagina index.html va modificata solo quanto viene aggiunta una nuova pagina, inserendone il rispettivo link nel markup.

Gestione dei Partials

I partials sono degli snippet di codice .html da inglobare in qualsiasi pagina o layout del pacchetto. Per inglobare un Partials, il codice da usare è: {{> nome-del-partial}}

In questa cartella sono stati suddivisi per funzionalità, ma non è necessario inserire il percorso specifico nel richiamarli in una pagina, l'importante è utilizzare il nome corretto senza estensione.

Inoltre con i partials Panini è possibile configurare azioni avanzate. Per approfondire: https://zurb.com/university/lessons/159