Template-Parser zur Darstellung dynamischer Webseiten in PHP

(ATP Version 3.06/2010-09-08)

Inhalt

1	Allgemeines

2.	Struktur der Platzhalter
2.1.	Marker-Tags
2.2.	Text-Pattern

3.	Transformation von Links

4	Bereitstellung der Variablen und Funktionen
4.1.	Marker-Funktionen und Variablen
4.2.	Hilfsfunktionen

5.	Arbeitsweise des Parsers

6.	Hinweise zur php-Programmierung
6.1.	Session-Verwaltung
6.2.	zeitlicher Ablauf der Abarbeitung der Funktionen
6.3.	Hinweise zur Strukturierung der Anwendungsfunktionen

7.	vorbereitete Funktionen
7.1.	Funktionen zur Verwendung mit Marker-Tags
7.2.	Funktionen zur Verwendung in Text-Pattern

8.	vordefinierte Variablen

	Anhang A: History

1. Allgemeines

Für die Realisierung von WWW-Inhalten sollen Design und veränderliche Inhalte getrennt werden, wie das z.B. auch von Content-Management-Sytemen (CMS) her bekannt ist.

Dabei wird folgende Funktionalität realisiert:

Das Design einer Internet-Seite soll mit Hilfe üblicher Web-Designwerkzeuge erstellt werden und aus mehreren Seiten (Dateien) bestehen können
Die das Design definierenden HTML-Dateien werden als Template-Satz bezeichnet ún sind so strukturiert, daß sie völlig unabhängig von der späteren Verwendung durch den Parser mit normalen HTML-Entwurfswerkzeugen getestet und dargestellt werden können
Dynamisch zu verändernde Elemente des HTML-Codes werden im Einsatzfall durch den Parser an gekennzeichneten Stellen vor Ausgabe an den Web-Browser modifiziert.
Zu modifizierende HTML-Quelltext -Abschnitte werden durch einschließende spezielle Marker-Tags gekennzeichnet
Zu modifizierende #CDATA-Angaben werden durch spezielle Platzhalter (Pattern) festgelegt
Links auf externe Ziele werden nicht verändert
Links auf Recourcen (alle ausser Html) innerhalb des Template-Satzes werden mit dem Pfad auf das Template-Verzeichnis erweitert
Links auf Html-Dateien mit relativer Pfadangabe werden als Parser-Aufruf umgesetzt

Für eine Web-Anwendung werden damit drei Komponenten benötigt:

der Template-Parser, gewöhnlich als index.php in einem Stammverzeichnis
Anwendung-Funktionen, die in einem Unterverzeichnis gespeichert sind
Ein Template-Satz, der in einem Unterverzeichnis mit dem Namen dieses Satzes unterhalb der Anwendungsfunktionen als Menge von html- und weiteren Dateien wie Bildern, Multimedia-Recourcen u.ä. abgelegt ist

Datenquellen für die in den Templates einzufügenden Inhalte können sein:

einfache Variablen
Arrays
Funktionen

Die Funktionen werden als php-Dateien bereitgestellt. Mindestend eine Funktion namens "Init()" muss vorhanden sein, die vom Parser immer als erstes (vor allen anderen Aktionen) aufgerufen wird.

In einer Konfigurationsdatei ({name}.conf, Standard: 'atp.conf') wird der Name der zu startenden Anwendung festgelegt:

Variablenname	Beschreibung	Beispiel	Standard-Wert
sAppDir	Verzeichnis, in dem die Anwendungsdateien abgelegt sind	opac-test	application
sAppName	Name des Funktionspaketes	OPAC	Anwendung

Der Name der Anwendung kann dem Parser auch per Parameter "App" übergeben werden.

Beispiel:
index.php?app=Test

damit wird die Test.conf gesucht, ausgewertet und die darin definierte Anwendung gestartet.

Ebenfalls kann das zu verwendende Template übergeben werden:
Beispiel:
index.php?tpl=index.html

2. Struktur der Platzhalter

Zur transparenten Kennzeichnung der zur verändernden Dateibereiche dienen zwei Arten von Platzhaltern (Content-Marker):

2.1. Marker-Tags

Diese Form wird eingesetzt, wenn ganze HTML-Quelltextbereiche modifiziert werden sollen. Dabei werden Pärchen von Marker-Tags benutzt: jeweils ein Start- und ein End-Tag:

