Wie baue ich ein jQuery-Plugin in mein WordPress-Theme ein? So geht's in 2 einfachen Schritten!

Wer kennt das nicht: Man hat ein frisches WordPress-Blog und ein nettes Theme gefunden, doch irgendwie fehlen dem Theme noch 1-2 kleine Features, wie eine Lightbox oder ähnliches. Gibt es für das Problem kein passendes WordPress-Plugin, sondern nur ein jQuery-Plugin, stellt sich dann die Frage, wie man dies in das Theme einbaut.

Daher will ich in dieser Anleitung zeigen, wie man ein jQuery-Script in 2 einfachen Schritten in das eigene oder ein bestehendes Theme einbauen kann.

1. Das jQuery-Plugin im Theme-Verzeichnis ablegen

Dazu erstellt man, wenn es noch nicht vorhanden ist, ein neues Verzeichnis namens js/ innerhalb des Theme-Ordners. Dort kopiert man das jQuery-Script hinein, z.B. /js/query.plugin.min.js. Auch eigene Scripts kann man dort ablegen.

2. Das jQuery-Plugin aktivieren

Damit das jQuery-Plugin auch genutzt wird, muss man WordPress noch sagen, wo es liegt und wie es eingebunden werden soll. Dies geschieht in der functions.php des Themes.

Dort schreibst Du jetzt einfach folgenden Code rein, wobei Du den Dateinamen des Plugins natürlich entsprechend anpassen musst:

add_action( 'wp_enqueue_scripts', 'add_my_scripts' ); 
function add_my_scripts () {
    wp_enqueue_script(
        'my-plugin', // eigener Name
        get_template_directory_uri() . '/js/jquery.plugin.min.js', // Pfad
        array('jquery') // Abhängigkeiten
    );
}

Folgendes passiert hier:

add_action sagt WordPress, dass es für die Aktion wp_enqueue_scripts auch noch unsere Funktion add_my_scripts aufrufen soll. Diese ist in der 2. Zeile ff. definiert.
Wenn WordPress die Seite darstellen will, geht es u.a. auch alle registrierten Funktionen für diese Aktion durch und ruft dann unsere Funktion auf
Mit wp_enqueue_script (Nicht verwechseln mit dem Aktionsnamen) sagen wir dann WordPress, welche JavaScript-Dateien auf der Seite zusätzlich auftauchen sollen (Plugins und das Theme selbst können auch schon welche definiert haben).
Dieser Funktion übergibt man als Parameter den Namen des Scripts, den Pfad zur eigentlichen JS-Datei und eine Liste von Abhängigkeiten (optional).

Hierbei musst Du auf folgende Sachen achten:

Der Name muss einmalig sein (hier „my-plugin“). Dieses identifiziert das Plugin gegenüber WordPress. Der Name sollte am besten klein geschrieben sein und keine Leerzeichen enthalten.
Der Pfad muss natürlich stimmen (hier /js/jquery.plugin.min.js).
Die Abhängigkeiten müssen stimmen, in diesem Fall normalerweise einfach array("jquery"). Schließlich binden wir ja ein jQuery-Plugin ein und das benötigt sicherlich jQuery als Grundlage. WordPress weiß dadurch, dass es erst (das mitgelieferte) jQuery laden soll und dann unser Script.

Achtung: Child-Themes

Wenn Du ein Child-Theme nutzt (z.B. um das Original-Theme nicht ändern zu müssen), dann ändert sich der Aufruf wie folgt:

    wp_enqueue_script(
        'my-plugin', // eigener Name
        get_stylesheet_directory_uri() . '/js/jquery.plugin.min.js', // Pfad 
        array('jquery') // Abhängigkeiten 
    );

Es wird also get_template_directory_uri durch get_stylesheet_directory_uri ersetzt, damit WordPress im richtigen Verzeichnis nachschaut (im Child-Theme und nicht im Haupt-Theme).

Und damit sollte das Plugin erfolgreich eingebunden sein.

Optional: Eigenes JavaScript als Datei einbinden

Oftmals muss man die Funktionen, die das jQuery-Plugin bereitstellt, auch noch aufrufen. Dies geschieht entweder direkt im Footer der Seite (also wahrscheinlich dann in footer.php) oder man lagert dies in ein eigenes Script aus. Gerade wenn es mehr Code wird, macht dies aus Organisations- und Performance-Sicht Sinn.

