html_form_element($e, $data = array ()):

HTML-Code für einzelne Formular-Elemente erzeugt die Funktion ´html_form_element´. Die Werte des gegebenen Datentupels $data sind dabei in der Ausgabe ersetzbar, d.h. vor Ausgabe der Formular-Quelltextes werden Werte aus $data durch die Funktion ´html_substitute_data´ ggf. hinein-substituiert, wobei alle von ´html_substitute_data´ unterstützten Ersetzungen erlaubt sind, aber nur Variablen ersetzt werden, die auch im Datensatz $data vorhanden sind ($allflag=0 für ´html_substitute_data´) (siehe ´html_substitute_data´). Funktionsparameter sind:

• [$e:]Array von Parametern, die das Formelement beschreiben: Dabei ist der Parameter "type" der wichtigste, denn er bestimmt die Art des Form-Elementes. Im folgeneden wird danach unterschieden:

• type="text" oder type="password": Formelement für Text (<input type=text...> bzw <input type=password...>); weitere Parameter in $e sind hierfür:
  • [name:]name des Formularelements, name-Attribut des input-Tags
  • [value:]voreingestellter Wert, value-Attribut des input-Tags, wird htmlencoded
  • [size:]Länge der Eingabezeile (sichtbar), size-Attribut des input-Tags
  • [maxlength:]maximale Länge der Eingabe, maxlength-Attribut des input-Tags
  • [readonly:]boolsches Flag, falls true, ist Formularelement nur lesbar, d.h. readonly-Attribut des input-Tags wird gesetzt
• type="hidden": Formelement für versteckte Werte (<input type=hidden...>); weitere Parameter in $e sind hierfür:
  • [name:]name des versteckten Wertes, name-Attribut des input-Tags
  • [value:]versteckter Wert, value-Attribut des input-Tags, wird htmlencoded
• type="textarea": Formelement für mehrzeiligen Text (<textarea...>); weitere Parameter in $e sind hierfür:
  • [name:]name der textarea, name-Attribut des textarea-Tags
  • [rows:]Anzahl Zeilen, rows-Attribut des textarea-Tags
  • [cols:]Anzahl Spalten, cols-Attribut des textarea-Tags
  • [wrap:]Zeilenumbruchsverhalten, wrap-Attribut des textarea-Tags: z.B. physical, virtual, off
  • [readonly:]boolsches Flag, falls true, ist Formularelement nur lesbar, d.h. readonly-Attribut des textarea-Tags wird gesetzt
  • [content:]voreingestellter Wert, d.h. Inhalt des textarea-Tags, wird htmlencoded
