{PROJECT} ../../template/doc.de.ini
{ROBOTS}INDEX, FOLLOW
{DESCRIPTION}PlugIns stellen eine Schnittstelle zum Kernel von phpCMS dar. Mit PlugIns können Programmierer Funktionen von phpCMS nutzen oder Erweiterungen in phpCMS einbauen. Hier wird beschrieben, wie das geht.
{MENU} 00.06.08
{TITEL} PlugIn's bei phpCMS
{PLUGIN FILE="$home/doc/doc_de/time_user.php" TYPE="DYNAMIC"}

{CONTENT}

Diese Seite ist für Programmierer. Wenn Du kein Programmierer bist, laß Dich nicht abschrecken
und lies auf den anderen Seiten weiter. Du mußt diese Funktionen von phpCMS nicht nutzen!

Beschreibung von PlugIn's
Verwendung in Templates
Verwendung im Content
Übergebene Variablen
Ein Beispiel





PlugIn's stellen eine Schnittstelle zum Herzen von phpCMS dar. Bei Skripteinbindung
wird die Ausgabe des Skriptes sofort an den Browser weitergegeben. PlugIn's sind
dazu gedacht, Werte zwischenzuspeichern und dann später, bei oder nach dem Parsen
auszugeben, oder Werte des Dokumentes zu verändern.


Vorteile von PlugIn's gegenüber der Skripteinbindung:

(statische) Rückgabewerte können gecached werden.
(statische) Rückgabewerte können gziped werden.
Felder vom CONTENT-Dokument können zur Laufzeit geändert werden.
Globale Einstellungen, wie Proxy-Cache-Zeit oder Client-Cache können
für diese Seite überschrieben werden.
Einbindung im Template und in der Content-Datei möglich.
Einsatz von Headern möglich.

Nachteile von PlugIn's gegenüber der Skripteinbindung:

Eigene Skripte müssen stärker angepaßt werden.
Genauere Kenntnis des Anwenders von PHP, Cache und phpCMS ist erforderlich.
Globale Variablen können zwar gelesen werden, für die Neuanlage muß aber
$GLOBALS[] benutzt werden, da das PlugIn innerhalb einer Funktion abgearbeitet wird.
Skripte werden im global-scope von PHP abgearbeitet.
Caching von Seitenteilen, wie bei Skripten wird nicht unterstützt.



Wenn Ihr selbst PlugIn's für phpCMS geschrieben habt und diese sind
auch für andere User von Nutzen, schickt mir diese PlugIn's.
Ich werde diese dann auf dieser Homepage unter Nennung Eures Namens
veröffentlichen.





Wenn Ihr PlugIn's in Templates einsetzt, werden diese bei jeder Seite
ausgeführt, die mit diesem Template erstellt wurde. Sinnvoll ist
ein solcher Einsatz z.B. bei PlugIn's, die das Erstellungsdatum
der Seite ausgeben oder Keywords für die Meta-Tags erzeugen.
PlugIn's im Template werden an jener Stelle ausgeführt, wo sie notiert sind.
Wenn Ihr also z.B. mit dem PlugIn TAGS ändert und das PlugIn wird erst am Ende
einer Seite notiert, wirkt diese Änderung nur für jene Inhalte,
die nach dem PlugIn im Template notiert werden.


Der korrekte Aufruf eines PlugIn's aus einem Template lautet:

{PLUGIN FILE="Pfad_zum_PlugIn/PlugIn.php" TYPE="DYNAMIC"}

Das Schlüsselwort "FILE" bezeichnet den Pfad wo das PlugIn abgelegt ist.
Im Pfad kann die Variable "$home", und es können
relative oder absolute Pfade benutzt werden. Wobei mit "absolut" nicht
der absolute Pfad zum Root-Directory des Rechners gemeint ist, sondern
der Pfad relativ zum Web-Server-Root. Relativ hingegen bezeichne ich Pfade,
die relativ zum Dokument (in diesem Fall das Template) angegeben sind.


Das Schlüsselwort "TYPE" bestimmt, ob das PlugIn einmal ausgeführt wird,
oder ob es bei jedem Aufruf der Seite erneut abgearbeitet werden soll.
Mögliche Werte dafür sind "DYNAMIC" und "STATIC".
Hat ein PlugIn den Typ "DYNAMIC" zugewiesen erhalten, wird es bei
jedem Aufruf der Seite abgearbeitet. Sowohl der Client-Cache als
auch die Speicherung auf Proxy's oder der Chache von phpCMS wird unterbunden.
Ihr könnt alle Einstellung im PlugIn selbst beeinflußen. Dazu später mehr.
Beim Typ "STATIC" bleiben alle Einstellung, wie global in phpCMS geregelt, erhalten.