allgemein: <atp {VAR|FKT}=bezeichner PAR=bezeichner >(beliebiger html-Inhalt)</atp>
Beispiel: : <p class="wospru"><atp FKT=Wochenspruch >An dieser Stelle wird der Spruch der Woche eingeblendet</atp></p>
Der Parameter 'PAR' kann auch entfallen, wenn nicht benötigt

Der Bereich zwischen den Marker-Tags wird vom Parser ersetzt oder modifiziert. Im Debug-Modus bleiben die Marker-Tags im modifizierten HTML-Quelltext stehen.

Ist eine Variable ein Array, werden alle Array-Elemente eingesetzt.

Im Fall eines Funktionsaufrufes wird der zwischen <atp ...> und </atp> stehende Quelltext an die Funktion übergeben.

Mit Marker-Tags markierte Bereiche sollen schachtelbar sein. Die inneren Bereiche müssen zuerst aufgelöst werden.
Beispiel:
<atp FKT=Test1 >(html-Inhalt1)<atp FKT=Test2 >(html-Inhalt2)</atp>(html-Inhalt3)</atp>
Zuerst wird im Beispiel die Funktion Test2 mit dem (html-Inhalt2) aufgerufen, danach die Funktion Test1 mit dem neuen Html-Text, der u.a. auch die Ausgabe der Funktion 2 enthält.

2.2. Text-Pattern

Diese Form wird eingesetzt, wenn #CDATA-Werte modifiziert werden sollen.

@ATP {VAR|FKT}=BEZEICHNER @

Da die Zeichenfolge '@ATP' auch in normalem Text vorkommen kann muss sie im Template als '\@ATP' geschrieben werden. normale '\' werden als '\\' geschrieben und vom Parser in einfache Backslashes umgesetzt.

Beispiel:

z.B. in init.php:
$_SESSION['aAtpVars']['Test'] = "(Inhalt der Variablen Test)";

...

Template-Quelltext vor der Abarbeitung: <input value="@ATP VAR=Test @" ... >
Quelltextnach der Verarbeitung: <input value="(Inhalt der Variablen Test)" ... >

Die Text-Pattern werden nach Abarbeitung der Marker-Tags behandelt.

3. Transformation von Links:

3.1. Transformation von Dokumenten-Links

Die Template-Dateien besitzen die Endung '.html'. Verweise zwischen ihnen lauten auf diese Namen. Da die dem Browser zu präsentierenden URL's aber auf die verarbeitende php-Datei verweisen müssen, werden Attribute, die URL's enthalten, über einen speziellen Marker-Tag (Link-Marker) vorgegeben, der immer direkt vor dem zu modifizierenden Tag platziert wird:

Zur Link-Transformation werden die fest hinterlegten Funktionen "HREF", "SRC", "ACTION" und "DATA" genutzt.

Dem bezeichnetem Attribut entnimmt der Parser den Namen der Template-Datei, der als Parameter 'tpl' übergeben wird. Weitere Parameter werden vom Parser beibehalten.

Beispiele:
aus
<atp FKT=HREF ><a ... href="suche.html?(parameterliste)" ... >...</atp>
entsteht
<a ... href="index.php?tpl=suche.html&{parameterliste}... >...

aus
<atp FKT=ACTION ><form ... action="tuwas.html" ... >...</atp>
entsteht
<form ... action="index.php... ><input type="hidden" name="tpl" value="tuwas.html" />...

Das hidden-Input-Feld wird benötigt, damit der Name der Template-Datei als Parameter mitgesendet wird.

3.2. Transformation von Rescourcen-Links

Ungekennzeichnete, relative Rescourcen-Adressen werden so umgesetzt, dass der relative Pfad von index.php ausgehend ersetzt wird. URL's , die mit "/" oder (protokoll):// beginnen, werden nicht verändert.

Beispiel: <IMG ... src="images/bild1.jpg" ... > wird umgesetzt in z.B. <IMG ... src="(templateverzeichnis)/images/bild1.jpg" ... >
oder: <LINK ... href="./style/style.css" ... > wird umgesetzt in z.B. <LINK ... href="(templateverzeichnis)/style/style.css" ... >

Die Link-Transformation wird nach Abarbeitung der Content-Marker durchgeführt.

Tag	behandeltes Attribut
a	href
link	href
img	src
script	src
object	data

4. Bereitstellung der Variablen und Funktionen

4.1. Marker-Funktionen und Variablen

