Read Pug - Die Template-Engine für node.js

Pug - Die Template-Engine für node.js

Jörg Krause

Inhaltsverzeichnis

PUG – die Template-Engine
1. Einführung in Pug
2. Sprachreferenz
3. Die Pug-API
- 3.1 API-Optionen
- 3.2 API-Funktionen
4. Die Kommandozeile
- 4.1 Installation
- 4.2 Benutzung und Optionen

PUG – die Template-Engine

Diese Bändchen beschreibt kompakt und übersichtlich die in der Express-Middleware standardmäßig eingesetzte Template-Engine Pug. Express gehört zum Node.js-Stack. Das heißt, alle hier gezeigten Beispiele und Kommandos sind nur in einer Node.js-Umgebung lauffähig.

Pug ist ehemals unter dem Namen JADE veröffentlicht worden. Die Umbenennung wurde aufgrund von Copyright-Streitigkeiten notwendig.

Zielgruppe

Dieses Bändchen wendet sich an Anfänger und an Webentwickler, die neu in der MEAN-Welt sind. MEAN steht für “MongoDb Express AngularJs Node” und bezeichnet eine komplett auf JavaScript basierendes Entwicklungs-Ökosystem. Pug ist eine Option für die Erstellung von Ansichten in Express.

Vielleicht sind Sie aber auch ein Webdesigner, der JavaScript als eine hervorragende Möglichkeit entdeckt hat, seine Webseiten mit dynamischen Elementen aufzuwerten. Dabei haben Sie mit Texten zu tun, mit Formularen, mit der Darstellung von Datenbankinhalten, also alles, was eine dynamische Website ausmacht. Dann wird Ihnen dieses Bändchen einen der Teilaspekte, nämlich das Erzeugen des HTML auf dem Server, in besonders übersichtlicher Form zeigen.

Auf alle Fälle habe ich mich bemüht, keine Voraussetzungen an den Leser zu stellen. Sie müssen kein Informatiker sein, keine Programmiersprache perfekt beherrschen, keine höhere Mathematik kennen. Egal in welchem Zusammenhang Sie auf Pug gestoßen sind, Sie werden diesen Text lesen können.

MEAN

Um alle Beispiele nachvollziehen zu können, benötigen Sie eine lauffähige Node.js-Umgebung. Diese wird auch als “MEAN” (MongoDb, Express, AngularJs, Node) bezeichnet. Pug ist die standardmäßig benutzte Template-Engine der Middleware- und Routingkomponente Express. Ein weiteres Bändchen der Reihe “Jörgs Webbändchen” widmet sich Express und natürlich steht auch eine Einführung in node.js selbst bereit.

Wenn Sie diesen Text zufällig gefunden haben und mit dem Begriff “MEAN” nichts anfangen können, lesen Sie es trotzdem. Sie werden eine der modernsten Techniken der Webentwicklung kennenlernen und künftig gehören Sie zum Kreis hervorragender Entwickler, die hochperformante und zukunftsorientierte Websites bauen.

Was Sie wissen sollten

Leser dieser Reihe müssen kaum Voraussetzungen mitbringen. Etwas HTML kann nicht schaden und wer schon mal eine statische HTML-Seite gesehen hat (den Quellcode natürlich) kommt sicher gut rein. Ich gehe davon aus, dass Sie wenigstens ein aktuelles Windows-System haben. Sie können die Umgebung direkt auf Windows installieren oder auf Linux. Wenn Sie Windows 8 oder 10 haben, können Sie die Hyper-V-Umgebung nutzen, um darauf ein Ubuntu-Linux zu installieren. Es ist einfacher als Sie denken und auf jeden Fall einen Versuch wert.

Wie Sie diesen Text lesen können

Ich will Ihnen nicht vorschreiben, wie Sie diesen Text lesen sollten. Beim ersten Entwurf der Struktur habe ich mehrere Varianten ausprobiert und dabei festgestellt, dass es die ideale Form nicht gibt. Wenn ich mich an den verschiedenen Anwendungsarten orientiere, zerfällt der Text in mehrere Kapitel, die nicht im Zusammenhang miteinander stehen. Der eine oder andere Leser würde sich dann ärgern, dass er viel Geld für ein Buch ausgibt, das nur zu einem Fünftel verwendbar ist. Diese Bändchen löst das Problem, indem es auf ein sehr kleines Thema fokussiert ist und kein “bla-bla” zur Aufblähung des Umfangs dabei ist.

