Verwendung von Formularen

Das Adventure PHP Framework beinhaltet eine sehr umfangreiche Formular-Unterstützung die auf dem Taglibs-Konzept basiert. Die Grundlagen und vorhandenen Taglibs sind im Abschnitt Formulare beschrieben. Dieses Kapitel beschäftigt sich nun mit der Verwendung von Formularen, der dynamischen Formular-Generierung und der Erweiterung der Formular-Taglibs.

1. Formulare & Controller

Formulare sind - genau wie Template-Fragmente - Elemente, die im DOM-Baum existieren, jedoch bei der Transformation nicht automatisch ausgegeben werden. Hierzu bedarf es eines Document-Controller. Der Grund dafür ist simple: nahezu jedes Formular ist an Aktionen geknüpft, die mit dem Absenden des Formulars ausgeführt werden sollen (z.B. Speichern der Daten).

Um ein Formular mit Hilfe eines Document-Controller auszugeben, ist folgender Code notwendig:

PHP-Code

class form_controller extends BaseDocumentController {
   public function transformContent(){
      $form = &$this->getForm('Search');
      $form->transformOnPlace();
   }
}

In der Variable $form steht dabei eine Instanz der Klasse HtmlFormTag zur Verfügung, die ein APF-Formular mit all seinen Elementen und Funktionen kapselt. Mit Hilfe dieser Referenz auf das Formular-Objekt im DOM-Baum kann das Formular ausgegeben, manipuliert, befüllt und angepasst werden. Details dazu können den folgenden Kapiteln entnommen werden.

2. API der Formular-Taglibs

Im vorangegangenen Abschnitt wurde beschrieben, wie ein Formular in einem Document-Controller referenziert werden kann. In diesem Kapitel beschäftigen wir uns nun mit der API der Formular-Taglibs, die Aufschluss darüber gibt, welche Möglichkeiten die Formular-Integration des APF bietet.

Für die Entwicklung ist es stets ratsam, die API-Dokumentation der eingesetzten Version parallel zur Entwicklungsumgebung geöffnet zu haben. Dies erleichtert die Arbeit, da jede Taglib ihre eigene API mitbringt, die in der API-DOkumentation genau beschrieben ist.

Grundlage für alle Formular-Elemente ist die Klasse AbstractFormControl. Diese implementiert Basis-Funktionalitäten für alle konkreten Formular-Elemente und definiert die Struktur eines Formular-Elements. Da die Formular-Elemente als Taglibs ausgeführt sind, unterliegen sie dem Lifecycle des Page-Controllers. Das bedeutet, dass sie darüber hinaus alle Methoden einer "normalen" Taglib implementieren müssen.

Im Gegensatz zu den Formular-Taglibs bis Version 1.10, kennen die Formular-Elemente ab Version 1.11 ihren Validitäts-Status selbst. Damit kann jedes Element nach seinem Status gefragt werden. Für das Formular selbst bedeutet das, dass die Methode isValid() den Status von jedem Element abfragt und daraus einen kumulierten Wert erzeugt.

Die Klasse AbstractFormControl implementierten folgende Methoden:

isValid(): Die Funktion ermöglicht es, den Validitäts-Status der Formular-Elements abzufragen. Intern oder auch von aussen.
markAsInvalid(): Markiert ein Element als invalid.
markAsValid(): Markiert ein Element als valide (seit Release 1.17).
markAsSent(): Markiert ein Element als abgesendet (relevant für Formulare und Buttons).
isSent(): Prüft, ob ein Formular abgesendet wurde.
isChecked(): Gibt zurück, ob eine Checkbox angehakt wurde oder nicht.
check(): Hakt eine Checkbox an.
uncheck(): Deaktiviert eine Checkbox.
getValue(): Gibt den Inhalt eines Elements zurück. Normalerweise ist dies der Inhalt des "value"-Attribut, außer bei Sonderfällen wie z.B. Textareas, bei denen Usereingaben im Inhaltsbereich des Tags stehen. (Seit 1.14)
setValue(): Setzt den Inhalt eines Elements. Normalerweise ist dies der Inhalt des "value"-Attribut, außer bei Sonderfällen wie z.B. Textareas, bei denen Usereingaben im Inhaltsbereich des Tags stehen. (Seit 1.14)
isFilled(): Gibt bei ausgefülltem Textfeld oder ausgefüllter Textarea true zurück, andernfalls false. Dies funktioniert nur bei Textfeldern und Textareas (form:text und form:area). (Seit 1.15)
isSelected(): Gibt bei einer Auswahl in einem Single- oder Multiselect true zurück, andernfalls false. Es muss dazu eine Option, welche einen Wert enthält, selektiert werden. Wird ein Wert selektiert, welcher ledigiglich "" liefert, wird ebenfalls false von dieser Methode zurück gegeben. Dies funktioniert bei einfachen sowie mehrfachen Auswahlfeldern (form:select und form:multiselect). (Seit 1.15)
isVisible(): Gibt den Sichtbarkeits-Status des Elements zurück. true referenziert auf ein sichtbares Element, false markiert ein Element, das bei der Ausgabe nicht angezeigt wird (seit Release 1.17).
hide(): Versteckt ein Formular-Feld für die Ausgabe (seit Release 1.17).
show(): Setzt den Sichtbarkeits-Status des Elements auf true (seit Release 1.17).
addFilter(): Fügt einen Filter zu einem Element hinzu.
addValidator(): Fügt einen Validator zu einem Element hinzu.
addAttribute(): Kann genutzt werden, um zu einem Attribut eines Tags weiteren Inhalt hinzuzufügen. Dies wird beim Benachrichtigen eines Formular-Elements innerhalb der Validierung genutzt.
notifyValidationListeners(): Benachrichtigt alle Listener eines Formular-Elements, dass dieses invalid ist.
presetValue(): Die Methode stellt Presetting von Formular-Elementen für einfache Text-Felder zur Verfügung. Diese kann bei der Erweiterung von Formular-Elementen entweder mit einer eigenen Logik überschrieben oder direkt genutzt werden.
setPlaceHolder(): Die Methode implementiert eine generische Funktion zum setzen eines Platzhalters in einem Formular-Element. Wichtig hierbei ist, dass das Kind-Tag *:placeholder heißt.
addAttributeToWhitelist(): Fügt das übergebene Attribut zur Whitelist des aktuellen Formular-Elements hinzu. Damit wird dieses auch in den HTML-Quelltext geschrieben.

