Live-Seiten: Unterschied zwischen den Versionen

Aktuelle Version vom 12. November 2009, 12:22 Uhr

Beschreibung

Als Live-Seiten werden SPML-Seiten bezeichnet, die in einem Publikationsbereich generiert werden und somit, wie auch PHP-Seiten, in einer Website aufgerufen werden.

Um SPML-Seiten in einem Publikationsbereich ausführen zu können, muss dieser als IES-Modul aktiviert sein.

SPML-Seiten mit Fullpage-Template

Die einfachste Art eine SPML-Liveseite zu erzeugen, ist über ein Fullpage Template. Verwenden Sie dazu bitte das im Basis-Paket des IES enthaltene Template Fullpage (spml). Dieses Template stellt für die Eingabe ein Textfeld bereit, in dem der SPML-Code eingetragen werden kann. Für die Ausgabe erzeugt das Template zu dem eingegebenen SPML-Code noch zusätzliche notwendige Setzungen.

Legen Sie einen Seiten-Artikel mit diesem Template an und tragen Sie in das Textfeld z.B. folgenden Code ein:

<sp:print name="system.page.name"/>

Publizieren Sie den Artikel und rufen Sie die generierte Seite auf. In der Seite ist nun der Name des Artikels enthalten. Das Objekt system.page steht nur in generierten SPML-Seiten zur Verfügung.

Bei der Erzeugung von SPML-Seiten über das Fullpage-Template ergibt sich jedoch ein Nachteil. Der in dem Textfeld eingetragene SPML-Code wird 1 zu 1 in die zu generierende SPML-Seite geschrieben. SPML-Code der zum Generierungszeitpunkt ausgeführt werden soll, kann nicht angegeben werden. Ist dies jedoch notwendig, müssen die SPML-Seite über andere Templates erzeugt werden.

SPML-Seiten mit benutzerdefinierten Templates

Je nach Anwendungsfall kann es auch sinvoll sein, den SPML-Code zunächst in ein Template zu schreiben, so dass jeder Artikel der dieses Template verwendet, den SPML-Code enthält. Da SPML aber auch für die Template-Sprache selbst verwendet wird, ist darauf zu achten, dass SPML-Code, der nicht zur Generierungszeit der Seite ausgeführt werden soll, in <sp:code>-Tags stehen muss. Code innerhalb dieser Tags wird zur Generierungszeit ignoriert und direkt in die Seite geschrieben. Dieser SPML-Code wird dann erst bei Aufruf der Seite ausgeführt.

So ist es möglich, Teile die zur Generierungszeit fest stehen, schon beim Erzeugen der Seite zu ermitteln und nur die 'echten' Liveanteile der SPML-Seite beim Aufruf auszuführen.

Im Out-Teil des Templates muss als erstes der Tag spt:spml eingebunden werden, da dieser den notwendigen SPML-Header in die Seite schreibt. Hierbei ist es wichtig, dass vor dem spt:spml-Tag kein Zeichen generiert wird. In den so generierten Seiten kann mit system.page auf das Page-Objekt zugegriffen werden.

<sp:io type="in">
   ...
</sp:io><sp:io type="out"><spt:spml/>
   ...
   <sp:code>
      SPML-Code der uninterpretiert in die Seite geschreiben wird.<br>
      Uhrzeit: <sp:print name="system.now" dateformat="HH:mm:ss"/>
   </sp:code>
</sp:io>

IES Nutzer anmelden

Um Daten des IES lesen und schreiben zu können ist ein angemeldeter Nutzer nötig. Mit dessen Rechten wird entschieden, ob bestimmte Daten gelesen, oder geschrieben werden dürfen.

Es gibt mehrere Möglichkeiten einen Nutzer anzumelden:

Über ein Login-Formular, das an den LoginHandler (siehe LoginHandler) gesendet wird.
Mit Hilfe von sp:login
Implizit über die Modul-Konfiguration
Über Basic-Authentication

Login über ein Formular

Über den LoginHandler können Nutzer mit Hilfe von Formular-Feldern angemeldet werden. Dazu wird ein solches Formular verwendet.

