Seit einigen Jahren schreibe ich u.a. eigene WordPress-Themes für diverse Projekte. Seit einigen Jahren artet dies auch des öfteren in Code-Chaos aus. Wer nicht zu Beginn eine klare Aufteilung und Struktur in sein Projekt bringt, wird schnell unübersichtlichen HTML-, PHP-, JS und CSS-Code als Ergebnis haben.

Vor kurzem habe ich mir dann Sage von roots.io näher angesehen. Dieses Framework arbeitet von Grund auf bereits mit einigen modernen Dev-Techniken und vereinfacht so Versionierung, Struktur und Wartbarkeit. On Top gibt es noch das Template-System von Laravel, welches ich als PHP-Framework für Projekte abseits von WordPress sehr schätze.
Generell finde ich es sehr angenehm, dass sich der gesamte Code in einem WP-Projekt via Sage objektorientiert schreiben lässt. Sprich: Controller und Views – saubere Trennung zwischen Funktionalität und Ausgabe. Wer also schon gewöhnt ist, mit Laravel oder CakePHP zu arbeiten oder grundsätzlich auf MVC-Basis programmiert, wird sich hier schnell zurechtfinden.

Auch hier setze ich zunächst auf ein grundsätzliches Docker-Compose-LAMP-Konstrukt, welches ich für die meisten meiner Web-Projekte nutze und je nach Bedarf in den Dockerfiles anpasse. Für Sage benötigen wir zunächst eine grundsätzliche WordPress-Installation. Das Sage-Basis-Template ist das komplette Theme-Verzeichnis. Sprich: Sage wird direkt unter /wp-content/themes/[SAGE_PROJEKTNAME] installiert.

Yarn

Yarn ist eine Alternative zu npm, ein Paketmanager für node_modules/NodeJS. Ähnlich, wie ich es in meinem Beitrag zur Organisation von JavaScript und CSS beschrieben hatte, nutzt auch Sage eine Browsersync.

Yarn wirst du beim Entwickeln des WordPress-Themes immer benötigen, bzw. hauptsächlich die Funktion von Browsersync. Da es hier anscheinend oft zu Missverständnissen kommt: Browsersync sorgt dafür, dass sämtlicher SASS/SCSS-Code in Echtzeit in den Browser injiziert wird. In der Terminal-Ausgabe wird hierfür ein Webserver unter Port 3000 und ein Browsersync-Interface unter Port 3001 zur Verfügung gestellt. Zusätzlich läuft dann allerdings auch noch der normale DEV-Server auf Port 80 (oder auf welchem alternativen Port auch immer dieser eingestellt ist). In meinem Fall läuft der DEV-Server (also die WordPress-Installation) auf Port 80 in einem Docker-Container lokal. Dies kann allerdings natürlich auch ein entfernter Webserver sein oder ein Docker-Container auf einem alternativen Port. Beim Setup von Sage werden diese Parameter allerdings abgefragt und können auch später noch angepasst werden (unter /resources/assets/config.json).
Sobald also Browsersync läuft (via „yarn start“), führen alle änderungen am Code dazu, dass dieser direkt in den Browser übertragen wird. Hierbei ist es auch wichtig zu verstehen, dass die Haupt-CSS-Datei des DEV-Servers einen Fehler 404 auswirft (main.css), da diese nicht „in Echt“ kompiliert wurde, sondern nur auf Port 3000 in den Code injiziert wird (Ergebnis des SCSS-Kompilierens). Ist die Entwicklung am Projekt fertig oder der aktuelle Arbeitsschritt getan, kann via „yarn build“ der CSS- und JS-Code dauerhart kompiliert werden. Sprich: Hier wird jetzt aus dem SCSS-Code CSS-Code generiert und tatsächlich ins Dist-Verzeichnis (main.css) geschrieben. Ab hier funktioniert die Seite dann auch direkt auf dem DEV-Server (und nicht über Port 3000). Wichtig ist hier auch zu wissen: Sobald Du wieder im DEV-Mode bist (also „yarn start“), werden die statischen Inhalte im Dist-Verzeichnis wieder entfernt.

Laravel Blade

Wer das Template-System aus Laravel noch nicht kennt: auf laracasts.com gibt es einige Tutorials. Hier empfehle ich ein „from scratch“-Tutorial und darin den Teil, bei welchem es um die Templates geht.

Die Logik und Syntax für die Blade-Templates ist nicht sehr schwierig und du gewöhnst dich innerhalb kürzester Zeit daran (und möchtest es gar nicht mehr missen).

