Es gibt eine Reihe von Möglichkeiten, um externe Javascript Bibliotheken Drupal hinzuzufügen, um die Website mit bestimmten erweiterten Funktionalitäten auszustatten, z.B. Slider, Endlos-Scroller Seiten uvm. Es existiert eine schier unbegrenzte Menge an solchen nützlichen Helferlein, doch wie bindet man diese korrekt in seine Drupal Website ein?
Dieser Artikel beschreibt das Hinzufügen von externen Javascript Bibliotheken mittels Libraries API, der einigermaßen zukunftssicher scheint. Drupal 8 ist zu diesem Zeitpunkt noch in der Betaphase, wird aber von Haus aus Möglichkeiten zur Einbindung von Javascript- und auch PHP-Bibliotheken mit sich bringen, die dem Weg mit der Libraries API sehr ähnlich sind.
Einbindung einer JavaScript Library im Libraries-Verzeichnis
Als Vorbereitung Drupal Modul: Libraries API installieren
Zunächst sollte das Drupal Modul Libraries API auf der betreffenden Website installiert werden. Diese sorgt dafür, daß externe Javascripte der Website und auch weiteren Modulen bereitgestellt werden. Das Modul einfach wie jedes andere Drupal-Modul installieren, d.h. entweder einfach den URL-Pfad des ZIP- oder TGZ-Archivs kopieren und einfügen oder das Datei-Archiv selbst herunterladen, entpacken und hochladen. Ersterer Weg ist wesentlich bequemer.
Das Modul Libraries API ist unter dieser Adresse verfügbar: https://www.drupal.org/project/libraries. Unten auf der Seite finden sich immer die angebotenen Downloads zum Drupal-Modul.
Es ist immer eine gute Idee, evt. Hinweise zu den Versionen und ggf. weiteren Abhängigkeiten zu lesen. Ansonsten einfach einen Rechtsklick auf das tar.gz der gewünschten Version (normalerweise sollte man immer das/die recommended releases nehmen), die Adresse des Links kopieren und dann zur Modul-Übersichtsseite der eigenen Website navigieren. Dort einfach den kopierten Link zum tar.gz einfügen und installieren lassen.
Mögliche Ablageorte für Javascripte sind:
/sites/all/libraries/sites/[domainname.tld]/libraries
Das heißt, auch in Drupal-Multisite Umgebungen können verschiedene Javascript Bibliotheken verschiedenen Drupal-Instanzen unter verschiedenen Domains zur Verfügung gestellt werden. Falls also die betreffende JavaScript Library in einer Multisite-Umgebung (1 Drupal, mehrere Domains, mehrere Datenbanken) nur einer ganz bestimmten Domain hinzugefügt werden soll, empfiehlt es sich, die JavaScript Library unter dem Pfad /sites/[domainname.tld]/libraries bereitzustellen.
Für den weiteren Verlauf dieses Artikels wird von /sites/all/libraries als Library-Pfad ausgegangen, da dies für die meisten Anwendungen der richtige Platz ist.
Anpassungen im Drupal Theme
In der Datei /sites/all/themes/[theme_name]/template.php werden nun z.B. einfach im Hook preprocess_page() die externen JavaScript Bibliotheken genannt, die für eine bestimmte Seite oder generell geladen werden sollen. Falls die Datei template.php oder die Funktion preprocess_page() nicht vorhanden ist, einfach anlegen bzw. hinschreiben.
Hier ein Beispiel, durch die jeweiligen Namen der eigenen, hinzugefügten JavaScript Libraries ersetzen:
Datei /sites/all/themes/[theme_name]/template.php
<?php/** * @file * template.php */function [theme_name]_preprocess_page( &$vars, $hook ){ // load external libraries through library api, located in /sites/all/libraries. libraries_load( 'imagesloaded' ); libraries_load( 'packery' ); libraries_load( 'meine_javascript_library' ); /* evt. weitere anweisungen in preprocess_page() */}
Wie bei Drupal üblich wird das schließende ?> nicht gesetzt.
Der Libraries Ordner
Die Libraries API wird evt. vorhandene .info Dateien, die die jeweiligen JavaScript Bibliotheken näher beschreibt, beachten. Wie für Drupal-Module und Drupal Themes, so kann hier ebenfalls eine .info Datei generiert werden, die einige Informationen bereitstellt, die an anderer Stelle ggf. weiterverarbeitet werden können. Zudem hilft diese Datei, den Überblick zu wahren und ermöglicht eine Versionierung der JavaScript Bibliotheken.
Zum Beispiel könnte sich unter /sites/all/libraries/ folgendes abspielen:
- (Ordner) imagesloaded -- imagesloaded.pkgd.min.js- imagesloaded.libraries.info
Mit folgendem Inhalt in imagesloaded.libraries.info:
name = imagesLoadedmachine name = imagesloadeddescription = JavaScript is all like "You images are done yet or what?"version = 3.1.8files[js][] = imagesloaded.pkgd.min.js
Man erstellt also einen Ordner, der den Namen der JavaScript Lib trägt (imagesloaded), schiebt dort die tatsächlich genutzte Library selbst hinein und legt eine Datei mit der Namensgebung [libraryname].libraries.info an, in der Name, Beschreibung, Version und Dateien festgehalten werden können. So kann man jederzeit in diese Datei schauen, um z.B. die genutze Version festzustellen.
Initialisieren und Nutzen der JavaScript Library
Damit die externe JavaScript Library im Drupal Theme nun ihre Wirkung entfaltet, muss sie ggfs. noch intitalisiert bzw. mit den gewünschten Werten eingestellt werden. Dies ist nun Aufgabe des Themes. Hierzu legt man sich eine Datei mit entsprechenden JavaScript Anweisungen z.B. im Verzeichnis [theme_name]/js an und bindet sie via [theme_name].info Datei ein. Nach flushen des Cache ist dies dann sofort aktiv.
Aber der Reihe nach:
Zunächst eine Datei /sites/all/themes/[theme_name]/js/control.js (Name der Datei beliebig) anlegen, mit den spezifischen Anweisungen für die genutzten JavaScript Bibliotheken. Das "Gerüst" ist ein funktions-gekapselter jQuery-Aufruf:
/sites/all/themes/[theme_name]/js/control.js
(function ($) { $(function( ) { /* hier die Anweisungen, Initalisierungen fuer die js lib */ /* ... */ });})(jQuery);
Ein Beispiel könnte so aussehen. Wie gesagt, der Inhalt dieser Datei hängt von den gewünschten Einstellungen zur entsprechenden JS Lib ab.
// We define a function that takes one parameter named $.(function ($) { $(function(){ /* language switch menu in navbar mit zus. css-klassen versehen */ /*$('.language-switcher-locale-url').addClass('menu nav navbar-nav');*/ /* call imagesloaded and add packery (masonry) to bootstrap grid views */ var $angebote_container = $('#views-bootstrap-thumbnail-1'); $angebote_container.imagesLoaded( function() { $angebote_container.packery({ itemSelector: '.col', }); }) });})(jQuery);
Der Grund für die "Kapselung" der jQuery-Aufrufe in einer Funktion $ im Namensraum (jQuery) ist, daß auch andere JavaScript Bibliotheken evt. das Kürzel "$" als Funktionsaufruf nutzen, z.B. Prototype u.a. Damit nun klar wird, mit welcher JavaScript Variante der Code beginnend mit "$" ausgeführt werden soll, notiert man es so. Setzen Sie also z.B. Prototype anstelle von jQuery ein, dann wird dieser Namensraum einfach am Ende des Funktionsaufrufes notiert.
Diese Javascript-Datei (control.js) muss dem genutzten Theme nur noch bekannt gemacht werden, damit sie geladen und ausgeführt wird. Um die Reihenfolge der geladenen Javascript-Dateien kümmert sich Drupal.
Hierzu in der .info Datei des Themes ([theme_name].info) folgende Zeile einfügen:
scripts[] = js/control.js
Anschließend den Cache von Drupal unter /admin/config/development/performance löschen und schon sind die Anweisungen unserer Setting-Datei (control.js) mit der entsprechenden JavaScript Bibliothek live und aktiv.
Falls nicht, hilft ein Blick in die JavaScript-Entwicklerkonsole des Webbrowsers. Oft handelt es sich nur um Tippfehler bei Bezeichnern oder es wurde eine Klammer falsch gesetzt. Gerade bei den geschachtelten Aufrufen in jQuery hilft eine ordentliche Strukturierung der Anweisungen, damit man den Überblick der vielen Klammern nicht verliert.
Vorteile der Einbindung via Libraries API
Mit dieser Methode kann man auch bei einer Multisite-Installation selbst eine größere Anzahl an JavaScript Libraries übersichtlich verwalten und jeder Website z.B. eine andere Einstellung derselben JavaScript Bibliothek mitgeben.
Falls man die JavaScript Bibliotheken einfach in den Ordner /sites/all/themes/[theme_name]/js wirft, wird man diese Möglichkeiten nicht haben und zudem schnell den Überblick verlieren. Denn zum Beispiel die verwendete Version einer JS Lib herauszufinden, ist nicht immer so einfach, wenn es sich um die "gepackte" Version handelt.
Der Aufwand der Einbindung via Libraries API ist ein ganz klein wenig größer als alles einfach in den Theme Ordner zu werfen, aber spätestens, wenn man doch mal Anpassungen vornehmen muss, wird sich dieser Weg schnell bezahlt machen.
Zudem steht - wie eingangs erwähnt - Drupal 8 vor der Tür und wird höchstwahrscheinlich eh diesen oder einen sehr ähnlichen Weg beschreiten.
Weiterführende Informationen zu JavaScript in Drupal in der Community Dokumentation:
- JavaScript API (includes AJAX, AHAH) in Drupal 7
- (Unterkapitel) Working with Javascript
- (Unterkapitel) Managing JavaScript in Drupal 7
