<h2>Aggiungere fogli di stile (CSS) e JavaScript (JS) in un modulo Drupal 8</h2>

Questa documentazione è per i moduli. Per informazioni sui temi, consulta la sezione Aggiungere fogli di stile (CSS) e JavaScript (JS) in un tema Drupal 8.

In Drupal 8 i fogli di stile (CSS) e JavaScript (JS) vengono caricati attraverso lo stesso sistema sia per i moduli (codice) sia per i temi: la libreria delle risorse. Le librerie di asset possono contenere una o più risorse CSS, una o più risorse JS e una o più impostazioni JS.

Drupal utilizza un principio di alto livello: le risorse (CSS o JS) vengono comunque caricate solo se indichi a Drupal che devono essere caricate. Drupal non carica tutte le risorse (CSS/JS) su tutte le pagine, perché questo ridurrebbe le prestazioni dell’interfaccia.

Differenze da Drupal 7

Ci sono due differenze importanti rispetto a Drupal 7 per gli sviluppatori:

1. Solo il JavaScript necessario per una pagina specifica verrà aggiunto a quella pagina. In particolare, per impostazione predefinita Drupal non richiede JavaScript sulla maggior parte delle pagine che possono vedere gli utenti anonimi. Questo significa che jQuery non viene più caricato automaticamente su tutte le pagine.
Quindi, se il tuo tema ha bisogno di jQuery o di qualsiasi altro JavaScript (anch’esso definito in una libreria di risorse), devi indicare a Drupal di farlo, dichiarando una dipendenza dalla libreria di asset necessaria.

2. L’oggetto JavaScript Drupal.settings è stato sostituito da drupalSettings.

Processo

Le fasi principali per caricare risorse (CSS / JS):

1. Salva il CSS o JS in un file.
2. Definisci una “libreria” che può contenere file CSS e JS.
3. “Allega” la libreria a un array di rendering in un hook.

Ma nel caso dei temi c’è un’alternativa al passo 3: i temi possono caricare un numero qualsiasi di librerie di risorse su tutte le pagine.

Definire una libreria

Per definire una o più librerie (risorse), aggiungi un file *.libraries.yml nella cartella principale del tuo modulo (insieme al file .info.yml). (Se il tuo modulo si chiama fluffiness, allora il nome del file deve essere fluffiness.libraries.yml). Ogni “libreria” nel file è una voce che dettaglia i file CSS e JS (risorse), per esempio:
Nota speciale per i francofoni: attenzione a scrivere correttamente .libraries.yml! Non .librairies.yml!! (in francese “librairie” significa libreria/libro…) altrimenti perderete molto tempo a capire cosa non funziona, dato che Drupal non darà errore quando tenterà di allegare una libreria inesistente… ;)

cuddly-slider:
  version: 1.x
  css:
    layout:
      css/cuddly-slider-layout.css: {}
    theme:
      css/cuddly-slider-theme.css: {}
  js:
    js/cuddly-slider.js: {}

Noterai le chiavi 'layout' e 'theme' per il CSS, che non ci sono per il JS. Questo indica il tipo di stile a cui appartiene il file CSS.

Puoi impostare il peso del CSS con 5 diversi livelli di stile:

• base: reset/normalizzazione CSS più la stilizzazione degli elementi HTML. Chiave = CSS_BASE = -200
• layout: disposizione macroscopica della pagina web, inclusi eventuali sistemi a griglia. Chiave = CSS_LAYOUT = -100
• component: elementi discreti e riutilizzabili dell’interfaccia utente. Chiave = CSS_COMPONENT = 0
• state: stili legati ai cambiamenti lato client dei componenti. Chiave = CSS_STATE = 100
• theme: stile puramente visivo per un componente. Chiave = CSS_THEME = 200

Questo è definito dallo standard SMACSS. Quindi, se specifichi theme, significa che il file CSS contiene stili relativi all’aspetto visivo. Ulteriori informazioni qui. Non puoi usare altre chiavi, altrimenti otterrai errori severi.

In questo esempio si presume che il file JavaScript cuddly-slider.js si trovi nella sottocartella js del tuo modulo. Puoi anche far sì che JS provenga da un URL esterno, includere file CSS, e ci sono altre possibilità. Consulta CDN / librerie esterne per i dettagli.

Tieni presente che Drupal 8 non carica più jQuery su tutte le pagine per impostazione predefinita; carica solo ciò che serve. Pertanto, dobbiamo dichiarare che la libreria cuddly-slider del nostro modulo dipende dalla libreria che fornisce jQuery. Non è un modulo o un tema a fornire jQuery, ma il core di Drupal: core/jquery è la dipendenza da dichiarare. (È nome_estensione/nome_libreria, quindi se un’altra libreria volesse dipendere dalla nostra cuddly-slider, dovrebbe dichiarare la dipendenza da fluffiness/cuddly-slider, dato che fluffiness è il nome del nostro modulo.)

Perciò, per garantire che jQuery sia disponibile per js/cuddly-slider.js, aggiorniamo così:

cuddly-slider:
  version: 1.x
  css:
    theme:
      css/cuddly-slider.css: {}
  js:
    js/cuddly-slider.js: {}
  dependencies:
    - core/jquery

Come ci si aspetta, l’ordine in cui elenchi CSS e JS è anche l’ordine in cui vengono caricati.

Per impostazione predefinita Drupal allega le risorse JS in fondo alla pagina, per evitare problemi comuni come: bloccare il caricamento del DOM, accedere a un elemento non pronto dal codice jquery, ecc. Se per qualche motivo hai bisogno di allegare gli asset JS nell’elemento <head>, puoi usare l’opzione header, così:

cuddly-slider:
  version: 1.x
  header: true
  js:
    js/cuddly-slider.js: {}

Ora js/cuddly-slider.js sarà allegato in cima alla pagina.