<sp:form name="beliebig" uri="${pageAfterLogin}" handler="com.sitepark.ies.control.jsp.handler.LoginHandler" method="post">
  Login: <input name="SYS_LGIN_login"><br>
  Passwort: <input name="SYS_LGIN_password" type="password"><br>
  <input name="SYS_LGIN_client" type="hidden" value="clientanchor"/>
  <input type="submit"/>
</sp:form>

<sp:loop collection="system.error" item="it">
  ERROR: <sp:print name="it.key"/>: <sp:print name="it.value"/><br>
</sp:loop>
<sp:loop collection="system.fatal" item="it">
  FATAL: <sp:print name="it.key"/>: <sp:print name="it.value"/><br>
</sp:loop>

Mit sp:form wird das Formular erzeugt. Mit uri wird angegeben, welche Seite nach dem ausgeführten Login aufgerufen werden soll. Mit handler wird der LoginHandler angegeben, um das Login durchzuführen. Die für den LoginHandler erforderlichen Felder SYS_LGIN_login, SYS_LGIN_password und SYS_LGIN_client müssen mit angegeben werden. Für SYS_LGIN_client kann entweder die Client ID oder der Anchor des Clients verwendet werden.

Um zu verhindern, dass Seiten aufgerufen werden können, ohne dass ein Nutzer angemeldet ist, können bestimmte Seiten geschützt werden. Weiterhin sollten im Fehlerfall (ungültiger Login, Aufruf einer geschützten Seite von einem nicht angemeldeten Nutzer) eine definierte Seite aufgerufen werden. Dazu ist in der Konfigurationsdatei DOCUMENT_ROOT/WEB-INF/ies-module.xml des entsprechenden Publikationsbereich folgendes einzutragen:

<ies-module ...>
  ...
  <web>
    <security-constrains>
      <allowed pattern="/login.spml" />
      <denied pattern="/.*" />
    </security-constrains>
    <exception url-pattern=".*">
      <catch class=".*" uri="/login.spml" />
    </exception>
  </web>
</ies-module>

<security-constrains>

Hier wird definiert welche Seiten ohne Login aufgerufen werden dürfen:

<allowed pattern="/login.spml" />

Der Aufruf von login.spml ist immer erlaubt.

<denied pattern="/.*" />

Alle anderen Seiten dürfen nicht aufgerufen werden.

Hierbei ist noch zu beachten, dass nur die Seiten geschützt werden, die vom IES ausgeführt/ausgeliefert werden (HTML-Seiten, PHP-Seiten, Bilder, CSS, ... gehören in der Regel nicht dazu). Je nach Konfiguration der Weiterleitungen (mod_jk, proxy_ajp) sind das möglicherweise nur *.spml und *.jsp Dateien.

<exception>

Werden Seiten von nicht angemeldeten Nutzern aufgerufen, wird von der Seite eine AccessDeniedException aufgerufen. Um diese Fehler allgemein zu verarbeiten, wird angegeben, für welche URLs welche Exception möglich sind und welche Seite danach aufgerufen werden soll. Hier werden für alle Seiten, alle Exception abgefangen und anschließend /login.spml aufgerufen.

Nach einer Änderung der Datei ies-module.xml muss das entsprechende Publisher-Modul neu geladen werden. Damit werden die Änderungen dann wirksam (Siehe Administration des IES).

Daten über Liveseiten erzeugen, ändern und löschen

Wie IES-Module können auch Liveseiten Daten im IES erzeugen, ändern und löschen. Dazu werden Handler angesprochen, die über HTTP GET- bzw. POST-Parameter gesteuert werden.

Artikel anlegen und ändern

Um einen Artikel über eine Liveseite anzulegen, muss der InformationHandler verwendet werden. Dieser wird über seinen vollen Klassennamen com.sitepark.ies.control.jsp.handler.InformationHandler angesprochen. Siehe InformationHandler.

Die Artikeldaten können z.B. in einem Formular eingegeben und anschließend an den IES gesendet werden. Der Handler führt dann die notwendigen Aktionen aus. Die SPML-Seite stellt anschließend die Ergebnisse dar.

Die Minimalanforderungen, um einen Artikel anlegen oder ändern zu können, sind:

Es muss ein Nutzer angemeldet sein, der die nötigen Rechte hat, einen Artikel in einem Pool anzulegen
Um einen neu angelegten Artikel direkt darzustellen, muss die Variable SYS_element mit dem Wert von SYS_INFE_id gesetzt werden. In SYS_INFE_id wird die ID des neu angelegten Artikels gesetzt. SYS_element definiert das aktuelle Element

<sp:set name="SYS_element" object="SYS_INFE_id"/>

Nur wenn diese Variable gesetzt ist, kann auf den aktuellen Artikel mit system.information zugegriffen werden.

Um einen Artikel zu ändern, muss das Feld SYS_INFE_id mit der zu ändernden Artikel-ID und SYS_INFE_action mit dem Wert update mitgesendet werden.
Um einen Artikel zu erzeugen, müssen die Felder SYS_INFE_articleType für den Typ des Artikels (Artikel, Medium, Resource), SYS_INFE_action mit dem Wert create und SYS_INFE_target mit der ID des Pools, in dem der Artikel angelegt werden soll, mitgegeben werden.
Für den Artikel muss mit dem Feld SYS_INFE_name ein Name angegeben werden.

Damit wird ein Artikel angelegt oder geändert, kann aber noch nicht mit InfoSite weiter bearbeitet werden. Dazu fehlen noch einige Steuerfelder, die von InfoSite benötigt werden, um in dessen Umgebung lauffähig zu sein. Bei den noch nötigen Feldern handelt es sich um Content-Felder, die mit Hilfe von sp:hidden erzeugt werden können.

Die Felder entsprechen den Angaben für den Artikelpool in der Artikelpoolverwaltung von InfoSite5, in dem der Artikel angelegt werden soll.

Da sich die Werte auf den Pool, in dem der Artikel abgelegt werden soll beziehen, kann dies z.B. so erfolgen:

<sp:set name="articlePool" object="system.page.parent"/>
...
  <sp:hidden name="template" value="${articlePool.container}"/>
  <sp:hidden name="editor_template_pool" value="${articlePool.editorTemplatePool}"/>
  <sp:hidden name="registration_template" value="${articlePool.registrationTemplate}"/>
  <sp:hidden name="editor_template" value="${articlePool.editorTemplatePool.sortedElements[0]}"/>
...

In diesem Beispiel wird der gleiche Pool verwendet, in dem auch die SPML-Seite selber liegt. Im Normalfall werden die angelegten Artikel vermutlich in anderen Pools liegen. Das Feld editor_template wird in diesem Beispiel auf das erste Template (alphabetisch sortiert) in dem Template-Pool gesetzt. Hier kann auch z.B. über Anchor ein bestimmtes Template angegeben werden. Es ist nur darauf zu achten, dass das Template auch in dem über editor_template_pool angegebenen Template-Pool enthalten ist.

In dem Artikelpool-Bereich können folgende Angaben für den Pool gemacht werden.

Template Container: Dieses Feld entspricht dem hidden-Feld template. Folgende Anchor für InfoSite-Container können verwendet werden:

gui.container.infosite.standard (Standard InfoSite Container)
gui.container.infosite.media (Standard Medien Container)

Template für die Eigenschaften: Dieses Feld entspricht dem hidden-Feld registration_template. Folgende InfoSite-Templates können verwendet werden:

gui.container.infosite.standard.all (alle Artikel-Typen)
gui.container.infosite.standard.page (nur Seiten anlegen)
gui.container.infosite.standard.media (nur Medien anlegen)
gui.container.infosite.standard.resource (nur Resourcen anlegen)
gui.container.infosite.standard.pageAutoName (nur Seiten ohne Namensvergabe anlegen)
gui.container.infosite.standard.pageAndMedia (nur Seiten und Medien anlegen)
gui.container.infosite.standard.pageAndResource (nur Seiten und Resourcen anlegen)

Templatepool für die Bearbeitung: Dieses Feld entspicht dem hidden-Feld editor_template_pool. Hier muss eine ID eines Templates-Pools angegeben werden, in dem sich die zu verwendenden Templates befinden

Hier ein kleines Beispiel für das Anlegen und Bearbeiten eines Artikels:

<sp:set name="SYS_element" object="SYS_INFE_id"/>

<sp:login login="nutzerlogin" password="nutzerpassword" client="mandantenanchor" scope="application"/>