Anfänger sollten den Text als Erzählung lesen, von der ersten bis zur letzten Seite. Wer sich schon etwas auskennt, kann die für ihn weniger interessanten Abschnitte gefahrlos überspringen. Falls Bezüge notwendig sind, habe ich entsprechende Querverweise eingefügt.

Schreibweisen

Das Thema ist satztechnisch nicht einfach zu beherrschen, denn Skripte sind oft umfangreich und es wäre schön, wenn man die beste Leseform optisch unterstützen könnte. Ich habe deshalb oft zusätzliche Zeilenumbrüche benutzt, die der Lesbarkeit dienen, im Editor Ihrer Entwicklungsumgebung aber nichts zu suchen haben.

Generell wird jeder Programmcode mit einer nicht proportionalen Schrift gesetzt. Außerdem verfügen Skripte über Zeilennummern:

1 function test(d){
2   return (d != undefined);
3 }

Wenn Sie etwas am Prompt oder in einem Dialogfenster eingeben müssen, wird dieser Teil der Anweisung fett geschrieben:

$ npm start

Ausdrücke und Befehlszeilen sind manchmal mit allen Arten von Zeichen gespickt und in fast allen Fällen kommt es auf jedes Zeichen an. Besonders das Leerzeichen ist nicht, wie in anderen Programmiertexten, beliebig verwendbar. Sie müssen genau so viele Zeichen eingeben, wie angegeben sind. Damit Sie Leerschritte richtig erkennen, werden diese wo es darauf ankommt mit dem Symbol • gekennzeichnet (ein kleiner Punkt in der Mitte der Zeile):

1 grep –w /^\\s*(•?)+/

