Hinzufügen von CSS, Schriftarten und JavaScript mithilfe der Library API in Drupal 8

Drupal ist ein CMS, das mich immer wieder aufs Neue begeistert. Dank des riesigen Netzwerks der Entwickler-Community ist Drupal wie ein Organismus, der jeden Tag wächst und sich verbessert.

Das 2015 eingeführte System hat erstaunliche Standards im Theming-Bereich sowie bei CSS- und JS-Assets und der Verwaltung von Bibliotheken, den sogenannten Libraries API, gesetzt. Obwohl es diese bereits in Drupal 7 gab, ist es in Version 8 der einheitliche Standard. Es verwendet YAML-Dateien, mit denen Sie Core-Bibliotheken überschreiben, Vorlagen Bibliotheken hinzufügen, Abhängigkeiten festlegen und Bibliotheken von Drittanbietern verwenden können.

Assets werden nicht mehr automatisch geladen, es sei denn, sie werden benötigt. Dies ermöglicht eine schnellere Front-End-Performance. Nachdem ich Ihnen nun die Vorteile der Verwendung der Library API erläutert habe, wollen wir uns ansehen, wie wichtig ihre Verwendung ist. Im folgenden Abschnitt werde ich Sie Schritt für Schritt durch den Prozess der Erstellung von Bibliotheken zum Hinzufügen externer Dateien führen. Verlieren wir keine Zeit und legen wir los.

Schritt 1: Bibliotheken erstellen

In diesem Schritt erstellen Sie eine *.libraries.yml-Datei. Diese Datei enthält alle Ihre Asset-Bibliotheken. Im Falle eines Themes müssen Sie diese Datei im Theme-Ordner erstellen. Und für ein Modul fügen Sie diese Datei dem Stammverzeichnis des Modulordners hinzu.

Unabhängig davon, ob Sie dies für ein Theme oder ein Modul tun, müssen Sie das " * " im Namen der Datei durch den Namen Ihres Themes oder Moduls ersetzen.

Beispiel: Wenn Ihr Theme my_theme heißt, lautet der Name der YAML-Datei my_theme.libraries.yml.

Nachfolgend finden Sie einen Überblick darüber, wie Sie eine Bibliothek definieren: 

#Bibliothek einen Namen geben
header: 
  css: 
    # Die SMACSS-Kategorie
    theme: 
      # Pfad relativ zum Theme-Verzeichnis
      build/libraries/header/header.css: {}
  js: 
    # Pfad relativ zum Theme-Verzeichnis
    build/libraries/header/header.js: {}
  dependencies:
    - core/jquery

Achten Sie darauf, dass Sie beim Erstellen Ihrer Bibliotheksdatei keine Tabulatoren verwenden. Da es sich um eine YAML-Datei handelt und YAML sehr streng ist, was die Verwendung betrifft, finden Sie eine gute Auffrischung zu YAML genau hier.

CSS hinzufügen

Wir sehen auch, dass wir zwei Abschnitte unter dem Namen CSS und JS haben. CSS ist ein Abschnitt, der alle CSS-Dateien enthält, und alle Dateien sind unter bestimmten Kategorien aufgelistet. Im obigen Beispiel haben wir beispielsweise das Theme als Kategorie. Dies werden als SMACSS-Kategorien bezeichnet und von Drupal für CSS-Dateien verwendet. 

SMACSS ist eine Methode zum Organisieren von CSS-Regeln und -Dateien. Es gibt im Wesentlichen fünf Kategorien: Basis, Layout, Komponente, Status und Theme. Mehr darüber finden Sie hier.
Wir können sehen, dass nach dem Pfad unserer Datei geschweifte Klammern stehen. Hier können wir zusätzliche Eigenschaften festlegen.

JS hinzufügen

Ähnlich wie bei CSS fügen wir alle unsere Javascript-Dateien im JS-Abschnitt hinzu. Obwohl es hier keine SMACSS-Kategorie gibt, müssen Sie in diesem Fall wissen, dass die JS-Dateien dennoch in verschiedenen Zeilen hinzugefügt werden. Außerdem können wir in der geschweiften Klammer zusätzliche Eigenschaften festlegen, genau wie bei CSS.

Standardmäßig fügt Drupal 8 alle Javascript-Dateien in die Fußzeile der Seite ein. Wenn Sie also möchten, dass Ihr JS hinzugefügt wird, müssen Sie "header: true" zur Bibliothek hinzufügen. Dadurch werden alle Ihre JS- und Abhängigkeiten im Header hinzugefügt.

Hier sind Abhängigkeiten alle anderen Bibliotheken von Drittanbietern, von denen Ihre Bibliothek abhängen kann. Sie werden automatisch angehängt, wenn Sie Ihre Bibliothek anhängen, und sie werden vor Ihrer Bibliothek geladen.

Externe Dateien hinzufügen

Unter bestimmten Bedingungen müssen Sie möglicherweise Javascript verwenden, das sich extern in einem CDN (Content Delivery Network) befindet, z. B. wenn Sie Ihrer Seite einige Webfonts hinzufügen müssen. Um diese Schriftarten zu erhalten, müssen Sie externes Javascript verwenden.

Dies kann erreicht werden, indem Sie die URL zum Abrufen des Inhalts angeben und den Typ: external in der Bibliothek festlegen. Auch wenn es nicht obligatorisch ist, ist es eine gute Praxis, einige Informationen über die externen Dateien in der Bibliothek hinzuzufügen.

Die folgenden zwei Beispiele zeigen das Hinzufügen von Font Awesome und Google Font (Lato) zur Bibliothek.