Die Initialisierung geschieht über eine Init()-Funktion, die in der Datei init.php des Funktionspaketes enthalten ist.

Die init.php wird vom Parser automatisch eingebunden (include) und enthält die include-Anweisungen für die weiteren benötigten Funktionen. Die enthaltene Init()-Funktion wird vom Parser als erstes aufgerufen und ermöglicht die Initialisierung des Funktionspaketes.

Die Variablen werden über ein assoziatives Array aAtpVars bereitgestellt, dass in $_SESSION abgelegt wird.
Beispiel: Bezeichner aus Pattern ist "Otto": $_SESSION['aAtpVars']['Otto']

4.2. Hilfsfunktionen

Zum bequemen Zugriff auf diese Variablen dienen folgende Funktionen, die im eigenen PHP-Code verwendet werden können:

bool AtpVIsset (string $sName)
bool AtpVSet (string $sName, mixed $mValue)
mixed AtpVGet (string $sName)
bool AtpVUnset (string $sName)

Weitere verfügbare Hilfsfunktionen sind:

String RQ (String $v) - liefert $_REQUEST-Wert oder Leerstring
String RVar (String $s) - ermittelt Variable aus $_REQUEST (Vorrang) oder ATP-Umgebung

Ein detailiertere Beschreibung der internen Funktionen gibt es hier:

5. Arbeitsweise des Parsers

Im Normalfall heißt der Parser "index.php", der folgende Aktionen ausführt:

Suche und Einlesen der Konfigurationsdatei (Standard: atp3.conf im gleichen Verzeichnis)
Einbinden der init.php der Anwendung
Aufruf der Funktion init() der Anwendung
weiter s. Abschn.6.2.

6. Hinweise zur php-Programmierung:

6.1. Session-Verwaltung

Bei der Programmierung von Funktionen für den Parser ist folgendes zu beachten:

session.auto_start() darfen nicht verwendet werden, damit in init.php noch Klassendefinitionen geladen werden können, die für Objekte der Session gelten.
session_start() wird an geeigneter Stelle in init.php an einer Stelle platziert, an der alle Klassendefinitionen bereit erfolgt sind.

6.2. zeitlicher Ablauf der Abarbeitung der Funktionen

Zeitliche Reihenfolge der Abarbeitung der Programmkomponenten

