3. Die Pug-API

Pug ist ein Paket das neben der Verarbeitung der Vorlagen einige Funktionen als Programmierschnittstelle (API) bereitstellt. Diese API wird nachfolgend kurz beschrieben.

3.1 API-Optionen

Jede Methode der API akzeptiert ein Optionen, die als JSON-Struktur übergeben werden:

 1 {
 2    filename: string,
 3    doctype: string, 
 4    pretty: boolean | string,
 5    self: boolean,
 6    debug: boolean,
 7    compileDebug: boolean,
 8    cache: boolean,
 9    compiler: class,
10    parser: class,
11    globals: Array.<string>
12 }

Die einzelnen Parameter haben folgende Bedeutung:

filename

Der Dateiname; wird beispielsweise in Ausnahmen angezeigt

doctype

Der Doctype, wenn dieser nicht als Teil einer Vorlage angegeben werden soll

pretty

Zeigt an, ob Leerzeichen zum ausgegebenen HTML hinzugefügt werden sollen, um lesbaren Code zu erzeugen. Wenn eine Zeichenkette angegeben wird, ist dies der Wert, der zum Einrücken benutzt wird, z.B. \t.

self

self-Namensraum für lokale Variable (standardmäßig false)

debug

Protokolliert Ausgaben nach stdout

compileDebug

Der Quellcode wird in die gerendete Ausgabe übertragen

cache

Funktionen werden gecachet. Schlüssel ist der Dateiname der Vorlage.

compiler

Ein alternativer Compiler kann angegeben werden.

parser

Ein alternativer Parser kann angegeben werden.

globals

Globale Variablen, die in allen Vorlagen bekanntgegeben werden

3.2 API-Funktionen

In allen Funktionen ist der Parameter options das zuvor beschriebene Options-Objekt. Nicht alle Optionen sind in allen Fällen sinnvoll.

Pug.compile(source, options)

Diese Funktion übersetzt Pug-Code, sodass dieser dann mehrfach mit verschiedene Werten ausgeführt werden kann. Gibt eine Funktion zurück, die ausgeführt werden kann. Der Befehl auf Zeile 2 erstellt die Funktion, auf Zeile 3 wird diese dann ausgeführt.

1 var *Pug* = require('*Pug*');
2 var fn = *Pug*.compile('p *Pug* ist cool!', options);
3 var html = fn(locals);

Dieses Skript erzeugt folgende Ausgabe:

1 <p>*Pug* ist cool!</p>

Pug.compileFile(path, options)

Diese Funktion übersetzt Pug-Code aus einer Datei, sodass dieser dann mehrfach mit verschiedenen Werten ausgeführt werden kann. Gibt eine Funktion zurück, die ausgeführt werden kann. sourcepath ist der Pfad zur Pug-Datei. Der Befehl auf Zeile 2 erstellt die Funktion, auf Zeile 3 wird diese dann ausgeführt.

1 var *Pug* = require('*Pug*');
2 var fn = *Pug*.compileFile('views/index.*Pug*', options);
3 var html = fn(locals);

Dieses Skript erzeugt folgende Ausgabe, wenn die Datei index.Pug** den Text “p Pug ist cool!” enthält:

1 <p>*Pug* ist cool!</p>

Pug.compileClient(source, options)

Hier wird eine JavaScript-Funktion gerendert, die dann später clientseitig ausgeführt werden kann und dort das erstellte HTML erzeugt.

1 var *Pug* = require('*Pug*');
2 
3 // Funktion erstellen
4 var fn = *Pug*.compileClient('p *Pug* ist cool!', options);
5 
6 // Rendern der Funktion
7 var html = fn(locals);

Die Rückgabe ist dann JavaScript:

1 function template(locals) { 
2   return "<p>*Pug* ist cool!</p>"; 
3 }

Pug.compileClientWithDependenciesTracked (source, options)

Diese Methode entspricht der vorhergehende methode compileClient, erzeugt jedoch ein Objekt, das folgende Struktur hat:

1 {
2   'body': 'function (locals) {...}',
3   'dependencies': ['filename.*Pug*']
4 }

Damit können Änderungen an Quelldateien überwacht werden. Ansonsten ist die einfache Variante zu bevorzugen.

Pug.compileFileClient(path, options)

Hier wird eine JavaScript-Funktion gerendert, die dann später clientseitig ausgeführt werden kann und dort das erstellte HTML erzeugt. Die Quelle muss als Datei vorliegen.

Das Options-Objekt hat einen weiteren Parameter name. Diese bestimmt den Namen der Funktion, die erzeugt wird und auf dem Client aufgerufen werden kann. Hier ein Beispiel mit einer Quelldatei *Pug*File.*Pug*:

1 h1 Dies ist eine Vorlage
2 h2 Von #{author}

Diese wird nun dynamisch übersetzt (Zeile 4):

1 var fs   = require('fs');
2 var *Pug* = require('*Pug*');
3 
4 var jsOut = *Pug*.compileFileClient('/views/*Pug*File.*Pug*', 
5    {
6       name: "templateFunction"
7    });

Nehmen Sie an, Sie wollen alle Ihre Vorlagen in eine einzige Datei übersetzen und diese dann an den Client übertragen. Dann kann die Ausgabe des letzten Beispiels jsOut folgendermaßen gespeichert werden:

1 fs.writeFileSync("templates.js", jsOut);

Die Datei templates.js, die daraus entsteht, enthält dann die oben definierte Funktion templateFunction:

 1 function templateFunction(locals) {
 2   var buf = [];
 3   var *Pug*_mixins = {};
 4   var *Pug*_interp;
 5 
 6   var locals_for_with = (locals || {});
 7 
 8   (function (author) {
 9     buf.push("<h1>Dies ist eine Vorlage</h1><h2>Von "
10       + (*Pug*.escape((*Pug*_interp = author) == null ? '' : \
11 *Pug*_interp))
12       + "</h2>");
13   }.call(this, "author" in locals_for_with ?
14     locals_for_with.author : typeof author !== "undefined" ?
15       author : undefined)
16   );
17 
18   return buf.join("");
19 }

Damit das funktioniert, muss auch die Laufzeitumgebung von Pug verfügbar sein. Sie steht unter dem Namen runtime.js zur Verfügung. Im HTML des Clients sieht das dann folgendermaßen aus:

 1 <!DOCTYPE html>
 2 <html>
 3   <head>
 4     <script src="/runtime.js"></script>
 5     <script src="/templates.js"></script>
 6   </head>
 7 
 8   <body>
 9     <h1>Dies ist eine Vorlage</h1>
10 
11     <script type="text/javascript">
12       var html = window.templateFunction({author: "Joerg"});
13       var div = document.createElement("div");
14       div.innerHTML = html;
15       document.body.appendChild(div);
16     </script>
17   </body>
18 </html>

Pug.render(source, options)

Diese Funktion rendert direkt in HTML:

1 var *Pug* = require('*Pug*');
2 var html = *Pug*.render('p *Pug* ist cool!', options);

Das HTML sieht nun so aus:

1 <p>*Pug* ist cool!</p>

Pug.renderFile(filename, options)

Auch diese Funktion rendert direkt in HTML, nutzt aber als Eingabe eine Datei:

1 var *Pug* = require('*Pug*');
2 
3 var html = *Pug*.renderFile('views/file.*Pug*', options);