font-awesome:
  remote: https://fortawesome.github.io/font-awesome/
  version: 4.5.0
  license: 
    name: mit
    url: https://fortawesome.github.io/font-awesome/license/
    gpl-compatible: true
  css:
    theme:
      https://maxcdn.bootstrapcdn.com/font-awesome/4.5.0/css/font-awesome.min.css: { type: external, minified: true}
lato: 
  css:
    base:
      ‘//fonts.googleapis.com/css?family=lato’: { external: true}

Nachdem Sie nun ein grundlegendes Verständnis der Dateistruktur haben, fahren wir mit dem nächsten Schritt fort.

Schritt 2: Bibliotheken anhängen

Es gibt mehr als eine Möglichkeit, die Bibliotheken anzuhängen. Sie können die Bibliotheken auf eine der folgenden Arten anhängen:

• Über die *.info.yml-Datei
• Über die Twig-Vorlage
• Über PHP

Sehen wir uns zunächst an, wie wir die Bibliotheken mit der *.info.yml-Datei anhängen können.

name: Ihr Theme
type: theme
description: Dies ist Ihre Theme-Beschreibung
core: 8.x
libraries: 
  # Die folgenden Bibliotheken werden global hinzugefügt
  - your-theme/global

Das ist es. Das ist alles, was Sie tun müssen, um die Bibliotheken global anzuhängen.

Da Drupal 8 die Twig-Templating-Engine verwendet, können Sie die Bibliotheken direkt über Twig-Vorlagen anhängen. Wenn Sie beispielsweise einen Suchformularblock haben, können Sie das CSS und JS für den Block definieren, ihn zu einer Bibliothek hinzufügen und diese Bibliothek zur Twig-Vorlage des Suchformularblocks hinzufügen. Diese Assets, die spezifisch für den Suchformularblock sind, werden nur einbezogen, wenn der Block gerendert wird. 

{{ attach_library(‘your-theme/search-block’) }}

<div{{ attributes.addClass(classes) }}>
  {% if label %}
    <h2{{ title_attributes }}>{{ label }}</h2>
  {% endif %}
  {% block content %}
    {{ content }}
  {% endblock %}
</div>

Abgesehen von den oben genannten Methoden können wir Bibliotheken auch mit PHP anhängen. Mit PHP können Bibliotheken in der Vorverarbeitung angehängt werden. Dies bedeutet, dass Sie eine Logik definieren können, die die Bedingungen überprüft, die erfüllt sein müssen, bevor die Bibliothek dem Bibliotheksarray hinzugefügt wird.

/**
  * Implementiert hook__page_attachments()
  */

Function mytheme_page_attachments(array &$attachments) {
  $attachments[‘#attached’][‘library’][] = ‘your-theme/your-library;
}

Erweitern und Überschreiben

Neben den verschiedenen Vorteilen, die Drupal 8 bietet, ist dies einer der nützlichsten und wichtigsten. Sie können Bibliotheken einfach erweitern oder überschreiben. Sie können dies mit der *.info.yml-Datei tun. Lassen Sie uns zunächst die Bibliothekserweiterung besprechen.

name: Ihr Theme
type: theme
description: Dies ist Ihr Theme
core: 8.x
libraries:
  # Die folgenden Bibliotheken werden global hinzugefügt
  -your-theme/global

libraries-extend:
  #Die Forumsbibliothek von Classy wird nur einbezogen, wenn die
  # forums.html.twig-Vorlage verwendet wird.
  classy/forums:
    -your-theme/forums

Hier ist libraries-extend eine Eigenschaft, die Sie in Ihrer *.info.yml verwenden. Hier bedeutet die Erweiterung, dass Ihre Bibliothek auf die gleiche Weise wie eine vorab angehängte Bibliothek angehängt wird und ihre Funktionalität erweitert.
Nachdem Sie nun etwas über libraries-extend wissen, kommt als Nächstes libraries-override.

name: Ihr Theme
type: theme
description: Dies ist Ihr Theme
core: 8.x
libraries: 
  # Diese Bibliotheken werden global hinzugefügt
  - your-theme-name/global
libraries-override:
  # Ersetzt die gesamte Bibliothek

  your-base-theme/global: your-child-theme/global
    
   # Entfernt die gesamte Bibliothek
   your-base-theme/search_form: false

   # Ersetzt eine bestimmte Datei
   # Kopieren Sie die Bibliothek, die die Datei enthält, die Sie ersetzen werden
   global:
     css:
       theme:
         build/libraries/global/global.css: build/libraries/global/global-new.css
   # Entfernt eine bestimmte Datei
   global: 
     css:
       theme:
       # Originalpfad zur Datei. nicht relativ zu Ihrem Theme.
         build/libraries/global/global.css: false

Libraries-override ist auch eine Eigenschaft, die Sie in der *.info.yml-Datei verwenden. Es dient als ein leistungsstarkes Werkzeug, das Ihnen die vollständige Kontrolle über die Bibliothek gibt und es Ihnen ermöglicht, sie auf jede Art und Weise zu manipulieren, die Sie für richtig halten.
Mit dieser Eigenschaft können Sie bestimmte Dateien oder sogar ganze Bibliotheken ersetzen oder entfernen. Es hängt ganz von Ihrer Wahl und Ihren Bedürfnissen ab.

Zusammenfassend

Das war alles, was Sie brauchten, um mit der Verwendung der Libraries API zu beginnen. Es ist ein wunderbares Werkzeug und kann verwendet werden, um die Aufgaben schnell zu erledigen. Es kann einige Zeit dauern, bis Sie wirklich gut darin sind, aber das Obige ist das absolute Minimum, das Sie wissen müssen, um seine Leistungsfähigkeit zu nutzen. Ich wünsche Ihnen alles Gute auf Ihrer Drupal-Reise und "Möge die Macht mit Ihnen sein"