<sp:set name="articlePool" object="system.page.parent"/>

<sp:form name="createAndEdit" uri="${system.page.url}" handler="com.sitepark.ies.control.jsp.handler.InformationHandler" method="post">
  <sp:condition>
    <sp:if name="system.information">
      <input type="hidden" name="SYS_INFE_id" value="<sp:print name="system.information.id"/>">
      <input type="hidden"  name="SYS_INFE_action" value="update">
    </sp:if>
    <sp:else>
      <input type="hidden" name="SYS_INFE_action" value="create">
      <input type="hidden" name="SYS_INFE_articleType" value="article">
      <input type="hidden" name="SYS_INFE_target" value="<sp:print name="articlePool"/>">
    </sp:else>
  </sp:condition>
  Name:<br>
  <input name="SYS_INFE_name" value="<sp:print name="name"/>"><br>
  Dateiname:<br>
  <input name="SYS_INFE_file" value="<sp:print name="filename"/>"><br>
  <input type="submit" value="speichern"><br>

  <sp:hidden name="template" value="${articlePool.container}"/>
  <sp:hidden name="editor_template_pool" value="${articlePool.editorTemplatePool}"/>
  <sp:hidden name="registration_template" value="${articlePool.registrationTemplate}"/>
  <sp:hidden name="editor_template" value="${articlePool.editorTemplatePool.sortedElements[0]}"/>

  <sp:loop collection="system.error" item="it">
    ERROR: <sp:print name="it.key"/>: <sp:print name="it.value"/><br>
  </sp:loop>
  <sp:loop collection="system.fatal" item="it">
    FATAL: <sp:print name="it.key"/>: <sp:print name="it.value"/><br>
  </sp:loop>

</sp:form>

Artikel publizieren und depublizieren

Um Artikel zu publizieren bzw. zu depublizieren müssen folgende Felder pro Publikationsbereich mitgesendet werden:

SYS_INFE_publicationArea: ID des Publikationsbereiches in dem der Artikel publiziert bzw. depubliziert werden soll. z.B. pub1
SYS_INFE_publicationChecked: Wird diese Feld mitgesendet und hat es als Wert die ID des Publikationsbereiches, so wird der Artikel in diesem Publikationsbereich publiziert. Wird nur das Feld SYS_INFE_publicationArea (ohne SYS_INFE_publicationChecked) mitgesendet, wird der Artikel aus dem Publikationsbereich depubliziert.
SYS_INFE_publicationTemplate: Hiermit wird das Template angegeben mit dem der Artikel publiziert werden soll. Theoretisch ist es möglich für die Ein- und Ausgabe unterschiedliche Templates anzugeben. Da aber InfoSite5 dies nicht unterstützt, ist davon abzuraten. Bitte geben Sie hier für alle Publikationsbereich das Template an, dass Sie auch für das Feld editor_template verwendet haben.

Die Felder können z.B. über hidden-Felder mitgesendet werden. preview und www sind die Anchor der Publikationsbereiche.

  <input type="hidden" name="SYS_INFE_publicationArea" value="<sp:print name="${!{preview}}"/>">
  <input type="hidden" name="SYS_INFE_publicationChecked" value="<sp:print name="${!{preview}}"/>"/>
  <input type="hidden" name="SYS_INFE_publicationTemplate" value="<sp:print name="${articlePool.editorTemplatePool.sortedElements[0]}"/>">

  <input type="hidden" name="SYS_INFE_publicationArea" value="<sp:print name="${!{www}}"/>">
  <input type="hidden" name="SYS_INFE_publicationChecked" value="<sp:print name="${!{www}}"/>"/>
  <input type="hidden" name="SYS_INFE_publicationTemplate" value="<sp:print name="${articlePool.editorTemplatePool.sortedElements[0]}"/>">

PHP Integration

Es kann sinnvoll sein, SPML-Liveseiten nicht direkt aufzurufen, sondern in PHP-Seiten einzubetten. Dazu müssen die PHP-Seiten einen eigenen Request an die SPML-Seite senden. Dabei benötigt die SPML-Seite möglicherweise auch der Request-Parameter, die an die PHP-Seite gesendet wurden. Um die SPML-Seite möglichst einfach einzubinden, steht die PHP-Class RequestDispatcher.class.php aus der phplib von Sitepark zur Verfügung.