Bei beiden Schlüsselwörtern muß der Wert in Hochkommata (") stehen.


Eventuelle Ausgaben des PlugIn's werden an jener Stelle im Template
eingefügt, an der das PlugIn aufgerufen wurde. Ausgaben dürfen nur
in den PlugIn-Buffer geschrieben werden.





Der Vorteil vom Einsatz im Content ist, daß individuell in jeder Seite
entschieden werden kann, ob ein PlugIn zum Einsatz kommt oder nicht.
Es muß dann kein spezielles Template angelegt werden. Ein weitere
Vorteil ist, daß das PlugIn vor dem Parsen des Dokuments
ausgeführt wird. Die Inhalte der CONTENT-Datei sind zu diesem Zeitpunkt
bereits eingelesen, es wurden aber noch keine TAGS vertauscht
und Menüs oder Templates abgearbeitet.


Der Aufruf erfolgt in der gleichen Notation wie im Template, jetzt
allerdings in der CONTENT-Datei.


Produziert das PlugIn eine Ausgabe, muß diese wieder in den
PlugIn-Buffer geschrieben werden. Allerdings müssen wir nun
im Template einen Platzhalter definieren, an dessen Stelle
die Ausgabe des PlugIn's geschrieben wird:

{CONTENT_PLUGIN_0}

PlugIn's werden, bei 0 beginnend, in der Reihenfolge durchnummeriert, in der
sie in der CONTENT-Datei notiert sind. Das Schlüsselwort
"CONTENT_PLUGIN_" leitet den Platzhalter ein, danach folgt die
Nummerierung.


Produziert das PlugIn keine Ausgabe oder verändert das PlugIn
lediglich den Feldwert eines anderen Contentfeldes in der
CONTENT-Datei, ist es nicht erforderlich einen Platzhalter im
Template zu notieren. Das PlugIn wird trotzdem ausgeführt.


Ist im Template ein Platzhalter für ein Content-PlugIn
vorhanden, aber in der CONTENT-Datei kein PlugIn notiert,
wird dieser Platzhalter einfach ignoriert. Das bedeutet,
Ihr könnt ohne Bedenken in einem Standard-Template einen
Platzhalter definieren und nur in jenen CONTENT-Dateien
das PlugIn notieren, wo Ihr es ausführen wollt.






PlugIn's können auf alle Variablen Zugreifen, die im
Global-Scope des Parsers vorhanden sind. Also auch auf jene Werte,
die mit einem GET- oder POST-Request an die Seite gesendet
wurden, auf das Array HTTP_COOKIE_VARS usw.


Zusätzlich werden dem PlugIn folgende Variablen vom Parser
übergeben, deren Inhalt verändert werden kann:

$PageContent

Der gesamte Inhalt der CONTENT-Datei. Die Variable ist ein ARRAY of ARRAY of STRING.
Mit dem jeweiligen Namen des Feldes in der CONTENT-Datei kann auf den
Inhalt des Feldes der CONTENT-Datei zugegriffen werden. Wenn also z.B.
in der CONTENT-Datei das Feld {TITEL} notiert ist, wird mit
"$PageContent->TITEL[0]" auf den Inhalt der ersten Zeile dieses Feldes
zugegriffen. Achtung: Alle Felder werden als Array angesprochen,
auch wenn der Inhalt nur ein Wert ist!


$CacheState

Diese Variable ist ein String und kann die Werte "on" und "off" haben.
Damit wird das Verhalten des Caches von phpCMS gesteuert. Ist der Wert
auf "on" wird der Inhalt des Dokumentes nach dem Parsen im Cache von
phpCMS abgelegt. Steht der Wert auf "off" wird die Datei nicht abgelegt,
aber Achtung: Existiert bereits eine Datei gleichen Namens
im Cache, wird diese nicht automatisch gelöscht! Wenn Ihr also Änderunge
vornehmt (z.B. durch Einbindung eines PlugIn's im Template) müßt Ihr überprüfen,
ob die Datei im Cache gelöscht ist.


$ClientCache

Diese Variable ist ein String und kann die Werte "on" und "off" haben.
Damit wird das Verhalten von Proxy-Servern und Browser-Caches gesteuert.
Bei "on" wird gecached, bei "off" nicht.


$ProxyCacheTime

Diese Variable ist ein String. Der Inhalt dieser Variablen
wird zur momentanen Zeit addiert und bezeichnet den Wert,
wann die Seite vom Client erneut angefordert werden muß.
Die Angabe erfolgt in Sekunden. Beispiel Ablauf nach einem Tag:

$ProxyCacheTime = 1 * 60 * 60 * 24



$Tags

Diese Variable ist ein Array of Arrays of Strings. Die Inhalte
sind jene TAGS, die im TAG-File definiert sind, ergänzt um jene
TAGS, die phpCMS standardmäßig zur Verfügung stellt. Es können
am Ende neue TAGS angefügt werden oder bestehende TAGS geändert
werden. Der Aufbau:

$Tags[Zähler][0] = Zu tauschender Wert;
$Tags[Zähler][1] = Wert auf den zu tauschen ist;

Zähler ist die laufende Nummer des Tags.


$PluginBuffer

Ist ein ARRAY of STRING. Der PluginBuffer dient zur Übergabe von
Ausgaben an phpCMS. Wird nur ein Wert übergeben, muß dennoch
in das erste Element dieses Arrays geschrieben werden. Bei Verwendung
von Plugin's im Template, wird der Inhalt vom PluginBuffer an der
Stelle ausgegeben, an der das PlugIn notiert ist. Bei PlugIn's
in der CONTENT-Datei, wird der Inhalt vom PluginBuffer dort ausgegeben,
wo im Template der entsprechende PLatzhalter mit der laufenden Nummer
dieses PlugIn's notiert ist.


$CHECK_PAGE->path

Der Pfad jener Datei die gerade geparsed wird,
relativ zum Root des Webservers.


$CHECK_PAGE->name

Der Name jener Datei die gerade geparsed wird.



Funktionen, die von phpCMS zur Verfügung gestellt werden:

string = $PHP->GetDocRoot()

Liefert das Root-Directory des Webservers auf dem phpCMS ausgeführt wird.
Ich habe beim Programmieren festgestellt, dass die Umgebungsvariable
$DOCUMENT_ROOT nicht in allen Konfigurationen auf dieses
Directory zeigt. Deshalb habe ich diese Funktion geschrieben.


string = $PHP->Version($number)

Liefert die Versionsnummer von PHP. $number ist dabei
1,2,3 oder 4. Wenn z.B. die Version 4.0.2pl1 läuft und der
Parameter "1" übergeben wird, wird der String "4" zurückgeliefert.
Wird der Parameter "4" übergeben wird "pl1" zurückgeliefert.
In der Version 3 von PHP gibt es noch keine solche Funktion.


string = $PHP->API()

Wird "mod" zurückgeliefert, läuft PHP als Server-API,
liefert diese Funktion "cgi" zurück wird PHP als
CGI ausgeführt.


string = $PHP->OS()

Wird "win" zurückgeliefert, kommt Windows als
Betriebssystem zum Einsatz,
liefert diese Funktion "nix" zurück läuft der Server unter
einer Unix oder Linux Version. Ist der Rückgabewert
nicht gesetzt, läuft ein anderes Betriebssystem.


Wenn Ihr also mit PHP auf jene Datei zugreifen wollt,
die gerade geparsed wird, erhaltet Ihr die erforderliche
Pfad- und Namensangabe mit folgendem Aufruf:

$Datei = $PHP->GetDocRoot().'/'.$CHECK_PAGE->path.'/'.$CHECK_PAGE->name;






Wir bauen jetzt ein PlugIn, das die Zeit und die IP-Nummer des Betrachters ausgibt.
Das Plugin wird wahlweise in der Content-Datei eingebunden, also nur auf jenen
Seiten ausgegeben, die auch die Notation in der Content-Datei haben.
Es werden dabei die Tags <!-- PLUGIN:TIME_USER time --> und
<!-- PLUGIN:TIME_USER ip --> ersetzt.


Template:

<html>
<body>
{MENU NAME="MAIN"}
<h1>Überschrift</h1>
{CONTENT}
</body>
</html>


CONTENT-Datei:


{PROJECT} /irgendwo/project.ini
{MENU} 00.01.01
{PLUGIN FILE="/irgendwo/time_user.php" TYPE="DYNAMIC"}
{CONTENT}
Es ist jetzt <!-- PLUGIN:TIME_USER time -->.
Sie haben die IP-Nummer <!-- PLUGIN:TIME_USER ip -->.


PLUGIN (time_user.php):


<?
$current = count($Tags);
$Tags[$current][0] = '<!-- PLUGIN:TIME_USER time -->';
$Tags[$current][1] = date ( "H:i" , time () );
$Tags[$current+1][0] = '<!-- PLUGIN:TIME_USER ip -->';
$Tags[$current+1][1] = $REMOTE_ADDR;
?>



Auf unserer Seite wird nun folgendes ausgegeben:

Es ist jetzt .
Sie haben die IP-Nummer .

Wenn es gerade ist und Du die IP-Nummer hast. :-)


Achtung: Vor dem öffnenden (<?) und nach dem schließenden (?>) PHP-Tag dürfen
weder Leerzeilen noch Leerzeichen notiert sein. Der Parser bricht sonst mit einer
häßlichen Fehlermeldung ab.