Kleine Ursachen…

Am Beispiel einer WordPress-Seite wird gezeigt, wie man die Programmdokumentation in einer eigenen Seite „Technik“ integrieren kann und damit dem altersbedingten Gedächtnisschwund ein bisschen entgegenwirken kann.

---

Ein junger Mann hat die HTL-Matura als einziger seiner Klasse mit Auszeichnung bestanden. Eine Auszeichnung für ihn und für sein häusliches Lernumfeld. Da muss man gratulieren und sich mitfreuen. Wir waren aus diesem Anlass zu einer kleinen Feier eingeladen.

Um diesen einmaligen Erfolg – immerhin gabs etwa 20 andere Mitkonkurrenten um eine Auszeichnung – zu unterstreichen, wollte ich dem Ausgezeichneten ein weniger schönes Maturazeugnis – mein eigenes – zeigen, und da ich alles online dokumentiere, versuchte ich meine Seite http://matura.fiala.cc am Handy zu öffnen, doch die Seite zeigte sich zugeknöpft und zeigte nichts. (Einige Wochen zuvor war noch alles in Ordnung.)

So hat die Seite seinerzeit ausgeschaut, wie sie nach einer „Erstversorgung“ nach dem Ausfall wieder zu sehen war.

Die Seite hat seit etwa 13 Jahren fehlerfrei funktioniert, doch nach einem Serverupdate funktionierten die alten Programme nicht mehr. Natürlich könnte man die Programme mit einem gewissen Aufwand wiederherstellen, doch entspricht die Seite ohnehin nicht mehr dem Anspruch, auf allen Endgeräten gleich gut dargestellt zu werden. Wenn man also Arbeit investiert, sollte sie wenigstens zukunftsorientiert sein. Daher entschloss ich mich, die Seite mit WordPress komplett neu aufzubauen.

Wer nur an dem Ergebnis interessiert ist: Hier ist das „weniger schöne“ Maturazeugnis aus dem Jahr 1966: http://matura.fiala.cc/zeugnis in einer responsive-Version.

Ich kann nunmehr dem sehr erfolgreichen Absolventen der HTL-Ungargasse zeigen, wie gut sein Zeugnis ist.

---

Aufbau der Website

Die Seite ist eigentlich ein digitales Klassenbuch von der ersten Klasse bis heute. Bei jedem Zusammentreffen unseres Jahrgangs gibt es einen Eintrag in der Chronik (Tabelle chronik) und alle Teilnehmer (Schüler und Lehrer, Tabelle namen) werden im Klassenbuch (Tabelle klassenbuch) als „anwesend“ markiert. Die Seiten sind daher Auszüge aus einer Datenbank mit den Tabellen namen, chronik und klassenbuch.

Auf die im Hintergrund arbeitende MS-SQL-Datenbank wurde in der alten Version direkt zugegriffen und am Server die HTML-Seiten konstruiert und die komplette Seite an den Client geschickt.

In der aktuellen Version werden in einem ersten Schritt aus der SQL-Datenbank in der Datei matura-db.js die drei JSON-Tabellen angelegt; die Formatierung der Seiten erfolgt ausschließlich clientseitig über JavaScript.

In alle Seiten dieses Webs werden folgende Dateien inkludiert:

• matura.css enthält StyleSheets, die das frühere Layout nachempfinden.
• matura-db.js ist die JSON-Entsprechung der Datenbanktabellen
• matura-common.js enthält Funktionen, die auf mehreren Seiten verwendet werden.

Wie aber werden diese Dateien in eine WordPress-Seite eingefügt? Ich verwende dazu das für diesen Zweck kostenlose PlugIn Code Snippets von WP Code.

Seite	Programm für diese Seite
Schule
Lehrer
Klassenvorstand
Schulzeit	matura-schulzeit.js
Zeugnis
Chronik	matura-chronik.js
Privat	matura-adressen.js
Technik

Die etwa eine Woche dauernde Entwicklungsarbeit überspringe ich und möchte nur auf die letzte Seite „Technik“ hinweisen, die alle beteiligten Programme zeigt, und zwar auch dann, wenn sich etwas an diesen Dateien ändern sollte, weil der Code nicht in händisch in die Seite eingefügt wurde, sondern per JavaScript/jQuery in das Dokument eingebettet wird und sich Änderungen daher automatisch abbilden.

Seite „Technik“

Meine zahlreichen Projekte sind nicht in einer einheitlichen Technik ausgeführt, sondern veränderten sich im Laufe der Zeit je nach Interesse. Es ist daher mit einem gewissen Aufwand verbunden, die Funktionsweise früher „Geistesblitze“ nach Jahren zu rekonstruieren. Ich habe daher bei diesem Projekt „Matura“ eine eigene Seite „Technik“ angehängt, die alle verwendeten Dateien dokumentiert.

Die Schwierigkeit der Dokumentationsarbeit ist aber, dass ein Projekt selten so statisch ist, dass die Dateien unverändert bleiben. Und kaum ändert man etwas, muss man genaugenommen auch die Dokumentation ändern, und das ist etwas, das meist der Bequemlichkeit zum Opfer fällt. Die Dokumentationsseite „Technik“ listet daher keine statischen Codeseiten, sondern inkludiert die Codeseiten in der WordPress-Seite.