Für diese Art der Integration sind noch ein paar PHP-Besonderheiten zu beachten.

Gleichnamige Request-Parameter bzw. Formularfelder

Werden an eine PHP-Seite zwei gleichnamige Request-Parameter bzw. Formularfelder gesendet, wird von PHP immer nur der letzte Parameter verwendet. Wird also z.B. die URL

http://www.domain.de/test.php?test=1&test=2

aufgerufen, erhält man mit $_GET["test"] den Wert 2. Das gleiche gilt für POST Formularfelder. Möchte man beide Parameter erhalten, muss noch ein [] am Parameternamen bzw. Formularfeldnamen angehängt werden. Das obige Beispiel würde dann so aussehen:

http://www.domain.de/test.php?test[]=1&test[]=2

$_GET["test"] enthält nun ein Array mit den Werten $_GET["test"][0]=1 und $_GET["test"][1]=2

Siehe hierzu auch http://www.php.net/manual/de/faq.html.php#faq.html.arrays

Modifikationen von Request-Parametern und Formularfeldern durch PHP

Enthalten Namen von Request-Parametern oder Formularfeldern bestimmte Zeichen, wird der Name von PHP modifiziert. Aufgrund der oben genannten Array-Regel werden z.B. alle Zeichen nach einem [] abgeschnitten. Wird z.B. ein Request-Parameter mit dem Namen

sp_mainIterator[0].sp_text

an eine PHP-Seite geschickt, ist der Wert des Feldes nur noch über den Namen

sp_mainIterator

zugreifbar. Desweiteren werden alle Punkte, die in einem Request-Parameternamen oder einem Formularfeldnamen enthalten sind, durch Unterstriche ersetzt. Wird z.B. ein Request-Parameter mit dem Namen

sp_text.de_DE

an eine PHP-Seite geschickt, ist der Wert des Feldes nur noch über den Namen

sp_text_de_DE

zugreifbar.

Siehe hierzu auch http://www.php.net/manual/de/faq.html.php#faq.html.form-image

Der IES verwendet Punkte und eckige Klammern in mit sp:text, sp:textarea, sp:checkbox, sp:select, sp:hidden, sp:upload, sp:password und sp:radio erzeugten Formularfeldern. Würden diese so an eine PHP-Seite gesendet werden, gingen nötige Informationen verloren. Um dies zu umgehen, können mit dem Attribut nameencoding des Tags sp:form die Formularfeldnamen encodet werden. Aus einem mit sp:form definiertem Formular

<sp:form uri="test.php">
  <sp:iterator collection="sp_list" min="1">
    <sp:text name="sp_text"/>
  </sp:iterator>
</sp:form>

wird folgender HTML-Code erzeugt:

<form action="/test.php" method="post" id="form:0"><div>...</div>
    <input type="text" name="sp_list[0].sp_text" value="" id="tag:0">  
<div><input type="hidden" name="SYS_pageParameter" value="..."></div></form>

Mit der Angabe eines nameencoding werden die Formularfeldnamen encodet. Aus einem mit sp:form definiertem Formular

<sp:form uri="test.php" nameencoding="hex">
  <sp:iterator collection="sp_list" min="1">
    <sp:text name="sp_text"/>
  </sp:iterator>
</sp:form>

wird folgender HTML-Code erzeugt:

<form action="/test.php" method="post" id="form:0"><div>...</div>  
    <input type="text" name="hex:73705f6c6973745b305d2e73705f74657874" value="" id="tag:0">
<div><input type="hidden" name="SYS_pageParameter" value="..."></div></form>

Dadurch wird verhindert, dass PHP die Formularfeldnamen modifiziert. Der weiter unten beschriebene RequestDispatcher.class.php bietet Methoden, mit denen über den originalen Formularfeldnamen auf die Parameter zugegriffen werden kann.

Zu lange Request-Parametern-Namen im Suhosin Patch

Wird PHP mit dem 'Suhosin Patch' betrieben, ist die Länge des Parameter-Namens beschränkt. Aufgrund des oben beschriebenen encodings der Parameternamen kann es jedoch zu sehr langen Parameternamen kommen.

