Übersicht 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

Beschreibung von PlugIn's

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.

• 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.

Verwendung in Templates

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.

Verwendung im Content

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.

Übergebene Variablen

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.

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.

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

Ein Beispiel

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>

{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 -->.

<?
$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 18:40.
Sie haben die IP-Nummer 185.16.62.58.

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.