From 5b5b5d8c3aef8ba0b7a04e458f5396ba6f96aad2 Mon Sep 17 00:00:00 2001 From: Sebastian Frank Date: Tue, 19 Feb 2019 15:18:37 +0100 Subject: [PATCH] templates doku --- main.go | 1 + .../03_Benutzung/04_Templates/README.md | 348 ++++++++++++++++++ .../03_Benutzung/04_Templates/config.yml | 3 + 3 files changed, 352 insertions(+) create mode 100644 website/content/de/01_Navigation/03_Benutzung/04_Templates/README.md create mode 100644 website/content/de/01_Navigation/03_Benutzung/04_Templates/config.yml diff --git a/main.go b/main.go index d39349a..ca9cc4e 100644 --- a/main.go +++ b/main.go @@ -474,6 +474,7 @@ RewriteRule ^$ %{REQUEST_URI}`+goToFixed+`/ [R,L] // read yaml header as data for template ctx := make(pongo2.Context) + ctx["This"] = newConfig.This ctx["Meta"] = newConfig.Meta ctx["Data"] = newConfig.Data ctx["NavMap"] = navMap diff --git a/website/content/de/01_Navigation/03_Benutzung/04_Templates/README.md b/website/content/de/01_Navigation/03_Benutzung/04_Templates/README.md new file mode 100644 index 0000000..57828b8 --- /dev/null +++ b/website/content/de/01_Navigation/03_Benutzung/04_Templates/README.md @@ -0,0 +1,348 @@ +# Templates + +Templates werden über das pongo2-Paket gerendert. Dieses nutzt die Template-Sprache **Django-Template**. + +Sämtliche Template-Dateien sind im Ordner `templates` zu speichern. +Die Endung kann frei gewählt werden. Für diese Dokumentation und auch als Grundlage für Beispiele wurde `.html` gewählt, da somit auch das Syntax-Highlighting gegeben ist. + +## grober Überblick + +Nachfolgend ist ein Beispiel eines Templates: + +```django + + + + + {{ Meta.Title }} + + + + + + + {% block header %} +
+
+ {% for nav in NavSlice %} + {{ nav.Navname }} + {% endfor %} +
+
+ +
+ {% endblock %} + + + {% block breadcrumb %} + + {% endblock %} + + {% block content %} +
+ {{ Body }} +
+ {% endblock %} + + {% block footer %} + + {% endblock %} + + + + +``` + +Wie im Beispiel zu sehen ist, werden einfache **Variables** über: + +```django +{{ Variable }} +``` + +eingebunden. Variablen können außerdem speziell weiterverarbeitet werden. Dies geschieht mit sogenannten Filtern oder Filterfunktionen. Die Syntax dafür ist folgendermaßen: + +```django +{{ Variable|Filter }} +``` + +Blockanweisungen dagegen verwenden zum Beispiel folgende Platzhalter: + +```django +{% if Variable %} + ... +{% endif %} +``` + +Eine Liste der in Django möglichen Anweisungen finden Sie unter [Django builtins](https://docs.djangoproject.com/en/2.1/ref/templates/builtins/). + +--- + +## mark2web Variablen + +Der mark2web-Generator liefert für die Template-Verarbeitung Variablen für die Navigation und den Inhalt. + +### Website-Inhalt + +Das rohe HTML, welches aus einer Markdown-Datei generiert wird steht über folgende Variablen zur Verfügung. + +```django +{{ Body }} = komplettes HTML aus der Markdown-Datei +{{ BodyParts.0 }} = erster HTML-Block +{{ BodyParts.1 }} = zweiter HTML-Block +usw. +``` + +Ist die Markdown-Datei durch `---` auf einer Zeile (nach den Kopfdaten) geteilt, stehen die Einzelteile im Slice/Array `{{ BodyParts }}` zur Verfügung. + +Aus folgender Markdown-Datei `README.md` in einem `content`-Unterverzeichnis: + +```markdown + # Titel 1 + + Text 1 + + --- + + ## Titel 2 + + Text 2 +``` + +wird für `{{ Body }}` folgendes HTML: + +```html +

Titel 1

+

Text 1

+
+

Titel 2

+

Text 2

+``` + +`BodyParts` erklärt sich an folgendem Template: + +```django + + + {% for part in BodyParts %} + + {% endfor %} + +
+ {{ part }} +
+``` + +Aus dem Template wird nach dem Rendern mit obiger Markdown-Datei also folgendes HTML: + +```html + + + + + +
+

Titel 1

+

Text 1

+ 		+

Titel 2

+

Text 2