Die aktuelle versendeten Beschränkungen können über

phpinfo();

ermittelt werden. Alle Filter-Optionen mit ihren Default-Werten können unter http://www.hardened-php.net/suhosin/configuration.html#filtering_options entnommen werden

Um dieses Problem zu lösen kann zunächst das Encoding mit dem sp:form die Parameter nameencoding, geändert werden. Verwenden sie das Encoding escff.

<sp:form ... nameencoding="escff">

Sollten die Parameternamen dennoch zu lang sein, muss die Filter-Optionen des Suhosin Patch erhöht werden.

RequestDispatcher.class.php

Die PHP-Klasse RequestDispatcher ist Teil der Sitepark phplib. Sie soll die Integrations von Live-SPML-Seiten in PHP-Seiten vereinfachen, kann aber auch ganz allgemein zur Weiterleitung von HTTP-Requests verwendet werden.

Bevor die Klasse verwendet werden kann, muss sie in die PHP-Seite geladen werden. Dies sollte wie folgt erfolgen:

require_once($_SERVER["DOCUMENT_ROOT"] . "/phplib/RequestDispatcher.class.php");

Um den Dispatcher zu nutzen, muss eine Instanz der Klasse erzeugt werden:

$dispatcher = new RequestDispatcher("www.domain.de");

Dem Konstruktor wird der Host, oder die IP-Adresse des Servers angegeben, an den der Request weitergeleitet werden soll. Wird kein Host angegeben, wird der Host mit Hilfe der Server-Variablen $_SERVER["HTTP_HOST"] ermittelt.

SPML-Seiten verwenden das Encoding UTF-8 und liefern die Zeichen in diesem Encoding zurück. Verwendet die PHP-Seite ein anderes Encoding, kann mit der Methode setEncoding() das entsprechende Encoding angegeben werden.

$dispatcher->setEncoding("ISO-8859-15");

Die Methode absorb() liest alle Request-Parameter, Request-Uploads, Cookies, Session-Parameter und Server-Variablen ein, um sie mit der dispatch()-Methode weiterzuleiten. Alternativ können z.B. auch nur Request-Parameter mit der Methode absorbRequestParameter() übernommen werden. Weitere Methoden sind absorbRequestUploads(), absorbSessionVariables(), absorbCookies() und absorbServerVariables(). Einzelnen Werte können mit setParameter(), setFile() und setCookie() gesetzt werden. Server- und Session-Variablen werden als HTTP-Parameter gesendet.

$dispatcher->absorb();

Die Methode dispatch() führt den Request aus. Bei dieser Methode wird der Pfad zu der Seite angegeben, an den der Request weitergeleitet werden soll. Die Methode liefert true zurück, wenn der Request erfolgreich weitergeleitet wurde, ansonsten den Wert false.

$success = $dispatcher->dispatch("/dir/file.spml");

Der Dispatcher reicht alle GET- und POST-Parameter der PHP-Seite weiter. Der Request, den der Dispatcher ausfürt ist immer POST. Weiterhin werden alle Session-Variablen ($_SESSION) und alle Server ($_SERVER) als Parameter mitgesendet. Cookies werden als Cookies weitergereicht.

Anschließend kann eine Fehlerbehandlung erfolgen oder z.B. der Response ausgegeben werden.

if ($success) {
  echo $dispatcher->getContent();
} else {
  echo "<b>FEHLER</b>: " . $dispatcher->getError() . "<br>";
}

Für die Ausgabe und Auswertung stehen folgende Methoden zur Verfügung:

getContent(): gibt den Inhalt der aufgerufenen Seite zurück

getStatusCode(): Liefert den HTTP-Status-Code des Response zurück (z.B. 200 für 'OK' oder 404 für 'not found')

getStatusMessage(): Liefert die HTTP-Status-Meldung des Response zurück (z.B. 'OK' oder '... not found')

getError(): Liefert eine Fehlerzeile aus HTTP-Status-Code und -Meldung zurück

getResonseHeaders(): Liefert ein Assoziatives Array, das die Response Header enthält

getResonseCookies(): Liefert ein Assoziatives Array, das die Cookies im Response enthält