Fazit

Roots/Sage gefällt mir außerordentlich gut. Die Struktur, die hier geboten wird, ist sehr durchdacht und bietet bereits von Grund auf eine Ausstattung mit verschiedenen modernen Werkzeugen, die einzeln organisiert einen deutlichen Aufwand bedeuten würden. Auch die Integration von Composer, dem Template-System und yarn ist bereits so konfiguriert, dass man nach anfänglichem entwickeln auch sehr einfach weitere JS-, CSS- oder PHP-Pakete (Composer) nachladen kann und durch diese Systeme natürlich auch gleich die Versionen der einzelnen Frameworks zentral steuern, bzw. überwachen kann.

Was an dieser Stelle auch noch empfehlenswert ist, da es ja immer noch eine Art Grauzone ist: Sämtliche Frameworks ladet ihr lokal und nur bei Bedarf via CDN. Das externe Laden von Scripts via CDN ist m.W. auch noch nicht so ganz hinsichtlich der DSGVO geklärt.

Natürlich kann dieser Beitrag nur ein kurzes Umreißen der Features sein, die mir persönlich am meisten Gefallen. Sage bietet deutlich mehr. Ein Blick lohnt sich – und nicht gleich aufgeben! Sortierter und sauberer Code und ein fast schon integriertes Deployment-Konzept wird dir auch später bei der Wartung der so erstellten Themes helfen.

Hinweis: Auf arch linux wurde folgender Fehler nach „yarn start“ ausgeworfen:

[...] node_modules/webpack/lib/Chunk.js:866
		throw new Error(
		^

Error: Chunk.entrypoints: Use Chunks.groupsIterable and filter by instanceof Entrypoint instead [...]

Den Fehler konnte ich durch Installation der 4.0.0-Beta von extract-text-webpack-plugin beheben.

yarn add extract-text-webpack-plugin@Next

The post WordPress-Templates mit Roots/Sage entwickeln first appeared on NET73.

Ausgangslage (Beispiel)

Grundvoraussetzung für den nachfolgend beschriebenen Einsatz von gulp ist, dass bereits NodeJS und npm (oder yarn) in der Entwicklungsumgebung installiert sind.

Ein PHP-Web-Projekt sieht bei mir meistens so aus, dass ich im obersten Verzeichnis alle Umgebungs-Tools ablege (Dateien für Docker, Vagrant, etc.). Dort ist dann auch ein Verzeichnis „www“, in welchem das eigentliche Projekt liegt. In diesem Verzeichnis sind in der Wurzel dann die Dateien für die DEV-Tools (Composer, Node, Gulp, etc.), ein „app“-Verzeichnis, in welchem die PHP-Aktionen sind (MVC) und ein „public“-Verzeichnis, welches die „htdocs“ für die Webroot bereithält. Hier ist meistens nur eine index.php-Datei, welche die Core-Klasse(autoload) aus dem app-Verzeichnis lädt und eben die statischen Frontend-Dateien (js,css, scss, assets, fonts, etc.).

In der Übersicht sieht das dann so aus:

├── app ->
│   ├── init.php
│   ├── config ->
│   ├── controller ->
│   ├── library ->
│   ├── model ->
│   └── view ->
├── composer.json
├── composer.lock
├── composer.phar
├── gulpfile.js
(├── node_modules -> # wird erst mit "npm install" automatisch angelegt!)
├── package.json
├── package-lock.json
├── public ->
│   ├── css ->
│   ├── js ->
│   ├── fonts ->
│   ├── scss ->
│   └── index.php
└── Readme.md

Das Ziel ist hier also, dass die benötigten JS- und CSS-Dateien aus node_modules in das Frontend-Verzeichnis nach public/js und public/css überführt werden und die selbst geschriebenen SASS-Scripts aus public/scss mit den Scripts aus node_modules zusammen in public/css kompiliert werden (letzteres inkl. FileWatcher in Echtzeit.

Als Basis-Beispiel eine package.json-Datei, die bereits Gulp lokal via npm (oder yarn) installiert:

{
  "name": "n73-test",
  "version": "0.1.0",
  "description": "Test-Projekt zur gulp-Demonstration",
  "main": "public/index.php",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "Pixel64",
  "license": "MIT",
  "dependencies": {
    "bootstrap": "^4.4.1",
    "jquery": "^3.4.1",
    "popper.js": "^1.16.1"
  },
  "devDependencies": {
    "browser-sync": "^2.26.7",
    "gulp": "^4.0.2",
    "gulp-sass": "^4.0.2"
  }
}

In diesem Projekt werden also die Pakete Bootstrap, JQuery und Popper gezogen und in das Verzeichnis node_modules gelegt.

GULP.JS

Mit der obigen Verzeichnisstruktur werden die Module via „npm install“ installiert (im Root-Verzeichnis, in welchem sich auch die package.json-Datei befindet).

Ist der Vorgang ausgeführt ist gulp _lokal_ installiert! Eine globale Installation von gulp(-cli) kann über den Paketmanager oder mit dem Schalter „-g“ erreicht werden (npm install -g gulp).

Die lokale Projekt-Installation reicht allerdings i.d.R. aus. Die installierte Version kann wie folgt geprüft werden:

./node_modules/.bin/gulp --version
CLI version: 2.2.0
Local version: 4.0.2

gulpfile.js

Die Anweisungen, was gulp im Verzeichnis erledigen soll, werden in der Datei gulpfile.js festgehalten. Eine Beispieldatei für das Test-Projekt sieht so aus:

var gulp        = require('gulp');
var browserSync = require('browser-sync').create();
var sass        = require('gulp-sass');

// SASS kompilieren, nach public/css verschieben und in browsersync aufnehmen
gulp.task('sass', function(){
    return gulp.src(['node_modules/bootstrap/scss/bootstrap.scss', 'public/scss/*.scss'])
        .pipe(sass())
        .pipe(gulp.dest('public/css'))
        .pipe(browserSync.stream());
});

//JS nach public/js verschieben
gulp.task('js', function(){
    return gulp.src([
        'node_modules/bootstrap/dist/js/bootstrap.min.js', 
        'node_modules/jquery/dist/jquery.min.js', 
        'node_modules/popper.js/dist/umd/popper.min.js'])
        .pipe(gulp.dest('public/js'))
        .pipe(browserSync.stream());
});



//Fonts nach public/fonts schieben
gulp.task('fonts', function(){
    return gulp.src('node_modules/font-awesome/fonts/*')
        .pipe(gulp.dest('public/fonts'));
});

//fontawesome nach public/css verschieben
gulp.task('fa', ()=>{
    return gulp.src('node_modules/font-awesome/css/font-awesome.min.css')
        .pipe(gulp.dest('public/css'))
        .pipe(browserSync.stream());
});

// SASS ueberwachen und bei Veraenderungen kompilieren
gulp.task('serve', gulp.series('sass', function() {
    browserSync.init({
	    proxy: 'http://localhost/',
	    notify: true,
    });

    gulp.watch(['node_modules/bootstrap/scss/bootstrap.scss', 'scss/*.scss'], gulp.series('sass'))
    gulp.watch('*.php').on('change', browserSync.reload);
}));


gulp.task('default', gulp.series('js', 'serve', 'fa', 'fonts'));%

Ist diese Datei erstellt, reicht ein einfacher Aufruf von ./node_modules/.bin/gulp und der Vorgang startet. Jetzt werden die entsprechenden Scripts kopiert und ein aktiver FileWatcher überwacht SASS und kompiliert bei Veränderungen scss nach css. Zudem werden die Veränderungen an den definierten Dateien im www-Verzeichnis über einen lokalen Server (Port 3000) angezeigt (index.php oder index.html, je nach Projekt). Letzteres wird durch den gulp-task „server“ organisiert und kann bei Bedarf oder Nutzung anderer Entwicklungsumgebungen deaktiviert werden (Docker- oder Vagrant-Umgebung?).

Zusatz

Natürlich kann gulp auch in komplett statischen Umgebungen eingesetzt werden. Generell müssen jeweils nur die Verzeichnisse an die eigene Projektstruktur angepasst werden.

Über die package.json-Datei kann jeweils kontrolliert werden, welche Versionen von Bootstrap, JQuery & Co. geladen werden sollen und den Weg ins eigene Web-Projekt finden. Die so erstellten CSS- und JS-Dateien können dann wie gewohnt aus dem /js- und /css-Verzeichnis in die eigenen Web-Dateien (PHP->Views, oder HTML-Dateien->statisch) eingebunden werden.

Für das Deployment im Produktiv-Betrieb ist somit auch kein einzelnes Zusammensuchen der Bibliotheken notwendig und auch kein Überwachen der statisch eingebundenen CDN-Links im Projekt notwendig (kann man trotzdem parallel nutzen).

The post CSS und JavaScript mit NPM und Gulp organisieren first appeared on NET73.