Oft werde ich die Verwendung bestimmter Zeichen in einem solchen Ausdruck genau erläutern (ich lasse Sie wirklich nicht mit solchen Zeichenschlangen allein). Dann werden die “wichtigen” Zeichen durch Zeilenumbrüchen alleingestellt und auch in diesem Fall werden Zeilennummern dazu dienen, das betroffene Symbol im Text exakt zu referenzieren (Beachten Sie das #-Zeichen in Zeile 6):

1 !!! 5
2   html(lang='en')  
3     head  
4   title= title  
5   body!= body  
6     div#navigation!= partial('navigation.pug')

Jade nutzt Einrückungen zur Struktur. Die Leerzeichen am Anfang einer Zeile haben eine semantische Bedeutung. Die Schrift ist nicht-proportional, sodass die Zeichen abzählbar sind.

Symbole

Um die Orientierung bei der Suche nach einer Lösung zu erleichtern, gibt es eine ganz Palette von Symbolen, die im Text genutzt werden.

Über den Autor

Jörg arbeitet als Trainer, Berater und Softwareentwickler für große Unternehmen weltweit. Bauen Sie auf die Erfahrung aus 25 Jahren Arbeit mit Web-Umgebungen und vielen, vielen großen und kleinen Projekten.

Jörg sind vor allem solide Grundlagen wichtig. Statt immer dem neuesten Framework hinterher zu rennen wären viele Entwickler besser beraten, sich eine robuste Grundlage zu schaffen. Wer dies kompakt und schnell lernen will ist hier richtig. Auf seiner Website www.joergkrause.de sind viele weitere Informationen zu finden.

Jörg hat über 60 Titel bei renommierten Fachverlagen und im Eigenverlag texxtoor in Deutsch und Englisch verfasst, darunter einige Bestseller.

Kontakt zum Autor

Neben der Website können Sie auch direkten Kontakt über www.IT-Visions.de aufnehmen. Wenn Sie für Ihr Unternehmen eine professionelle Beratung zu Web-Themen oder eine Weiterbildungsveranstaltung für Softwareentwickler planen, kontaktieren Sie Jörg über seine Website oder buchen Sie direkt über http://www.IT-Visions.de.

1. Einführung in Pug

Pug ist eine Template-Engine für Express, der Middlware- und Routing-Lösung für Node.js. Sie ist der Standard für Express. Wenn Sie sich also intensiv mit Node.js und Express auseinandersetzen, führt kein Weg an Pug vorbei.

1.1 Übersicht

Pug nutzt eine vereinfachte Darstellung der HTML-Seite durch simple Textbefehle. Praktischerweise entsprechen diese den Namen der HTML-Tags. Da HTML eine Hierarchie aufbaut und Pug keine schließenden Tags kennt, muss die Baumstruktur anders entstehen. Pug nutzt dazu Einrückungen im Texteditor. 2 Leerzeichen zeigen an, dass das folgende Element ein Kindelement ist.

Vorbereitung

Pug setzt voraus, dass Sie mit node.js arbeiten und die Middleware Express nutzen. Der einfachste Weg zu einer funktionierenden Umgebung geht über ein schrittweises Abarbeiten der Bausteine einer node.js-Installation.

Damit steht die Umgebung, und der Beschäftigung mit Pug steht nichts im Weg.

Installationsanleitung

Zur Installation gibt es wenig Besonderheiten. Pug benötigt Express. Falls dies mit der Videoanleitung bereits installiert wurde, kann dieser Schritt überprungen werden. Ansonsten folgen Sie der Schrittfolge hier.

Installieren Sie nun das Pug-Paket. Ich habe meine Projekte unter /home/joerg/Apps und für dieses Bändchen dann unter Pug abgelegt. Legen Sie dann einen Ordner views an, in dem eine erste Testseite entstehen wird (sie befinden sich in Apps):

1 mkdir Pug
2 cd Pug
3 npm install express
4 npm install Pug
5 npm init
6 npm install express --save
7 mkdir views

npm init erstellt die Node.js-Applikation. Dabei wird eine Paket-Datei erzeugt, deren Werte interaktiv abgefragt werden. Die erzeugte Paket-Datei kann noch manuell angepasst werden.

Legen Sie in dem neu erstellten Applikationsverzeichnis Pug eine Datei mit dem Namen index.js an. Sie hat folgenden Inhalt:

1 var express = require('express');
2 var app = express();
3 
4 app.get('/', function (req, res) {
5   res.send('Hallo Express!');
6 });
7 
8 var server = app.listen(3000, function () {});

Starten Sie nun den Node-Server:

1 npm start

Geben Sie nun im Browser auf dem Entwicklungssystem folgende URL ein: http://localhost:3000. Sie sollten dann die “Hallo Express!”-Ausgabe sehen.

1.2 Applikationsstruktur

Express bietet eine Reihe spannender Funktionen. Ich will hier jedoch nur auf Pug eingehen und deshalb ist das manuelle Erzeugen und nutzen einer View einfacher. Lesen Sie “Jörgs Webbändchen” zu Express, um mehr über die Applikationsstruktur herauszufinden.

Die einfachste Nutzung von Pug besteht aus zwei Bausteinen. Zum einen die erste View, index.pug:

Datei: index.pug

1 doctype html
2 html(lang='en')  
3   head  
4     title= title  
5   body!= body  
6     h1= title

Zum anderen wird das “Hallo Express”-Beispiel so verändert, dass nun statt des statischen Texts die View benutzt wird:

Datei: index.js

 1 var express = require('express');
 2 var app = express();
 3 app.set('view engine', 'pug');
 4 
 5 app.get('/', function (req, res) {
 6   res.render('index', { 
 7     title: 'Hallo pug!' 
 8   });
 9 });
10 
11 var server = app.listen(3000, function () {});

Zum einen wird hier Pug als Standard vereinbart, sodass keine Dateierweiterung angegeben werden muss und das passende Modul vorab geladen werden kann. Dies passiert durch:

app.set('view engine', 'pug');

Dann wird statt res.send die Funktion res.render benutzt. Der erste Parameter ist der Name der View, der ohne Pfad (standardmäßig wird im view-Ordner gesucht) und ohne Dateierweiterung (standardmäßig wird nun pug benutzt) angegeben werden kann. Der zweite Parameter ist ein Objekt, dass lokale Variablen für die View bestimmt. Jede Eigenschaft des Objekts wird als lokale Variable bereitgestellt. Im Beispiel ist das der Wert title.

1.3 Pug-Views

Statt HTML schreiben Sie ab jetzt die Ansichtsseiten in pug. Noch einmal das eben benutzte Beispiel:

Datei: index.pug

1 doctype html
2 html(lang='en')  
3   head  
4     title= title  
5   body!= body  
6     h1= title

Auf jeder Zeile der View steht zuerst ein HTML-Tag. Statt der Schreibweise in XML-Form (<title></title>) nimmt Pug hier eine vereinfachte Darstellung.

title= title

Der linke Teil ist das HTML-Element. Es folgt ein Gleichheitszeichen, dass die Kodierung bestimmt, also die Behandlung von HTML-spezifischen Entitäten wie < oder >. Dann folgt JavaScript. Da eine lokale Variable mit dem Namen title vereinbart wurde, wird dieser Ausdruck hier hingeschrieben. Analog funktioniert das mit h1, dass unterhalb des body-Elements steht. Der Umgang mit body zielt darauf ab, dass Views üblicherweise auf Stammseiten (Layout- oder Master-Seiten) basieren und der eigentliche Inhalt über die Variable body (rechts im Ausdruck) zugeordnet wird. Da HTML aus einer Seite direkt übernommen werden soll, wird der Operator != benutzt, der nicht codiert.

Umgang mit Teil-Ansichten

Teil-Ansichten (partial views) erlauben das Strukturieren von Views. Eine Pug-View sieht beispielsweise folgendermaßen aus:

Datei: index.pug

1 doctype html
2 html(lang='en')  
3   head  
4     title= title  
5   body!= body  
6     include navigation
7     h1= title

Mit dem Befehl include wird eine weitere View eingebunden, navigation.pug. Beachten Sie, dass diese ohne Anführungszeichen und Klammern angegeben wird.

Diese Navigation wird nun in einer weiteren Datei erstellt: views/navigation.pug:

Datei: navigation.pug

1 div#navigation
2   a(href='/') home

Umgang mit Layout-Seiten

Eine Layout-Seite ist ein Master, eine Stammseite deren Inhalte von Inhaltsseiten bestimmt werden. Das entspricht der Layout-Seite in ASP.NET MVC oder der Master-Seite in ASP.NET.

Eine Layout-Seite sieht beispielsweise folgendermaßen aus:

Datei: index.pug

1 doctype html
2 html(lang='en')  
3   head  
4     title= title  
5   body!= body  
6     include navigation

Dies unterscheidet sich in kaum von dem vorherigen Beispiel. Lediglich das h1-Element am Ende fehlt.

Im nächsten Schritt wird die Inhaltsseite erstellt. Sie heißt views/content.pug:

Datei: content.pug

1 extends index
2 
3 h1= title
4   a(href='http://www.joergkrause.de/') Jörg &lt;Is A Geek&gt;\
5  Krause

Sie verweist auf die Layout-Seite. Nun wird das Startskript angepasst, denn Pug rendert zuerst die Inhaltsseite, die ihrerseits die Layout-Seite aufruft.

Datei: index.js

 1 var express = require('express');
 2 var app = express();
 3 app.set('view engine', 'pug');
 4 
 5 app.get('/', function (req, res) {
 6   res.render('content', { 
 7     title: 'Hallo Pug!' 
 8   });
 9 });
10 
11 var server = app.listen(3000, function () {});

Beachten Sie die res.render-Funktion, die nun content statt vorher index aufruft (Zeile 5).

Jetzt kann der node-Server gestartet werden (im Ordner wo die Datei package.json steht):

npm start

Soweit der Standardport nicht anderweitig vergeben wurde zeigt der Browser die gerenderte HTML-Seite nun an:

http://127.0.0.1:3000/

Der Einstiegspunkt ist der Aufruf von res.render mit dem Argument der Inhaltsseite, content.pug. Die Engine sorgt dann für das Laden der Layout-Seite und die Verarbeitung. Der gesamte Vorgang findet also auf dem Server statt.

Dabei fällt auf, dass die Navigation verschwunden ist. Das ist das normale Verhalten. Denn nun wurde der Inhalt des body-Elements tatsächlich durch eine Inhaltseite geliefert und damit wird der statische Inhalt überschrieben. Freilich gibt es hier einige Optionen, dieses Verhalten zu verändern. Dies wird in der Sprachreferenz genau beschrieben.

2. Sprachreferenz

Im Folgenden finden Sie eine systematische Sprachreferenz basierend auf der Original-Dokumentation. Der Einstieg in die online verfügbaren Informationen ist Github.