Im Release 1.17 wurden alte Namenskonventionen von Methoden entfernt. Sofern Sie das APF in der Version 1.16 oder kleiner verwenden lautet der Name der Funktion für das Presetting von Formular-Werten __presetValue() statt presetValue().

Mit Hilfe dieser Funktionen wird der Entwickler darin untrstützt, eigene Formular-Elemente zu erstellen. Mehr dazu in Kapitel 7.

Mit dem Release 1.12 wurde im Zusammenhang mit der Einführung der Client-Validierung ein Attribut-Whitelisting für Formular-Taglibs eingeführt. Dieses sorgt dafür, dass nur XHTML-kompatible Attribute in den Quelltext geschrieben werden. Proprietäre Attribute - etwa zur Steuerung der Validierung - werden nicht beachtet.

Bei der Erstellung einer eigenen Formular-Taglib muss da daher darauf geachtet werden, dass zusätzlich notwendige Attribute in die Whitelist aufgenommen werden. Hierzu empiehlt es sich, den Konstruktor der Taglib zu nutzen:

PHP-Code

class SpecialFormControlTag extends AbstractFormControl {
   public function __construct() {
      $this->attributeWhiteList[] = 'name';
      $this->attributeWhiteList[] = 'accesskey';
   }
}

3. Validierung

Die Validierung von Formular-Elementen wird über die Taglib form:addvalidator und die Implementierung der Validatoren auf das Klick-Event eines Buttons ausgeführt. Zeitlich gesehen erfolgt die Validierung bei der Ausführung der onAfterAppend()-Methode. Das ist nach der Analyse-Phase (hier wird die Methode onParseTime() jeder Taglib ausgeführt) und damit steht der DOM-Baum der Formular-Elemente vollständig zur Verfügung.

In der onAfterAppend()-Methode des form:addvalidator-Tags wird dann der Validator erzeugt, mit den notwendigen Informationen (Button und Formular-Control) ausgestattet und dem Element übergeben. Das Element führt den Validator dann bei aktivem Status aus und prüft das Ergebnis. Im Negativfall wird die notify()-Methode des Validators aufgerufen.

3.1. Abfragen des Validierungs-Status

Da die einzelnen Formular-Elemente ab der neuen Implementierung selbst kennen, muss die Methode isValid() des Formulars den Status jedes einzelnen Elements erfragen. In einem Document-Controller kann der Zustand eines Formulars damit wie folgt abgefragt werden:

PHP-Code

class form_controller extends BaseDocumentController {
   public function transformContent(){
      $form = &$this->getForm('MyForm');
      if($form->isSent()){
         echo 'Form was send');
      }
      if($form->isValid()){
         echo 'Form is valid';
      }
   }
}

Ebenso ist es möglich, den Status eines definierten Elements zu erfragen:

PHP-Code

class form_controller extends BaseDocumentController {
   public function transformContent(){
      $form = &$this->getForm('MyForm');
      $searchField = &$form->getFormElementByName('searchterm');
      if($searchField->isValid()){
         echo 'Search field is valid';
      }
   }
}

Um den Klick-Status eines Buttons abzufragen, kann folgender Code genutzt werden:

PHP-Code

class form_controller extends BaseDocumentController {
   public function transformContent(){
      $form = &$this->getForm('MyForm');
      $button = &$form->getFormElementByID('button');
      if($button->isSent()){
         echo 'Search button was clicked';
      }
   }
}

Weitere Methoden der Formular-Elemente finden sich in der API-Dokumentation der Klassen HtmlFormTag, AbstractFormControl und den Taglibs der jeweiligen Formular-Elemente (z.B. TextFieldTag).

3.2. Ausgabe von Validator-Fehlermeldungen

Bei der Validierung von Formularen werden monierte Felder üblicherweise farblich markiert und der Benutzer mit einem Hinweistext benachrichtigt. Für diese Aufgaben können die Tags <form:error /> (globale Formular-Fehlermeldungen) und <form:listener /> verwendet werden. Alternativ dazu ist ein Platzhalter-Tag verfügbar, das im Controller mit einem entsprechenden Wert belegt werden kann.

3.2.1. Form-Error

Der <form:error /> gibt immer dann seinen Inhalt aus, wenn das Formular nicht valide ist. Dazu fragt er das Formular bei der Transformation nach seinem Status:

Template:

APF-Template

<html:form name="product-form">
   <form:error>Please fill in the mandatory fields!</form:error>
   <form:text name="code" minlength="5" maxlength="5"/>
   <form:text name="title" minlength="20"/>
   <form:area name="description" minlength="30"/>
   <form:addvalidator
      class="TextLengthValidator"
      control="code|title|description"
      button="send"
   />
   <form:button name="send" value="Save" />
</html:form>

Controller:

PHP-Code

class form_controller extends BaseDocumentController {
   public function transformContent(){
      $form = &$this->getForm('product-form');
      $form->transformOnPlace();
   }
}

Innerhalb des <form:error />-Tags können gemäß Anzeige von Formular-Fehlern noch weitere Tags zur Definition der Inhalte verwendet werden.

3.2.2. Listener

Der <form:listener />-Tag dient dazu Feld-speziefische Fehler anzuzeigen. Wie in der Einleitung zum Kapitel 3 angesprochen, wird bei fehlgeschlagener Validierung die Methode notify() aufgerufen. Diese benachrichtigt alle Listener, die sich auf das entsprechende Control registriert haben und diese geben dann bei der Transformation den definierten Inhalt aus.

Im folgenden Beispiel wird bei fehgeschlagener Validierung jeweils eine Feld-spezifische Meldung angezeigt:

Template:

APF-Template

<html:form name="product-form">
   <form:listener control="code">Please fill in a five letter product code!</form:listener>
   <form:text name="code" minlength="5" maxlength="5"/>
   <form:listener control="title">Please fill in a title with at least 20 characters!</form:listener>
   <form:text name="title" minlength="20"/>
   <form:listener control="description">Please provide a verbose product description!</form:listener>
   <form:area name="description" minlength="30"/>
   <form:addvalidator
      class="TextLengthValidator"
      control="code|title|description"
      button="send"
   />
   <form:button name="send" value="Save" />
</html:form>

Controller:

PHP-Code

class form_controller extends BaseDocumentController {
   public function transformContent(){
      $form = &$this->getForm('product-form');
      $form->transformOnPlace();
   }
}

Innerhalb des <form:listener />-Tags können gemäß Listener noch weitere Tags zur Definition der Inhalte verwendet werden.

3.3. Nachträgliche Validierung im Controller