getRequestURL(): Liefert die URL, an die der Request weitergeleitet wurde

getJSessionId(): Liefert vor dem dispatch()-Aufruf die JSESSIONID mit der der Request gesendet wird. Nach dem dispatch()-Aufruf wird die vom Request zurückgelieferte JSESSIONID ausgegeben.

Soll für mehrere Aufrufe von SPML-Seiten die gleiche Session verwendet werde, muss das dafür notwendige Cookie JSESSIONID vom Dispatcher an die aufrufende PHP-Seite weitergegeben werden. Ist dies erwünscht, ist das vor dem dispatch()-Aufruf mit der Methode setWriteCookies(true) einzuschalten.

Das Schreiben des Cookies vom Dispatcher ist standardmässig deaktiviert. Der Grund dafür ist, dass der Dispatcher das Cookie nur setzen kann, wenn noch keine Daten an den Client gesendet wurden (Cookies liegen im HTTP-Header). Soll der Dispatcher Cookies an den Client weiterreichen, muss die disptach()-Methode aufgerufen werden, bevor PHP Daten an den Client sendet (z.B. mit echo).

...
$dispatcher->setWriteCookies(true);
$success = $dispatcher->dispatch("/dir/file.spml");
...

Dadurch wird das Cookie JSESSIONID an den Browser weitergereicht. Mit dieser Methode kann die PHP-Seite nur eine Session für die SPML-Seiten definieren, da der Cookie-Name JSESSIONID vorgegeben ist. Möglicherweise kann es auch zu Konflikten kommen, wenn weitere PHP-Seiten eine andere Session verwenden wollen. Aus diesem Grund ist es möglich den Namen des Cookies zu ändern, der an den Browser gesendet werden soll. Mit folgendem Aufruf lässt sich der Cookie-Name ändern.

...
$dispatcher->setJSessionName("mySessionA");
$dispatcher->setWriteCookies(true);
$success = $dispatcher->dispatch("/dir/file.spml");
...

Auch die Namensänderung muss vor dem Aufruf der dispatch()-Methode erfolgen. Der Dispatcher sorgt nun dafür, dass zwar das Cookie JSESSIONID an die SPML-Seite gesendet wird, im Browser wird die SessionID allerdings in einem Cookie gehalten, dessen Name mit setJSessionName() angegeben werden kann.

Im Normalfall leitet der RequestDispatcher alle Request-Parameter mit der die PHP-Seite aufgerufen wurde an die angegebene URL weiter. Es können allerdings noch weitere Parameter und auch Upload-Dateien hinzugefügt werden. Diese können vor dem dispatch()-Aufruf mit folgender Methode gesetzt werden.

...
$dispatcher->setParameter("myparam", "abc"); // HTTP-Parameter hinzufügen
$dispatcher->setFile("myfile", "/tmp/image.jpg", "image/jpg"); // HTTP-Upload-Datei hinzufügen
$success = $dispatcher->dispatch("/dir/file.spml");
...

Wurden an die PHP-Seite Formulardaten eines mit sp:form erzeugten Formulars gesendet, ist wie oben beschrieben die Angabe eines nameencodings notwendig. Um dennoch über den originalen Fomularfeldnamen auf die Felder zugreifen zu können, ist es möglich das Encoding bei den Methoden setParameter(), addParameter(), removeParameter(), getParameter(), setFile(), addFile(), removeFile() und getFile() mit anzugeben.

...
$dispatcher->setParameter("myparam", "abc", "hex"); // HTTP-Parameter hinzufügen
$dispatcher->getParameter("test", "hex"); // liefert den HTTP-Parameter zurück
...

Zusammenfassend noch die Methoden, mit denen der Request gesteuert werden kann

setJSessionId(jsessionid): Setzt die JSESSIONID die verwendet werden soll.

absorb(): Übernimmt alle Parameter und Variablen der PHP-Seite, um sie weiter zu senden.

absorbRequestParameter(): Übernimmt alle Request-Parameter der PHP-Seite, um sie weiter zu senden.

absorbRequestUploads(): Übernimmt alle Request-Uploads der PHP-Seite, um sie weiter zu senden.

absorbCookies(): Übernimmt alle Cookies der PHP-Seite, um sie weiter zu senden.

