Aggiungere librerie CSS e JS

Perché Drupal usa le librerie

Definire una libreria in nome_tema.libraries.yml

Nel file nome_tema.libraries.yml si possono indicare i file CSS e JS che devono essere inclusi con le relative dipendenze. Possono inoltre essere indicate delle opzioni di configurazione:

L'ordine in cui vengono caricati i files è quello in cui sono scritti, i files JS sono caricati nel footer ma se si vuole che vengano caricati nell'header basta aggiungere header: true. 

Opzioni per CSS

  • browsers: specifica per quali browsers la libreria deve essere caricata
  • media (solo per i files CSS): attributo media del tag <link>
  • preprocess: indica se deve essere incluso nell'aggregation dei files CSS e JS

Opzioni per JavaScript

  • attributes (solo per i files JS): un oggetto che contiene attributi HTML da inserire nel tag <script>
  • browsers: specifica per quali browsers la libreria deve essere caricata
  • preprocess: indica se deve essere incluso nell'aggregation dei files CSS e JS
  • type (solo per i files JS): indicare file se è un file custom o external se è un file caricato da CDN

Dipendenze tra librerie

Caricamento globale dal file .info.yml

Una volta definite le librerie nel file libraries.yml bisogna decidere dove devono essere caricate. Per librerie che devono essere caricate in tutte le pagine che usano il tema è sufficiente aggiungerle nel file .info.yml. Se invece si vogliono caricare le librerie solo in alcune pagine si utilizza l'hook_page_attachments_alter nel file .theme:

Caricamento da render array o preprocess 

<?php

/**
* Implements hook_page_attachments_alter
*/
function nome_tema_page_attachments_alter(array &$page) {
  $path = $current_path = \Drupal::service('path.current')->getPath();
  
  if ($path == '/node') {
    $page['#attached']['library'][] = 'nome_tema/nome_libreria';
  }
}

?>

Un altro modo è quello di usare una funzione preprocess sempre nel file .theme:

<?php

/**
* Implements hook_preprocess_page() for PAGE document templates.
*/
function nome_tema_preprocess_page(&$variables) {
  if ($variables['is_front'] == TRUE) {
    $variables['#attached']['library'][] = 'nome_tema/nome_libreria';
  }
}

?>

Caricamento da Twig con attach_library()

Oppure si possono caricare le librerie direttamente dentro i files di template:

{% if node.bundle == 'article' %}
  {{ attach_library('nome_tema/nome_libreria') }}
{% endif %}

Estendere una libreria esistente

Se si vuole modificare il comportamento di una libreria predefinita si può fare in modo che ogni volta che quella determinata libreria viene caricata vengano caricate anche le nostre modifiche. Nel file .info.yml:

libraries-extend:
  # Nome della libreria che si vuole estendere
  core/drupal.dropbutton:
    # Lista di una o più librerie che devono essere incluse ogni volta che la libreria padre viene caricata
    - nome_tema/nome_libreria

Sostituire o rimuovere file con libraries-override

Se si vuole invece sostituire una libreria predefinita con una custom si può usare libraries-override:

libraries-override:
  core/drupal.dropbutton: #per escludere tutta la libreria cambiare in core/drupal.dropbutton: false
    css:
      component:
        misc/dropbutton/dropbutton.css: css/my-dropbutton.css #per sostituire il file predefinito con uno custom
        misc/dropbutton/dropbutton.css: false #per escludere completamente il file

Aggregazione/preprocess degli asset