In einigen Situationen kann es einfacher bzw. schneller sein, eine Formular-Validierung im Controller durchzuführen anstatt einen eigenen Validator zu schreiben. Um auch in diesen Fällen eine Markierung der Formular-Felder zu ermöglichen wurde in Version 1.14 eine neue Methode für Formular-Felder eingeführt.

Als Beispiel soll im folgenden Formular das Feld searchterm nach einer eigenen Regel im Controller validiert werden:

APF-Template

<html:form name="search">
   <label for="searchterm">Suchbegriff:</label>
   <form:text id="searchterm" name="searchterm" value="" />
   <form:button name="search" value="GO" />
</html:form>

Der passende Controller beinhaltet folgenden Code zur Prüfung, dass das Suchfeld den Buchstaben e nicht enthält:

PHP-Code

class search_controller extends BaseDocumentController {

   public function transformContent() {

      $form = &$this->getForm('search');
      $searchTerm = &$form->getFormElementById('searchterm')

      if(stripos($searchTerm->getValue(), 'e') !== false) {
         $searchTerm->markAsInvalid();
         $searchTerm->appendCssClass(AbstractFormValidator::$DEFAULT_MARKER_CLASS);
      }

      $form->transformOnPlace();

   }

}

Beim Abschicken des Formulars mit einem Wort, das den Buchstaben e beinhaltet, wird das Feld searchterm technisch als invalid markiert und erhält die Standard-CSS-Klasse, die zur optischen Markierung eingesetzt wird. Sofern eine eigene Klasse genutzt werden soll, kann diese entweder im Controller fest definiert werden oder aus einem Attribut des Formular-Feldes bezogen werden (z.B. valmarkerclass).

4. Auslesen von Formularen

Eine häufige Aufgabe beim Handling von Formularen stellt das Auslesen von Werte dar. Hierzu können im Document-Controller folgende Methoden genutzt werden:

getFormElementByID(): Liefert ein Formular-Element an Hand seiner ID (Attribut: id).
getFormElementByName(): Liefert ein Formular-Element an Hand seines Namens (Attribut: name).
getFormElementsByTagName(): Liefert eine Liste von Formular-Elementen an Hand des Tag-Namens (z.B. form:text).
getFormElementsByObjectID(): Liefert ein Formular-Element an Hand seiner internen ObjektID. Diese Vorgehensweise kann bei der Generierung von dynamischen Formularen angewendet werden.

4.1. Auswahl per Name

Sollen die im Formular des Kapitels 3.2.2. beschriebenen Felder zum Abspeichern des Formulars ausgelesen werden, kann dies mit Hilfe des folgenden Controller-Codes erreicht werden:

PHP-Code

class form_controller extends BaseDocumentController {
   public function transformContent(){
      $form = &$this->getForm('product-form');

      if($form->isSent() && $form->isValid()){

         $code = &$form->getFormElementByName('code');
         echo 'product code: '.$code->getValue();

         $title = &$form->getFormElementByName('title');
         echo 'product title: '.$title->getValue();

         $description = &$form->getFormElementByName('description');
         echo 'product desc: '.$description->getValue();
      }
      
   }
}

Bei Textareas wird der Inhalt nicht im Attribut value gespeichert, sondern im Inhalt des Tags. Dies entspriche exakt der Vorgehensweise der Tag-Definition in HTML.

Da das Formular nichts anderes darstellt als einen DOM-Baum von Formular-Elementen, kann ein Platzhalter in einem Error-Tag über zwei Stufen adressiert werden. Zu erst wird die Instanz des Error-Tags bezogen und von dort der Platzhalter. Als Beispiel nutzen wir folgendes Formular:

APF-Template

<html:form name="product-form">
   <form:error name="error">
      <error:placeholder name="ph1" />
   </form:error>
   ...
</html:form>

Um nun den Platzhalter innerhalb des <form:error />-Tags zu füllen, kann folgender Controller-Code genutzt werden:

PHP-Code

class form_controller extends BaseDocumentController {
   public function transformContent(){
      $form = &$this->getForm('product-form');
      $error = &$form->getFormElementByName('error');

      // simple way:
      $error->setPlaceHolder('ph1','My placeholder value');

      // alternative way:
      $placeHolder = $error->getFormElementByName('ph1');
      $placeHolder->setContent('My placeholder value');
   }
}

Um ein Formular-Element per ID auszuwählen, kann die gleiche Vorgehensweise wie bei der Auswahl nach Name verwendet werden.

4.2. Auswahl per Tag

In manchen Fällen kann es nützlich sein, die gewünschten Formular-Elemente per Tag-Namen zu selektieren. Hierzu steht die Methode getFormElementsByTagName() zur Verfügung. Diese liefert eine Liste mit Referenzen auf Formular-Elemente des übergebenen Tag-Namens.

Im Zusammenspiel mit dem Generischer O/R-Mapper kann die Methode genutzt werden um Formular-Felder auszulesen und direkt in ein GenericDomainObject zu speichern. Hierzu kann folgender Code genutzt werden:

PHP-Code

class edit_controller extends BaseDocumentController {
   public function transformContent(){
      $form = &$this->getForm('...');
      $textFields = &$form->getFormElementsByTagName('form:text');
      $user = new GenericDomainObject('User');
      $count = count($textFields);
      for($i = 0; $i < $count; $i++){
         $user->setProperty(
            $textFields[$i]->getAttribute('name'),
            $textFields[$i]->getValue()
         );
      }
   }
}

Bei der Anwendung ist zu beachten, dass die Methode jeweils nur diejenigen Elemente zurückliefert, die ausgehend vom verwendeten Element, als direkte Kind-Knoten vorhanden sind.

5. Manipulation von Formularen

Die Implementierung der Formular-TagLibs des Frameworks bringt einige Möglichkeiten zur Manipulation von Formularelementen oder deren Werte mit. Die folgenden Kapitel zeigen häufig auftretende Anwendungsbeispiele.

5.1. Vorbefüllung von Formularen

Zur Vorbefüllung von Formularen (z.B. in einem Bearbeiten-Dialog) können Methoden

getFormElementByName(),
getFormElementByTagName(),
getFormElementByID() oder
getFormElementByObjectID()

eingesetzt werden um eine Referenz auf ein Formular-Element zu beziehen. Anschließend stehen die Standard-Methode

getAttribute()

bzw.

setAttribute()

zur Verfügung.

Die folgenden Codebox definiert ein Beispiel-Formular, das im anschließend abgedruckten PHP-Code befüllt wird:

Template:

APF-Template

<core:addtaglib
   namespace="tools::form::taglib"
   class="HtmlFormTag"
   prefix="html"
   name="form"