absorbSessionVariables(): Übernimmt alle Session-Variablen der PHP-Seite, um sie weiter zu senden.

absorbServerVariables(): Übernimmt alle Server-Variablen der PHP-Seite, um sie weiter zu senden.

dispatch(path, user, password): Führt den Request mit den angegebenen Pfad aus. Optional kann noch ein User und ein Passwort für BASIC-Authentikation angegeben werden.

setParameter(name, value, encoding)

Setzt ein Parameter der zusätzlich noch mitgesendet werden soll. Existiert bereis ein Parameter mit dem Name wird dieser überschieben

Parameter: name Name des Parameters; value Wert des Parameters; encoding (optional) Encoding, mit dem der angegebene Parametername encodet werden soll

addParameter(name, value, encoding)

Setzt ein Parameter der zusätzlich noch mitgesendet werden soll. Existiert bereis ein Parameter mit dem Name wird der neue Wert hinzugefügt. Aus dem value wird ein Array.

Parameter: name Name des Parameters; value Wert des Parameters; encoding (optional) Encoding, mit dem der angegebene Parametername encodet werden soll

removeParameter(name, encoding)

Löscht einen Parameter und liefert den Wert des gelöschten Parameters zurück

Parameter: name Name des Parameters; encoding (optional) Encoding, mit dem der angegebene Parametername encodet werden soll

getParameter(name, encoding)

Liefert den Wert eines Parameters

Parameter: name Name des Parameters; encoding(optional) Encoding, mit dem der angegebene Parametername encodet werden soll

setFile(name, file, mime, encoding): Setzt eine Datei die zusätzlich noch mitgesendet werden soll. Existiert bereis eine Uploaddatei mit dem Feldnamen wird diese ersetzt.

Parameter: name Feldname unter dem die Datei mitgesendet werden soll.; file Absoluter oder relativer (zur PHP-Seite) Pfad der Datei; mime MIME-Type der Datei; encoding (optional) Encoding, mit dem der angegebene Parametername encodet werden soll

addFile(name, file, mime, encoding): Setzt eine Datei die zusätzlich noch mitgesendet werden soll. Existiert bereis eine Uploaddatei mit dem Feldnamen wird die Datei hinzugefügt.

Parameter: name Feldname unter dem die Datei mitgesendet werden soll.; file Absoluter oder relativer (zur PHP-Seite) Pfad der Datei; mime MIME-Type der Datei; encoding (optional) Encoding, mit dem der angegebene Parametername encodet werden soll.

removeFile(name, encoding)

Sendet die Upload-Datei(en) mit dem angegebenen Feldnamen nicht mit und liefert die Datei in Form eines Arrays zurück. Das Array hat folgende Felder.

name: Feldname
type: MIME-Type
tmp_name: Pfad zur Datei
error: Fehlercode bei übernommenen Dateien
size: Dateigröße in Bytes
Parameter: name Feldname unter dem die Datei mitgesendet werden soll.; encoding (optional) Encoding, mit dem der angegebene Parametername encodet werden soll.

getFile(name, encoding)

Liefert die zu sendende Datei in Form eines Arrays. Das Array hat folgende Felder

Parameter: name Feldname; type MIME-Type; tmp_name Pfad zur Datei; error Fehlercode bei übernommenen Dateien; size Dateigröße in Bytes

setCookie(name, value)

Setzt ein Cookie das zusätzlich noch mitgesendet werden soll.

Parameter: name Name des Parameters; value Wert des Parameters

removeCookie(name)

Sendet das angegebene Cookie nicht mit und liefert den Wert des Cookies oder null, wenn des Cookie nicht existiert

Parameter: name Name des Parameters

getCookie(name)

Liefert den Wert des zu sendenden Cookies oder null, wenn des Cookie nicht existiert

Parameter: name Name des Parameters

setJSessionName(name);

Gibt einen Cookie-Namen an, unter dem die JSESSIONID im Browser gespeichert werden soll

Parameter: name Name des Cookies

setWriteCookies(writeCookie);

Gibt an, ob die Cookies des Response des weitergereichten Requests bis zum Browser durchgereicht werden sollen.

Parameter: writeCookie true, wenn die Cookies durchgereicht werden sollen.