Nehmen wir also an, Du legst den JavaScript-Code in /js/scripts.js ab, dann musst Du noch einen weiteren wp_enqueue_script-Aufruf zu add_my_scripts hinzufügen:

add_action( 'wp_enqueue_scripts', 'add_my_scripts' );
function add_my_scripts () {
    wp_enqueue_script(
        'my-plugin', // eigener Name
        get_template_directory_uri() . '/js/jquery.plugin.min.js', // Pfad
        array('jquery') // Abhängigkeiten
    );

    // jetzt noch eigenes Script laden
    wp_enqueue_script(
        'my-script', // eigener Name
        get_template_directory_uri() . '/js/scripts.js', // Pfad
        array('my-plugin') // Abhängigkeiten
    );

}

Hier siehst Du folgende Änderungen im Aufruf:

Das Script hat einen anderen Namen (my-script)
Der Pfad ist entsprechend anders (dieselben Regeln für ein Child-Theme gelten)
Die Abhängigkeit ist nicht mehr jquery, sondern jetzt my-plugin, also das Plugin, welches Du in Deinem Script benutzt. Man hätte auch noch jquery zusätzlich angeben können (dann als array('jquery', 'my-plugin')), aber da my-plugin schon jquery als Abhängigkeit hat, ist das nicht unbedingt notwendig.

Script-Versionen definieren

Der obige Aufruf von wp_enqueue_script funktioniert super, solange man immer dieselbe Version eines Scripts/Plugins nutzt. Aktualisiert man das Script aber, kann es je nach Caching-Setup dazu kommen, dass Benutzer noch die alte Version ausgeliefert bekommen. Um dies zu vermeiden, kann man an den Aufruf noch eine Versionsnummer übergeben, z.B. so:

    wp_enqueue_script(
        'my-script', // eigener Name
        get_template_directory_uri() . '/js/scripts.js', // Pfad
        array('my-plugin'), // Abhängigkeiten
        '20160323'
    );

Wie man sieht, wurde mangels offizieller Versionsnummer einfach ein Datum als Versions-String genutzt. Lädt man fertige Plugins aus dem Netz herunter, sollte man die offizielle Versionsnummer dort eintragen (immer als String).

Script im Footer laden

Nicht alles muss im Header der Seite geladen werden. Genauer genommen sollte eigentlich alles, was möglich ist, im Footer geladen werden. Dadurch kann eine Seite teilweise deutlich schneller angezeigt werden.

Um ein Script von WordPress in den Footer laden zu lassen, kannst Du einen weiteren Parameter an wp_enqueue_script anhängen:

    wp_enqueue_script(
        'my-script', // eigener Name
        get_template_directory_uri() . '/js/scripts.js', // Pfad
        array('my-plugin'), // Abhängigkeiten
        '20160323', // Versionsnummer
        true // lade es im Footer
    );

Also einfach noch true anhängen und schon wird es im Footer geladen.

Scripts im Admin-Bereich laden

Wenn ihr das so, wie oben beschrieben, einbaut, dann werden die angegebenen Scripts nur im Frontend geladen. Normalerweise reicht das auch, denn es geht ja um das Theme und damit um die öffentliche Ansicht.

Wenn ihr aber jetzt Plugin- oder Theme-Entwickler seid, dann wollt ihr bestimmte JavaScript-Dateien ggf. auch im Admin-Bereich laden. Dazu nutzt ihr einfach eine andere Aktion, nämlich statt wp_enqueue_scripts dann admin_enqueue_scripts. Wichtig: Es geht hier um den Aktionsnamen, nicht etwa um die Funktion zum Definieren der Scripts, diese ist weiterhin wp_enqueue_script (Singular).

Das erste Beispiel würde also für den Admin-Bereich wie folgt aussehen:

add_action( 'admin_enqueue_scripts', 'add_my_scripts' );
function add_my_scripts () {
    wp_enqueue_script(
        'my-plugin', // eigener Name
        get_template_directory_uri() . '/js/jquery.plugin.min.js', // Pfad
        array('jquery') // Abhängigkeiten
    );
}

Ich hoffe, euch damit geholfen zu haben. Fragen könnt ihr gerne in den Kommentaren hinterlassen. Generell hilft auch, die Doku zu wp_enqueue_script und der zugehörigen Aktion wp_enqueue_scripts zu lesen oder aber Dinge einfach auszuprobieren.