/>
<html:form name="UserEdit" method="post">
   <strong>FirstName</strong>:
   <form:text name="FirstName" />
   <br />
   <strong>LastName</strong>:
   <form:text name="LastName" />
   <br />
   <br />
   <form:button name="Edit" value="Save" />
   <form:hidden name="userid" />
</html:form>

Controller:

PHP-Code

$form = &$this->getForm('UserEdit');

$userID = &$form->getFormElementByName('userid');
$userID->setAttribute('value','...');

$firstName = &$form->getFormElementByName('FirstName');
$fFirstName->setAttribute('value','...');

$lastName = &$form->getFormElementByName('LastName');
$lastName->setAttribute('value','...');

5.2. Befüllen von Select-Feldern

Die Behandlung Select- und Multiselect-Feldern unterscheidet sich ein wenig von einfachen Formular-Elementen. Das Framework stellt jedoch auch hier Methoden zur Verfügung, mit denen das Befüllen von Feldern vereinfacht wird. Im nachfolgend aufgeführten Code wird ein Formular vorausgefüllt, das zusätzlich zu den Standard-Text-Felder auch Auswahlfelder beinhaltet:

APF-Template

<core:addtaglib
   namespace="tools::form::taglib"
   class="HtmlFormTag"
   prefix="html"
   name="form"
/>
<html:form name="UserCreate" method="post">
   <strong>Salutation</strong>:
   <form:select name="Salutation" />
   <br />
   <strong>FirstName</strong>:
   <form:text name="FirstName" />
   <br />
   <strong>LastName</strong>:
   <form:text name="LastName" />
   <br />
   <br />
   <strong>Groups</strong>:
   <br />
   <form:multiselect name="Group" />
   <br />
   <br />
   <form:button name="Edit" value="Save" />
   <form:hidden name="userid" />
</html:form>

Der folgende PHP-Code befüllt das Formular:

PHP-Code

$form = &$this->getForm('UserCreate');
$salutations = array(...);
$salutation = &$form->getFormElementByName('Salutation');
for($i = 0; $i < count($salutations); $i++){
   $salutation->addOption($salutations[$i]['DisplayName'], $salutations[$i]['Value']);
}
$goups = array(...);
$group = &$form->getFormElementByName('Groups');
for($i = 0; $i < count($groups); $i++){
   $group->addOption($groups[$i]['DisplayName'], $groups[$i]['Value']);
}

Sollen beim Befüllen eines Multiselect-Feldes bestimmte Optionen bereits vorausgewählt sein, so kann die Methode setOption2Selected() verwendet werden.

Der folgende Code zeigt, wie ein Multiselect-Feld zunächst mit Berechtigungen gefüllt und anschließend gemäß den Applikationsinformationen vorselektiert wird. Das Beispiel ist aus dem im Release mitgelieferten Usermanagement-Modul-Modul entnommen.

PHP-Code

$form = &$this->getForm('PermissionSetEdit');

// load permissions and fill the select field
$allPermissions = $uM->loadPermissionList();
$permField = &$form->getFormElementByName('Permission[]');
for($i = 0; $i < count($allPermissions); $i++){
   $permField->addOption($allPermissions[$i]->getProperty('DisplayName'),$allPermissions[$i]->getProperty('PermissionID'));
}

// preselect the options
$selectedPermissions = $uM->loadPermissionsOfPermissionSet($permSet);
for($i = 0; $i < count($selectedPermissions); $i++){
   $permField->setOption2Selected($selectedPermissions[$i]->getProperty('PermissionID'));
}

5.3. Auslesen von Formular-Elementen

Das Auslesen von Formular-Elementen gestaltet sich ähnlich wie das Befüllen. Eine Besonderheit stellen auch hier die Einfach- und Mehrfachselektionsfelder dar. Das folgende Code-Beispiel zeigt, wie die Werte des unter 3.1 dargestellten Formulars im Document-Controller ausgelesen werden können:

PHP-Code

$form = &$this->getForm('UserEdit');

$userID = &$form->getFormElementByName('userid');
echo $userID->getValue();

$firstName = &$form->getFormElementByName('FirstName');
echo $firstName->getValue();

$lastName = &$form->getFormElementByName('LastName');
echo $lastName->getValue();

Um die selektierten Optionen eines Einfach- oder Mehrfachselektionsfeldes auszulesen, stehen die Methoden getSelectedOption() und getSelectedOptions() zur Verfügung. Die folgende Codebox zeigt den Anwendungsfall:

PHP-Code

$form = &$this->getForm('UserCreate');

$salutations = array(...);
$salutation = &$form->getFormElementByName('Salutation');
for($i = 0; $i < count($salutations); $i++){
   $salutation->addOption($salutations[$i]['Value'],$salutations[$i]['DisplayName']);
}

$option = &$salutation->getSelectedOption();
echo $option->getAttribute('value').', '.$option->getContent();

$groups = array(...);
$group = &$form->getFormElementByName('Groups[]');
for($i = 0; $i < count($groups); $i++){
   $group->addOption($groups[$i]['Value'],$groups[$i]['DisplayName']);
}

$selectedGroups = &$group->getSelectedOptions();
for($i = 0; $i < count($selectedGroups); $i++){
   echo $selectedGroups[$i]->getAttribute('value').', '.$selectedGroups[$i]->getContent();
}

Die Auswertung von dynamisch befüllten Select-Feldern funktioniert nur dann, wenn diese in allen Anwendungsfällen zuerst mit den gewünschten Optionen versehen werden. Ist dies nicht der Falls, so liefern die Methoden getSelectedOption() bzw. getSelectedOptions() kein Ergebnis. Dies ist insbesondere dann wichtig, wenn eine Auswertung bei Absenden des Formulars stattfindet. In diesem Fall muss die Befüllung unabhängig vom Zustand des Formulars vorgenommen werden.

6. Dynamische Formulare

In einigen Anwendungsfällen ist es notwenig, Formulare dynamisch nach Anforderung zu erstellen. Hierzu besitzt die Implementierung der Formular-TagLib (HtmlFormTag) die Methoden

addFormElement()
addFormContent()

und seit dem Release 1.7

addFormContentBeforeMarker()
addFormContentAfterMarker()
addFormElementBeforeMarker()
addFormElementAfterMarker()

Die ersten beiden Funktionen lassen sich dazu nutzen, Inhalte oder konkrete Formular-Elemente an das Ende des Formulars anzuhängen. Die zu letzt genannten Methoden sind dazu gedacht, Inhalte oder Formular-Elemente an konkreten Stellen zu platzieren. Zur Positionierung steht das <form:marker />-Tag zur Verfügung. Das Tag selbst generiert keine Ausgabe, sondern dient lediglich als Positionierungshilfe.