1.	Initialisierung des Parsers (Einlesen der Konfigurationsdatei, Initialisieren der parsereigenen Variablen
2.	Auswertung der parserbezogenen Aufrufparameter (GET- oder POST-Variablen), z.B. tpl
3.	Ausführung der globalen Inhalte der init.php der eingebundenen Anwendung
4.	Ausführung der Funktion init() aus der init.php der eingebundenen Anwendung
5.	Einlesen der zu verwendenden Template-Datei (Standardwert oder aus tpl-Parameter)
6.	Auflösung aller Marker-Tags - hier angegebene Funktionen werden in dem Moment abgearbeitet, in dem die Marker-Tags aufgelöst werden. Geschachtelte Marker-Tags werden von innen nach außen aufgelöst.
7.	Auflösung aller Text-Pattern - angegebene Funktionen werden abgearbeitet (wie 6.)
8.	Transformation der Recourcen-Links
9.	Ausgabe des Ergebnisses (Übergabe des generierten HTML-Textes an den Client-Browseer)

6.3. Hinweise zur Strukturierung der Anwendungsfunktionen

Variablen, die in den Platzhaltern verwendet werden, müssen entweder schon in der Session vorhanden sein, oder müssen in der init.php belegt werden, Das kann z.B. in Abhängigkeit von einem übergebenen Parameter geschehen
Funktionen, die in den Platzhaltern angegeben werden, werden in dem Moment abgearbeitet, in dem die Platzhalter im Template aufgelöst werden.
Text-Pattern-Variablen können auch durch von in Marker-Tag-Platzhaltern verwendeten Funktionen belegt werden, da die Auflösung der Text-Pattern nach der Abarbeitung der Funktionen aus Tag-Markern erfolgt.
Tag-Marker können geschachtelt werden. Sie werden von innen nach aussen aufgelöst, was bedeutet, dass die in äusseren Tags verwendeten Funktionen die Ausgabe der inneren Tags "sehen" .
Funktionen, die in Text-Pattern verwendet werden, sind parameterlos.

7. vorbereitete Funktionen

7.1. Funktionen zur Verwendung mit Marker-Tags

FKT	PAR	Beschreibung
HREF		konvertiert href-Attibut des eingeschlossenen Tags so, dass der Parser mit dem Inhalt des Attributs als Parameter "tpl" aufgerufen wird
SRC		konvertiert src-Attibut des eingeschlossenen Tags so, dass der Parser mit dem Inhalt des Attributs als Parameter "tpl" aufgerufen wird
ACTION		konvertiert action-Attibut des eingeschlossenen Tags so, dass der Parser mit dem Inhalt des Attributs als Parameter "tpl" aufgerufen wird
DATA		konvertiert data-Attibut des eingeschlossenen Tags so, dass der Parser mit dem Inhalt des Attributs als Parameter "tpl" aufgerufen wird
ARR	Array-Name	ersetzt im HTML-Quelltextabschnitt Platzhalter der Form ##bezeichner## mit den korrespondierenden Inhalten des Arrays Beispiel: $_SESSION[aAtpVars][Test] = (abc => Hallo, def => Otto); aus <atp FKT=ARR PAR=Test ><b>##abc## ##def##!</b></atp> entsteht <ATP FKT="ARR" PAR="Test"><b>Hallo Otto!</b></ATP> im Debug-Modus oder <b>Hallo Otto!</b> bei DEBUG=0
ARR2	Array-Name	wie Funktion ARR, aber für 2-dimensionales Array; Der Quelltext wird sooft dupliziert, wie die erste Dimension des Array Elemente hat Ist das Array leer, wird der Quelltext unterdrückt. Die Platzhalter haben die gleiche Struktur, wie die für die Funktion ARR verwendeten.
SETCLASS	Variablenname	Setzt den Klassennamen des eingeschlossenen Tags neu.
VISIBILITY	Variablenname	Setzt VISIBILITY-Wert des style-Atrributs des eingeschlossenen Tags neu: Der Inhalt der per PAR bezeichneten Variablen wird wie folgt verwendet: -1 - VISIBILITY wird 'hidden' gesetzt 0 - VISIBILITY -Eigenschaft wird entfernt 1 - VISIBILITY wird 'visible' gesetzt
HIDDEN	Variablenname	veraltet; Synonym für VISIBILITY
SHOW	Variablenname	läßt Code stehen, wenn Variable gesetzt ist.
BLANK	Variablenname	unterdrückt Code, wenn Variable gesetzt ist

7.2. Funktionen zur Verwendung in Text-Pattern

(noch keine)

8. vordefinierte Variablen

VAR	Beschreibung
ATPVER	Version des Template.Parsers Beispiel: 3.07.04
DATE	Datum im Format "[T]T.[M]M.YYYY"
WEEKDAY	aktueller Wochentag
MONTH	aktueller Monatsname
sTplDir	relativer Pfad des Template-Verzeichnisses (ohne abschl. "/" !)
TIME	liefert die aktuelle Zeit im Format 'hh:mm:ss'
UHR	liefert die aktuelle Uhrzeit im Format 'hh:mm Uhr'

Anhang A: History

V3.06:

Neue vordefinierte Variablen:

ATPVER
sTplDir
TIME
UHR
REMOTE_ADDR
HTTP_USER_AGENT
HTTP_ACCEPT_CHARSET
SERVER_NAME

Neue Marker-Tag-Funktionen:

DATA
VISIBILITY; ersetzt HIDDEN (HIDDEN wird ab Version 4 nicht mehr unterstützt)

V3.05:

Neue Marker-Tag-Funktionen:

SHOW()
BLANK()

V3.04:

Als Marker-Tags werden ab dieser Version <atp ...> </atp> verwendet.
Neue Funktionen:

AtpVIsset()
SETCLASS()
HIDDEN()
RQ()
RVar()

V3.03:

Neu: vordefinierte Variablen DATE, WEEKDAY und MONTH
Doku: Begriff "Kommentar-Marker" in "Marker-Tags" geändert
Neu: Funktionen AtpVSet(), AtpVUnset() und AtpVGet()

V3.02:

Tag "<script> in link-Transformation einbezogen
Funktion ARR2 ergänzt

V3.01:

Kommentar-Tags: attribut "PAR" ergänzt
Unterstützung für Ausgabe von Arrays ergänzt
Funktion "SRC" ergänzt

V3.00:

neu definiert und codiert

Version 3.03.1/2010-02-10