In jeder Seite dieses Webs werden einige Bibliotheken eingefügt, aber – wie gesagt – kann sich bei solchen Entwicklungen immer wieder etwas ändern und daher müsste man diese Änderungen immer auch in der Dokumentation nachziehen. Gesucht ist also eine Technik, die alle zusätzlich eingefügten Bibliotheken korrekt anzeigt. Eine Seite, die alle beteiligten Elemente dokumentiert ist http://matura.fiala.cc/technik.

Damit alles hübsch formatiert ist, wird die Bibliothek PrismJs verwenden. Auch diese Seite nutzt diese Bibliothek. Wie das funktioniert, wird im Beitrag Syntax Highlighting gezeigt.

Einbettung des Source-Code der Datei matura-chronik.js

<div id="matura-chronik"></div>
<script>
   DrawFile("https://iam.at/d/matura/matura-chronik.js","matura-chronik","javascript")
</script>

Die Funktion DrawFile() findet man in der Datei matura-common.js, die auf jeder Seite eingebettet wird.

function DrawFile(url, selector, language) {
	$.get(url,function(data){
		data = data.replace(/&/g,"&")
		data = data.replace(/</g,"&lt;")
		data = data.replace(/>/g,"&gt;")
		$("#"+selector).html('<pre><code class="language-'+language+'">'+data+'</code></pre>')
	})
}

In dieser Datei werden die Zeichen &, < und > durch &, < und > ersetzt und das Ergebnis in einem HTML-Objekt namens selector gespeichert.

Die dargestellte Datei matura-chronik.js schaut mit diesen Hilfsmitteln wie folgt aus:

function GetTeilnehmer(event) {
	var html = ""
	var arr_Name = []
	for (var k=0; k<klassenbuch.length; k++) {
		if (klassenbuch[k].ID_CHRONIK == event) {
			arr_Name.push(klassenbuch[k].n)
		}
	}
	var l = ""
	var s = ""
	for (var i = 0; i < namen.length; i++) {
		if (arr_Name.includes(namen[i].n)) {
			var name1 = namen[i]
			if (name1.LEHRER=="False")
				s += (s=="" ? "" : " &middot; ") + GetNameFormatiert(name1)
			else
				l += (l=="" ? "" : " &middot; ") + GetNameFormatiert(name1)
		}
	}
	html += "<div class=\"row\"><div class=\"col\">"
		+ s +"<br/><br/>" + l 
		+"</div></div>"
	arr_Name.splice(0,255)
	return html
}
function GetChronik() {

	SortNamen()
	SortKlassenbuch()
	SortChronik()

	var s = ""
	var alte_klasse_jahr = ""
	for (var e=0; e<chronik.length; e++) {
		var event1 = chronik[e]
		var klasse_jahr = event1.X
		if (klasse_jahr==alte_klasse_jahr) klasse_jahr = ""
		else alte_klasse_jahr = klasse_jahr
		s += "<tr>"
		s += "<td style='font-size:20pt !important;'>" + klasse_jahr + "</td>"
		s += "<td>" + event1.JAHR + "-" 
			+ (event1.MONAT=="0" ? "" : "-" + event1.MONAT.padStart(2,'0'))
			+ (event1.TAG=="0" ? "" : "-" + event1.TAG.padStart(2,'0')) + "</td>"
		s += "<td><strong>" + event1.WAS + "</strong><br/>" + event1.WO +"<br/>"
			+ GetTeilnehmer(event1.ID_CHRONIK)
			+ "</td>"
		s += "</tr>\n"
	}
	$("#chronik").html(s)
}
GetChronik()

Achtung: die hier dargestellte Datei ist – im Gegensatz zu der Version auf der Seite „Chronik“ von http://matura.fiala.cc/chronik – statisch und verändert sich nicht, wenn sich mit einer eventuellen späteren Änderung.

Header

Damit man diese Zeilen auch findet, wurde der Beginn der Einfügungen mit <!--1--> und das Ende mit der Zeile <!--2--> markiert. Die Funktion, die diese Einbettung erledigt, heißt DrawMyHead(), man findet sie in der Datei matura-common.js.

Hinweise

Die Seite matura.fiala.cc wird laufend erweitert, es kann daher sein, dass das sowohl Inhalte als auch das Aussehen sich im Laufe der Entwicklung noch verändern.

Die Code-Dateien werden auf dieser Seite zur Laufzeit, während des Ladens der Seite eingefügt. Daher muss die PrismJS-Bibliothek nach dem vollständigen Laden der Seite noch einmal aufgerufen werden. Das geschieht mit folgendem Code-Block:

<script>
$(document).ready(function() {
    Prism.highlightAll()
})
</script>

Ergänzung

2013-07-21: Die Seite matura.fiala.cc hat sich seit der Erstellung dieses Artikels weiterentwickelt und daher stimmen verschiedene Hinweise in diesem Artikel nicht mehr. Es gibt aber eine Dokumentationsseite, mit der man die einzelnen Komponenten des Webs nachvollziehen kann: http://matura.fiala.cc/matura-8ab66/dokumentation/