Die folgenden Kapitel sollen zeigen, wie ein dynamisches Formular zur Eingabe von Form-Koordinaten (Dreieck, Quadrat, ...) realisiert werden kann. Je nach Auswahl des Typs sollen die jeweils notwenigen Felder angezeigt werden. Bei Auswahl des Typs "square" werden vier Felder angezeigt ...

APF - Dynamische Formular-Generierung; Auswahl des Typs square

APF - Dynamische Formular-Generierung; Auswahl des Typs square

... und bei Auswahl von "triangle" drei:

APF - Dynamische Formular-Generierung; Auswahl des Typs triangle

6.1. Formular-Definition

Bei der Definition des Formulars sollte bereits bedacht werden, welche Art der Formular-Generierung angestrebt wird. Kommen die Methoden addFormElement() und/oder addFormContent() zum Einsatz, ist keinen Marker erforderlich. In diesem Beispiel wird jedoch ein Marker eingesetzt, da das Formular bereits Inhalte besitzt, die nach den dynamisch erzeugten Elementen angezeigt werden sollen.

Die folgende Code-Box zeigt das notwenige Formular mit einem Auswahlfeld. Bei der Implementierung wurde auf CSS-Formatierung verzichtet um die wesentlichen Elemente besser hervorheben zu können. Das Formular besteht dabei aus einem statisch definierten Auswahlfeld, das den Typ der geometrischen Form vorgibt und aus einem Marker-Tag, der als Positionierungshilfe für die dynamisch erzeugten Felder dient. Weiterhin wird ein Document-Controller definiert, der die gewünschten Felder dynamisch an der Stelle des Markers hinzufügt:

APF-Template

<@controller namespace="..." class="select_controller" @>
<core:addtaglib
   namespace="tools::form::taglib"
   class="HtmlFormTag"
   prefix="html"
   name="form"
/>
<html:form name="type" method="post">
  <table>
    <tr>
      <td>
        Please choose the desired form type:
        <form:select name="type">
          <select:option value="triangle">triangle</select:option>
          <select:option value="square">square</select:option>
        </form:select>
      </td>
      <td>
        <form:button name="submit" value="send" />
      </td>
    </tr>
    <tr>
      <td>
        <form:marker name="fields" />
      </td>
    </tr>
  </table>
</html:form>

6.2. Controller

Der Document-Controller übernimmt im beschriebenen Beispiel die Generierung der abhängigen Formularfelder, die je nach Auswahl angezeigt werden sollen. Hierzu wird im Controller zunächst definiert, welche Formular-Felder für welchen Typ angezeigt werden. Anschließend wird das Typ-Feld ausgewertet und das Formular mit Inhalten und Text-Feldern gemäß Typ ergänzt. Die folgende Code-Box zeigt die Implementierung des Document-Controllers:

PHP-Code

class select_controller extends BaseDocumentController {

   // specify form element container
   private $formElements = array();

   public function __construct(){

      // define form elements for the triangle
      $this->formElements['triangle'][] = array('label' => 'coord 1','name' => 'coordone');
      $this->formElements['triangle'][] = array('label' => 'coord 2','name' => 'coordtwo');
      $this->formElements['triangle'][] = array('label' => 'coord 3','name' => 'coordthree');

      // define form elements for the square
      $this->formElements['square'][] = array('label' => 'coord 1','name' => 'coordone');
      $this->formElements['square'][] = array('label' => 'coord 2','name' => 'coordtwo');
      $this->formElements['square'][] = array('label' => 'coord 3','name' => 'coordthree');
      $this->formElements['square'][] = array('label' => 'coord 4','name' => 'coordfour');

   }

   public function transformContent(){

      // get form reference
      $form = &$this->getForm('type');

      // get current decision
      $Select = &$form->getFormElementByName('type');
      $Option = &$Select->getSelectedOption();
      if($Option === null){
         $CurrentType = 'triangle';
      }
      else{
         $CurrentType = $Option->getAttribute('value');
      }

      // add form elements
      for($i = 0; $i < count($this->formElements[$CurrentType]); $i++){

         // add label
         $form->addFormContentBeforeMarker('fields',$this->formElements[$CurrentType][$i]['label'].': ');

         // add text field (name attribute is present to enable validation and presetting!)
         $currentElementID = $form->addFormElementBeforeMarker(
                                'fields',
                                'form:text',
                                array('name' => $this->formElements[$CurrentType][$i]['name'])
                             );

         // configure further form element attributes
         $currentElement = &$form->getFormElementByObjectID($currentElementID);
         $currentElement->setAttribute('style','width: 200px;');

         // add a line break
         $form->addFormContentBeforeMarker('fields','<br />');

      }

      // display form
      $form->transformOnPlace();

   }

}

6.3. Dynamische Filter und Validatoren

Mit dem Release 1.11 wurde das Konzept der Filter und Validatoren überarbeitet. Dies wirkt sich auch auf die Definition von dynamischen Formular-Elementen mit Filtern und Validatoren aus.

Wie im Kapitel Aufbau von Validatoren und Aufbau von Filtern besprochen wurde, werden Validatoren und Filter als Observer an Formular-Elemente geheftet. Bei dynamischen Formularen kann durch "Simulation" der <form:addvalidator />- und <form:addfilter />-Tags ebenso verfahren werden. Für die konkrete Anwendung bedeutet das, dass nach der Definition eines dynamischen Formular-Feldes der gewünschte Validator oder Filter über die Methoden addValidator() bzw. addFilter() angeheftet werden kann. Dies gestaltet sich in Code ausgedrückt im Kontext des in den letzten Kapiteln besprochenen Beispiels wie folgt:

PHP-Code

// gather button instance of the form
$button = &$form->getFormElementByName('submit');

// create dynamic form elements
for($i = 0; $i < count($this->formElements[$CurrentType]); $i++){

   // add label
   $form->addFormContentBeforeMarker('fields',$this->formElements[$CurrentType][$i]['label'].': ');

   // add text field (name attribute is present to enable validation and presetting!)
   $currentElementID = $form->addFormElementBeforeMarker(
                           'fields',
                           'form:text',
                           array('name' => $this->formElements[$CurrentType][$i]['name'])
                       );

   // configure further form element attributes
   $currentElement = &$form->getFormElementByObjectID($currentElementID);
   $currentElement->setAttribute('style','width: 200px;');

   // add filter to the current element
   $filter = new NoSpecialCharactersFilter($currentElement,$button);
   $currentElement->addFilter($filter);

   // add validator to the current element
   $validator = new TextLengthValidator($currentElement,$button);
   $currentElement->addValidator($validator);

   // add a line break
   $form->addFormContentBeforeMarker('fields','<br />');

}