+
+``` + +Die Einrückungen im HTML wurden für die bessere Lesbarkeit angepasst. Wie zu sehen ist, wird `---` in `{{ Body }}` laut Markdown-Syntax zu `
`. In `{{ BodyParts.N }}` ist es jedoch nicht enthalten, da es hier nur zur Trennung des Dokuments dient. + +### Navigation + +Jedes Navigationselement steht intern in folgender go-Struktur zur Verfügung: + +```go +type navElement struct { + Navname string + GoTo string + Active bool + + Data interface{} + + This ThisPathConfig + + SubMap *map[string]*navElement + SubSlice *[]*navElement +} + +``` + +Diese erste Navigationsebene wird mit seinen Unternavigationspunkten zum einen auf die Variable `{{ NavMap }}` in Form einer Map (assoziatives Array) mit dem umgeformten Namen (wie im Zielverzeichnis) abgebildet. +Außerdem steht die erste Navigationsebene als Liste, bzw. Slice (Array) über die Variable `{{ NavSlice }}` zur verfügung. + +Wird z.B. folgende Navigation als Zielverzeichnis-Struktur angenommen: + +```plain +de + main + home + leistungen + referenzen + service + impressum +en + main + home + ... +``` + +Der Teasertext aus folgender `config.yml` im `content`-Verzeichnis `de/main/02_Leistungen` + +```yaml +This: + Data: + teaser: Teasertext +``` + +welcher zum Navigationspunkt im Zielpfad *de/main/leistungen* gehört, ist über folgende Template-Variablen erreichbar: + +```django +{{ NavMap.de.SubMap.main.SubMap.leistungen.This.Data.teaser }} + +oder + +{{ NavSlice.0.SubSlice.0.SubSlice.1.This.Data.teaser}} + +oder auch eine Kombination + +{{ NavMap.de.SubMap.main.SubSlice.1.This.Data.teaser }} +``` + +Natürlich wird diese Variable in der Form so nie verwendet, sondern soll nur den Aufbau der Struktur verdeutlichen. Üblicherweise werden Schleifenblöcke verwendet um die Navigationsbäume auszugeben, wie z.B. eine Liste als Sprachwähler, wenn man annimmt, dass die erste Navigationsebene die Website-Sprache ist: + +```django + +``` + +Wie im Beispiel zu sehen ist, wird das aktive Navigationselement mit `class="active"` über die Variable `Active` aus der Struktur markiert. + +#### aktiver Navigationspfad + +Der aktive Navigationspfad ist über eine weitere vorbelegte Variable zu erfahren: + +```django +{{ NavActive }} +``` + +Ähnlich wie `{{ NavSlice }}` oder `{{ ...SubSlice }}` ist dies ein Slice/Array welches als Elemnte Navigationselemente aus oben angegebener Struktur enthält. +Im Gegensatz zu `{{ NavSlice }}` besteht die Liste nicht aus Elementen einer Ebene, sonder aus allen aktiven Elemtenten in des aktuellen Pfads. + +Geht man also wieder vom obigen Beispiel aus und der aktive Pfad ist *de/main/leistungen*, so würden folgendes zutreffen: + +```django +{{ NavActive.0 }} ist das Navigationselement für "de" +{{ NavActive.1 }} ist das Navigationselement für "main" +{{ NavActive.2 }} ist das Navigationselement für "Leistungen" +``` + +Somit lassen sich leicht Pfade anzeigen, bzw. Breadcrumbs in die Website einbinden, wie im folgenden Beispiel: + +```django +aktiver Pfad: + {% for nav in NavActive %} + {{ nav.Navname }} + {% endfor %} +``` + +Ebenso lässt sich bei mehrsprachigen Seite immer die richte Hauptnavigation zur aktuelle Sprache laden: + +```django +

Hauptnavigation

+ + +``` + +### Meta-Angaben + +Über die Variablen + +```django +{{ Meta.Title }} +{{ Meta.Description }} +{{ Meta.Keywords }} +``` + +stehen die üblichen Meta-Angaben für die Verwendung im `` Tag zur Verfügung. + +### weitere Daten + +Die Variablen + +```django +{{ This.Navname }} +{{ This.Data }} +{{ Data }} +``` + +stehen ebenfalls zur Verfügung und spiegeln die Daten aus den Konfig-Dateien `config.yml` und den Kopfdaten der Markdown-Datei wieder. \ No newline at end of file diff --git a/website/content/de/01_Navigation/03_Benutzung/04_Templates/config.yml b/website/content/de/01_Navigation/03_Benutzung/04_Templates/config.yml new file mode 100644 index 0000000..d279373 --- /dev/null +++ b/website/content/de/01_Navigation/03_Benutzung/04_Templates/config.yml @@ -0,0 +1,3 @@ +This: + Data: + teaser: Aus Markdown wird HTML \ No newline at end of file