• type="select": Formelement für Auswahlmenü (<select...>; weitere Parameter in $e sind hierfür:
  • [name:]name des Auswahlmenüs, name-Attribut des select-Tags
  • [size:]Größe des Menüs (sichtbar), d.h. Anzahl Zeilen, size-Attribut des select-Tags
  • [multiple:]boolsches Flag, falls true ist dieses Menü ein mehrfaches Auswahlmenü, d.h. multiple-Attribut des select-Tags wird gesetzt
  • [values:]Liste der möglichen Auswahlwerte; Dabei ist ein Auswahlelement selbst ein Array mit dem Parameter "<value>" für den eigentlichen Wert und mit dem Parameter "<content>" für die Beschriftung.
    In jedem dieser Werte werden Datentupel-Werte von $data zu Beginn durch ´html_substitute_data´ ggf. substituiert (z.b. wird $[keyname] in einem Wert durch $data[keyname] (htmlencoded) ersetzt, weitere Ersetzungen siehe ´html_substitute_data´, es werden alle von ´html_substitute_data´ möglichen Substitutionen erlaubt, aber nur Variablen ersetzt, die auch in $data vorhanden sind).
    Pro Wert in der Liste wird ein option-Tag mit value="<value>" mit Inhalt <content> ausgegeben.
    Bei jedem Wert, der dabei mittels dem Parameter "selected" bzw. "selected2" (siehe unten) als zu Beginn markiert erkannt wird, wird in seinem option-Tag das selected-Flag gesetzt.
  • [selected:]zu Beginn ausgewählter Wert, muss in $values vorhanden sein, d.h. er sollte als value-Komponente eines Elements im values-Array vorkommen.
    Falls das multiple-Flag (siehe oben) gesetzt ist, kann dies eine Liste der zu Beginn ausgewählten Werte statt einem einzelnen Wert sein. Sonst sollte es nur ein einzelner Wert sein.
  • [selected2:]boolsches Flag; falls gesetzt, wird in jedem option-Tag statt dem festen String-Wert für das selected-Attribut "selected" eine durch ´html_substitute_data´ später auswertbare bedingte Ausgabe für "selected" ausgegeben. Dabei wird bei späterem Auswerten durch ´html_substitute_data´ ($subst_type & 8 == 1) nur dann tatsächlich der String "selected" in einem option-Tag ausgegeben, wenn der zum option-Tag gehörende Wert (aus $values) gleich einem bei der späteren Auswertung an ´html_substitute_data´ übergebenen Vergleichswert ist.
    Falls selected2 benutzt wird sollte selected nicht verwendet werden.
    selected2 ist bei der Verwendung von Schablonen nützlich, d.h. man man erzeugt mit ´html_form´ eine Schablone für mehrere Formulare, derren tatsächliche Datensätze bei Aufruf von ´html_form´ noch nicht bekannt ist. Eine solcher Schablonen-Formular-Code kann z.B. im Parameter datacell_format des $param-Arrays für ´html_table´ verwendet werden, um für jedes in einer HTML-Tabelle angezeigte Datentupel einen eigenes Formular in der Tabellenzeile zu erzeugen (mittels Auswertung durch ´html_substitute_data´)
• type="radio" oder type="checkbox": Formelement für Radio- bzw. Check-Box-Buttons (<input type=radio...> bzw <input type=checkbox...>); weitere Parameter in $e sind hierfür:
  • [name:]name der Radio/Checkbox, name-Attribut des input-Tags
  • [value:]Wert der Box, value-Attribut des input-Tags, wird htmlencoded
  • [content:]Beschriftung der Box, Inhalt des input-Tags, wird htmlencoded
  • [content_htmlpre:]Beschriftung der Box als HTML-Code, Inhalt des input-Tags, wird vor Wert von "content" ausgegeben
  • [content_htmlpost:]Beschriftung der Box als HTML-Code, Inhalt des input-Tags, wird nach Wert von "content" ausgegeben
  • [content_html:]Beschriftung der Box als HTML-Code, Inhalt des input-Tags; Alternative der Angabe der Beschriftung zu content/content_htmlpre/content_htmlpost
  • [checked:]boolsches Flag, falls true, so ist diese Box zu Beginn gecheckt, d.h. checked-Attribut des input-Tags gesetzt
  • [checked2: ]boolsches Flag, falls gesetzt, wird im input-Tag statt dem festen String-Wert für das checked-Attribut "checked" eine durch ´html_substitute_data´ später auswertbare, bedingte Ausgabe von "checked" ausgegeben. Dabei wird bei späterem Auswerten durch ´html_substitute_data´ nur dann tatsächlich der String "checked" in im input-Tag ausgegeben, wenn der Wert der Box "value" gleich einem bei der späteren Auswertung an ´html_substitute_data´ übergebenen Vergleichswert ist.
    Falls checked2 benutzt wird sollte checked nicht verwendet werden.
    checked2 ist bei der Verwendung von Schablonen nützlich, d.h. man man erzeugt mit ´html_form´ eine Schablone für mehrere Formulare, derren tatsächliche Datensätze bei Aufruf von ´html_form´ noch nicht bekannt ist. Eine solcher Schablonen-Formular-Code kann z.B. im Parameter datacell_format des $param-Arrays für ´html_table´ verwendet werden, um für jedes in einer HTML-Tabelle angezeigte Datentupel einen eigenes Formular in einer Datenzeile zu erzeugen (mittels Auswertung durch ´html_substitute_data´).
• type="reset" oder type="submit": Formelement für Reset- bzw Submit-Button (<input type=reset...> bzw <input type=submit...>); weitere Parameter in $e sind hierfür:
  • [name:]name des Buttons, d.h. name-Attribut des input-Tags
  • [value:]Beschriftung des Buttons, d.h. value-Attribut des input-Tags, wird htmlencoded
• type="html": kein echtes Formelement, sondern Möglichkeit bei einem Aufruf von ´html_form´ bzw. ´html_form_elements´ beliebigen HTML-Code zwischen echte Formelemente zu setzten ohne einzelne Aufrufe zu ´html_form_element´ machen zu müssen. Einziger weiterer Parameter in $e ist:
  • [content:]beliebiger HTML-Code, wird unmittelbar in Ausgabe übernommen
• type="constant": kein echtes Formelement, sondern sozusagen ein Readonly-Select-Menü:
  Verhält sich ähnlich wie select-Formelement bei der Ausgabe, allerdings wird der aktuelle Wert nur angezeigt und kein echtes Formelement aufgebaut, so dass vom HTML-Benutzer keine Änderung über diese Formelement möglich ist.
  Weitere Parameter in $e sind die gleichen wie bei type="select",
  Verwendung findet dieses Pseudoelement daher bei der Schablonenbenutzung, wo bei Aufbau des Formular-Quellcodes die tatsächlichen Werte des Datentupels noch nicht bekannt sind und später mittels ´html_substitute_data´ mit einem dann übergebenen Wert verglichen werden, womit dann entschieden werden kann, welcher Auswahlwert zu Beginn ausgewählt ist und damit angezeigt wird.
• bei allen Typen sind stets noch folgende Parameter in $e möglich:
  • [htmlpre:]beliebiger HTML-Code, der vor dem Formelement ausgegeben wird
  • [htmlpost:]beliebiger HTML-Code, der nach dem Formelement ausgegeben wird

• [$data:]Ein gegebenes Datentupel, wobei ein Datentupel Datentupel ein assoziatives Array, bestehend aus beliebigen Key/Value-Paaren ist, z.b. wie es von db_query als Repräsentation einer Zeile eines SQL-Ergebnisses zurückgeliefert wird.

Rückgabe von ´html_form_element´ ist ein String, der den HTML-Quelltext für das Formelement enthält.