Bei der Definition von dynamischen Validatoren und Filtern muss die Reihenfolge beachtet werden. Damit keine unerwünschten Validierungs-Ergebnisse auftreten, müssen Filter stets vor Validatoren ausgeführt werden.

Bitte beachten Sie, dass Prüfungen eines Formulars per

PHP-Code

$form->isValid()

erst nach dem Hinzufügen von dynamischen Validatoren und Filtern erfolgen dürfen. Andernfalls werden fehlerhafte Inhalte nicht erkannt.

6.4. Weitere Hinweise

Ein APF-Formular-Element benötigt bereits bei der Erstellung des Objekts die Information über den Namen des Feldes. Ist dieser nicht bekannt, kann es nicht vorausgefüllt oder validiert werden. Um die Presetting und Validierung von Formular-Elementen nutzen zu können besitzen die Methoden addFormElement(), addFormElementBeforeMarker() und addFormElementBeforeMarker() einen optionalen, dritten Parameter. Dieser erwartet eine assoziative Liste von Tag-Attributen, die dem Formular-Tag bei der Erstellung mitgegeben werden. Es daher sinnvoll, der Methode mindestens den Namen des Feldes in der Form

PHP-Code

array(
      'name' => 'current_name'
     )

als drittes Argument mitzugeben. Dies kann unter Umständen auch für die spätere Adressierung der Objekte über die Methoden getFormElementByName() und getFormElementByID() von Interesse sein.

7. Erweiterung von Formular-Elementen

Das APF-Konzept des Page-Controllers erlaubt es, eigene Taglibs zu schreiben um wiederverwendbare Elemente zu schaffen. Dies setzt sich auch bei den Formularen fort. Eigene Formular-Elemente können bequem mit dem <form:addtaglib />-Tag, dessen Funktion identisch zum <core:addtaglib /> ist, in ein bestehendes Formular eingebunden werden.

Die Besonderheit der Formular-Taglibs bzw. Formular-Elemente ist, dass diese die abstrakte Klasse AbstractFormControl implementieren. Sie genügen damit einem erweiterten Tag-Interface, das vom <html:form />-Tag behandelt werden kann. Die Erweiterung des Funktions-Umfangs besteht insbesondere in der Validierung und Filterung.

Die folgenden drei Kapitel beschreiben die Erstellung von eigenen Formular-Elementen, Validatoren und Filter und geben Beispiele für die Implementierung.

7.1. Formular-Felder

Wie bereits angedeutet, ist eine Formular-Element im APF durch die abstrakten Basis-Klasse AbstractFormControl definiert. Um ein neues Formular-Element zu implementieren, muss diese nun um die gewünschten Funktionen erweitert werden.

Als Beispiel soll im Folgenden ein Formular-Element besprochen werden, das zum Schutz eines Formulars ein verstecktes Text-Feld erzeugt und das im darauffolgenden Kapitel mit einem speziellen Validator belegt werden kann. Ist das Feld gefüllt, ist davon auszugehen, dass es sich um eine automatisierte Anfrage handelt. Ist das Feld nicht gefüllt, wird das Formular als valide betrachtet, sofern alle anderen Felder ebenfalls valide sind. In diversen Blog-Einträgen werden diese Art von Felder auch als honeypot fields bezeichnet.

Beginnen wir zunächst mit dem Rumpf des Elements. Wie zuvor beschrieben soll ein Text-Feld ausgeben werden, das via CSS versteckt wird. Um diese Funktion zu gewährleisten, muss das neue Formular-Element bei der Transformation die entsprechende HTML-Ausgabe zurückliefern:

PHP-Code

class HoneypotFormControlTag extends AbstractFormControl {
   public function transform(){
      $htmlCode  = (string)'<input ';
      $htmlCode .= $this->getAttributesAsString($this->attributes);
      $htmlCode .= 'type="text" ';
      $htmlCode .= 'style="margin: 0px; padding: 0px; display: none; height: 0px; width: 0px;"';
      $htmlCode .= ' />';
      return $htmlCode;
   }
}

Vor der Version 1.14 muss die Zeile

PHP-Code

$htmlCode .= $this->getAttributesAsString($this->__Attributes);

auf Grund von API-Änderungen durch

PHP-Code

$htmlCode .= $this->__getAttributesAsString($this->__Attributes);

ersetzt werden.

Da die Rückgabe des Validitäts-Status, die Möglichkeit Validatoren und Filter anzuheften und Presetting der eingegebenen Werte beim Absenden bereits in der Klasse AbstractFormControl enthalten ist, stellt die oben gezeigte Klasse bereits den vollständig Funktionsumfang dar.

Um das neue Element in einem Formular verwenden zu können, muss dieses mit Hilfe des <form:addtaglib />-Tags im Formular bekannt gemacht werden:

APF-Template

<core:addtaglib
   namespace="tools::form::taglib"
   class="HtmlFormTag"
   prefix="html"
   name="form"
/>
<html:form name="CheckedForm">
   ...
   <form:addtaglib
      namespace="..."
      class="HoneypotFormControlTag"
      prefix="form"
      name="honeypot"
   />
   <form:honeypot name="check" />
   ...
</html:form>

Die eigentliche Funktionalität des honepot field steckt in der Validierung. Diese wird im nächsten Kapitel besprochen.

7.2. Validatoren

Validatoren werden ab dem Release 1.11 von Formular-Elementen getrennt definiert und diesen als Observer mitgegeben. Um diesen Mechanismus zu unterstützen, muss das Formular-Element jedoch darauf vorbereitet sein. Im Fall des im vorangegangenen Kapitels beschriebenen Honeypot-Feldes ist die Validierungs-Funktionalität bereits durch die Basis-Klasse AbstractFormControl definiert. Bei der Validierung wird dem Validator der Inhalt des Attributs value übergeben und dieser kann entsprechend darauf reagieren.

Der zu erstellende HoneypotValidator ist im Wesentlichen ein Text-Feld-Validator, daher kann die im APF-Release enthaltene Klasse TextFieldValidator als Basis für die Implementierung verwendet werden. Diese leitet von AbstractFormValidator ab, der Basis-Klasse für alle Formular-Validatoren.

Jeder Validator implementiert die Methode validate(), die den zu validierenden Inhalt entgegen nimmt. In unserem Fall erhält die Funktion den Inhalt des Honeypot-Feldes. Dieses muss im Positiv-Fall leer sein, sofern dort Zeichen enthalten ist, muss das Feld als invalid gekennzeichnet werden. Hierzu kann folgender Code verwendet werden:

PHP-Code

class HoneypotValidator extends TextFieldValidator {
   public function validate($input){
      if(empty($input)){
         return true;
      }
      return false;
   }
   ...
}

Da die Klasse TextFieldValidator bereits die Benachrichtigung eines "echten" Text-Feldes übernimmt wird das Feld im Fehlerfall mit einer CSS-Klasse versehen, die zur optischen Markierung genutzt werden kann. Dies ist im aktuellen Anwendungsfall nicht erforderlich und muss daher unterdrückt werden. Hierzu überschreiben wir die Methode notify() der Klasse TextFieldValidator, die aufgerufen wird, sofern ein Feld nicht erfolgreich validiert werden konnte:

PHP-Code

class HoneypotValidator extends TextFieldValidator {
   public function validate($input){
      if(empty($input)){
         return true;
      }
      return false;
   }

   public function notify(){
      $this->control->markAsInvalid();
      $this->notifyValidationListeners($this->control);
   }
}

Die Methode enthält im Gegensatz zur Implementierung in der Klasse TextFieldValidator die Zeile

PHP-Code

$this->markControl($this->control);

nicht. Damit haben wir das optische Markieren des fehlerhaften Formular-Feldes ausgeschaltet.

Die Anwendung des Validators gestaltet sich dann im Zusammenhang mit dem Honeypot-Textfeld wie folgt:

APF-Template

<core:addtaglib
   namespace="tools::form::taglib"
   class="HtmlFormTag"
   prefix="html"
   name="form"
/>
<html:form name="CheckedForm">
   <form:addtaglib
      namespace="..."
      class="HoneypotFormControlTag"
      prefix="form"
      name="honeypot"
   />
   <form:honeypot name="check" />
   <form:addvalidator
      namespace="..."
      class="HoneypotValidator"
      control="check"
      button="send"
   />
   <form:button name="send" value="Send" />
</html:form>

Der Validator kann durch die eigentständige Definition auch auf andere Text-Felder angewendet werden, die Text-Validierung unterstützen. Hierzu zählen alle im Release mitgelieferten Text- und Text-Area-Taglibs.

7.3. Filter

Für das Honeypot-Feld wird kein Validator benötigt. Aus diesem Grund soll in diesem Kapitel ein Filter implementiert werden, mit dem deutsche Umlaute durch die Laut-Entsprechungen (z.B. ä -> ae) ersetzt werden.

Der GermanUmlautsFilter implementiert dabei die Klasse AbstractFormFilter - die wie der AbstractFormValidator bei den Validatoren - das Interface eines Formular-Filters beschreibt.

Jeder Filter implementiert dabei die Methode filter(). Diese nimmt den zu filternden Inhalt entgegen, führt die gewünschte Funktion aus und gibt den gefilterten Inhalt wieder zurück.

Das Grundgerüst des Filters kann damit durch folgenden Code beschrieben werden:

PHP-Code

class GermanUmlautsFilter extends AbstractFormFilter {
   public function filter($input){
      return $input;
   }
}

Die Funktionalität des Filters besteht aus einem einfachen Aufruf der Funktion str_replace():

PHP-Code

class GermanUmlautsFilter extends AbstractFormFilter {
   public function filter($input){
      return str_replace(
         array('ä','ö','ü','Ä','Ö','Ü','ß'),
         array('ae','oe','ue','Ae','Oe','Ue','ss'),
         $input
      );
   }
}

Die Anwendung des Filters gestaltet sich dann im Zusammenhang mit einem Text-Feld oder einer Text-Area wie folgt:

APF-Template

<core:addtaglib
   namespace="tools::form::taglib"
   class="HtmlFormTag"
   prefix="html"
   name="form"
/>
<html:form name="UmlautsForm">
   <form:text name="name" />
   <form:area name="comment" />
   <form:addfilter
      namespace="..."
      class="GermanUmlautsFilter"
      control="name|comment"
      button="send"
   />
   <form:button name="send" value="Send" />
</html:form>

7.4. MultiFileUpload

Seit Release 1.16 wird seitens des APF auch ein weiteres Tool zum Erzeugen von Datei-Uploads mit Vorschau-Funktion sowie prozentualer Fortschrittanzeige angeboten: der MultiFileUpload. Ausführliche Informationen dazu entnehmen Sie bitte der Dokumentation im Wiki: MultiFileUpload im Wiki.

8. Sichtbarkeit von Formular-Elementen

Mit dem Release 1.17 wurden die Formular-Elemente um ein Sichtbarkeitsmerkmal erweitert. Dieses wird bei der Transformation dazu genutzt zu entscheiden, ob ein Formular-Element dargestellt wird oder nicht. Dies ermöglicht Ihnen das aus- bzw. einblenden von Formular-Elemente via (Document-)Controller.

Zusätzlich zum Sichtbarkeits-Status lassen sich pro Formular-Element abhängige Elemente definieren, die beim Ausblenden ebenso ausgeblendet werden. So lassen sich - in gewissen Grenzen - ganz einfach dynamische Formulare erzeugen.

Die folgenden Kapitel beschreiben die möglichen Anwendungsfälle und die zugehörige Implementierung.

8.1. Manipulation der Sichtbarkeit per Controller

In Version 1.17 wurde die Klasse AbstractFormControl um die Methoden

hide()
show()
isVisible()

erweitert. Da alle Formular-Elemente von dieser ableiten, steht die Sichtbarkeits-Definition grundsätzlich in jedem Element zur Verfügung. Weitere Hinweise finden Sie im Kapitel Unterstützte Formular-Elemente.

Die Methode isVisible() kann dazu genutzt werden um den aktuellen Status zu in einem Controller oder einem Tag zu erfragen. show() setzt das Element auf den Status sichtbar, hide() versteckt es.

Standardmäßig ist jedes Formular-Element zunächst sichtbar.

Als Beispiel soll uns das in der Code-Box abgebildete Login-Formular dienen:

APF-Template

<html:form name="log-in">
   <label for="user-name">Benutzer-Name:</label>
   <form:select name="user-name" id="user-name" />

   <label for="password">Passwort:</label>:
   <form:text name="password" id="password" />

   <label for="stay-logged-in">Eingeloggt bleiben?</label>:
   <form:checkbox name="stay-logged-in" id="stay-logged-in" />

   <form:button name="log-in" value="Anmelden" />
</html:form>

Wie aus der Code-Box zu entnehmen ist, beinhaltet das Formular je ein Feld für Benutzer-Namen und Passwort sowie ein Feld, das die dahinterliegende Applikation dazu veranlasst eine permanente Anmeldung zu erzeugen.

Um die Checkbox zur Aktivierung der permanenten Anmeldung auszublenden kann folgender Controller-Code verwendet werden:

PHP-Code

class LoginController extends BaseDocumentController {

   public function transformContent() {

      $form = &$this->getForm('log-in');

      $checkbox = &$form->getFormElementByName('stay-logged-in');
      $checkbox->hide();

      ...

      $form->transformOnPlace();

   }

}

Bei der Anzeige des Formulars ist die Checkbox nun nicht mehr sichtbar und damit für den Anwender nicht mehr nutzbar.

Bitte beachten Sie die Hinweise in Kapitel 8.4 zur Implementierung von eigenen Formular-Elementen unter Nutzung der Sichtbarkeits-Definition.

Bitte beachten Sie, dass die per hide() ausgeblendeten Elemente weiterhin in Ausführung der Validierung und Filterung einbezogen werden. Dies kann dazu führen, dass nicht mehr sichtbare Elemente einen Fehler auslösen und das Formular dadurch nicht mehr absendbar ist. Da das Feld nicht sichtbar ist, kann der Benutzer dann leider keinen Einfluss mehr darauf nehmen.

Beinflussen Sie die Sichtbarkeit von Formular-Elementen im Controller, achten Sie bitte darauf, dass ein ausgeblendetes Feld entweder per

PHP-Code

$checkbox = &$form->getFormElementByName('stay-logged-in');
$checkbox->hide();
$checkbox->markAsValid();

im Controller als valide oder definieren Sie für dieses Feld einen optionalen Validator (siehe Formulare).

8.2. Ausblenden von abhaengigen Elementen

Nachteil der in Kapitel 8.1. beschriebenen Vorgehensweise: das Label-Element der Checkbox weiterhin angezeigt wird. Dies lässt sich sehr einfach dadurch umgehen, dass das als HTML-Tag definierte Label als APF-Formular-Tag ausgeführt wird. Dieser lässt sich dann mit Hilfe des Attributes dependent-controls als abhängiges Element der Checkbox markieren und wird beim Ausblenden der Checkbox ebenso ausgeblendet.

Die Definition des Formulars erweitert sich dadurch wie folgt:

APF-Template

<html:form name="log-in">
   <label for="user-name">User name:</label>
   <form:select name="user-name" id="user-name" />

   <label for="password">Password:</label>:
   <form:text name="password" id="password" />

   <form:label name="stay-logged-in-label" for="stay-logged-in">Stay logged-in?</form:label>:
   <form:checkbox
      name="stay-logged-in"
      id="stay-logged-in"
      dependent-controls="stay-logged-in-label"
   />

   <form:button name="log-in" value="Anmelden" />
</html:form>

Die Definition von abhängigen Elementen ist rekursiv möglich. Wird beispielsweise das Passwort-Feld als abhängiges Element des Label-Tags definiert, so werden beim Ausblenden der Checkbox sie selbst, der Label-Tag und das Passwort-Feld ausgeblendet.

Möchten Sie pro Feld mehrere abhängige Felder referenzieren, so trennen Sie die Namen der Felder jeweils mit einem | (Pipe-Zeichen). Beispiel:

Code

stay-logged-in-label|password

8.3. Unterstützte Formular-Elemente

Die Sichtbarkeits-Definition wird nicht von allen Formular-Elementen unterstützt. Dies hat den Grund, dass für bestimmte Elemente wie z.B. der <form:hidden />-Tag bereits vor Release 1.17 keine sichtbare Darstellung besitzen und bei Elementen wie dem <form:error />-Tag eine Sichtbarkeit fachlich nicht sinnhaft ist.

Die folgende Liste zeigt die Tags, die die Definition der Sichtbarkeit unterstützen:

<form:button />
<form:imagebutton />
<form:reset />
<form:checkbox />
<form:file />
<form:label />
<form:multiselect />
<form:select />
<form:password />
<form:radio />
<form:text />
<form:area />
<form:date />
<form:time />

8.4. Implementierung von eigenen Formular-Elementen

Die Definition der Sichtbarkeit ist in der Klasse AbstractFormControl verankert und steht damit jedem Formular-Element-Typ zur Verfügung. Da die Auswirkung der Sichtbarkeit jedoch jedes Element selbst definiert muss bei der Implementierung von eigenen Formular-Tags der Status bei der Erzeugung der Ausgabe beachtet werden oder bewusst ignoriert werden.

Der Sichtbarkeits-Status wird in der Klassenvariablen AbstractFormControl::$isVisible verwaltet. Der Wert true entspricht dabei dem Status sichtbar, bei false werden die in Kapitel 8.3. nicht angezeigt.

Soll der Sichtbarkeits-Status bei der Ausgabe Ihres Formular-Elements beachtet werden, so können Sie die folgende Code-Box als Vorlage nutzen:

PHP-Code

class MyCustomFormTag extends AbstractFormControl {

   ...

   public function transform() {
      if ($this->isVisible) {
         return '...what ever your tag generates as its output...';
      }
      return '';
   }

   ...
}

Ein weiterer Anwendungsfall bei der Implementierung von eigenen Formular-Elementen ist das direkte Ausblenden von benachbarten Formular-Elementen im Tag-Code. Dies kann notwendig sein, wenn Sie z.B. ein Formular-Element eine direkte Abhängigkeit zu einem anderen besitzt.

Das Ausblenden aller in einem Formular enthaltenen Check-Boxen lässt sich beispielsweise wie folgt in einem eigenen Formular-Tag abbilden:

PHP-Code

class MyCustomFormTag extends AbstractFormControl {

   ...

   public function onAfterAppend() {

      $form = &$this->getParentObject();
      $controls = $form->getFormElementsByTagName('form:checkbox');

      foreach ($controls as $control) {
         $control->hide();
      }

      ...

   }

   ...
}

Kommentare

Möchten Sie den Artikel eine Anmerkung hinzufügen, oder haben Sie ergänzende Hinweise? Dann können Sie diese hier einfügen. Die bereits verfassten Anmerkungen und Kommentare finden Sie in der untenstehenden Liste.

Für diesen Artikel liegen aktuell keine Kommentare vor.

Verwendung von Formularen

Kommentare

QUICKNAVI