Formulare

für die Liste aller Seiten

Diese Seite erklärt, wie man Eingabeformulare in Wikiseiten einbetten kann.

Eingabeformulare behandeln die Eingaben eigentlich nicht — dies Feature erlaubt einfach nur die Erzeugung von Formularen innerhalb einer Wikiseite. Die Auswertung von Formularen findet man in den Kochbüchern (s. u.).

Markup

Zwei Direktiven braucht man, um ein Formular zu beginnen und zu beenden:

    (:input form "url" method:)
    ...
    (:input end:)

Die (:input form:)-Direktive startet ein Formular, das Daten an url (optional action=url) mit der Methode method (optional method=method) sendet. Wenn der Url weggelassen wird, wird die aktuelle Seite angenommen. Der Url muss in Anführungszeichen gesetzt sein, wenn er nicht über action= angegeben wurde. Ein optionaler Name="Formularname" kann angegeben werden, um das Formular zu benennen. Man kann explizit action=url oder method=get angeben oder man benutzt sie als positionierte Parameter.

Wenn Ihre Site ?n=Gruppe.Seite benutzt, um den Seitennamen anzugeben, dann erlaubt ein zusätzliches Feld (:input hidden name=n value={$FullName}:) dem Formular, die Daten an die aktuelle Seite zu senden als Alternative zur Angabe des vollständigen URLs in action=url.

Die (:input end:)-Direktive schließt das aktuelle Formular.

Anmerkung: Dies Feature garantiert nicht, dass die Ausgabe des Formulars korrektes HTML ist – es nimmt an, dass der Autor ein bisschen was von der Sache versteht. (:input form:) und (:input end:) sollten nicht innerhalb von Tabellen erscheinen und alle Formularfelder und Kontrollelemente sollten innerhalb des (:input form:) ... (:input end:)-Blockes stehen. Bedenken Sie auch, dass nicht alle Browser alle Feldtypen unterstützen - so wie in 2023 das (:input month:)-Feld noch immer nicht unterstützt wird von Firefox und Safari.

Standardeingabeelemente

Die Standardeingabeelemente sind

    (:input text name "value" size=n:)
    (:input hidden name "value":)
    (:input password name "value":)
    (:input search name "value":)
    (:input number name "value" min=x max=y step=z:)
    (:input email name "value":)
    (:input tel name "value":)
    (:input url name "value":)
    (:input date name "value":)
    (:input month name "value":) 
    (:input color name "value":) 
    (:input radio name "value" label checked=checked:)
    (:input checkbox name "value" label checked=checked:)
    (:input datalist id "value":) - siehe datalist
    (:input select name "value" "label":) - sieheselect
    (:input default default-name "default-value":) - siehe default
    (:input textarea name [=value=] rows=n cols=n:)
    (:input file name "label":)
    (:input image name "src" "alt":)
    (:input reset name "label":)
    (:input button name "value":)
    (:input pmtoken:)  - siehe pmtoken
    (:input submit name "value":)

Dabei werden name und value in der HTML-Syntax geschrieben: name="addr" value="808 W Franklin".

Ein PmWiki-spezifisches Kontrollelement ist "e_author", das mit dem aktuellen Autorennamen vorausgefüllt ist. Wenn $EnablePostAuthorRequired gesetzt ist, hat es ein required="required" Attribut:

    (:input e_author:)  

Für die meisten Elemente hat die Direktive die Form:

    (:input ''type'' ''name'' ''value'' ''parameter=value'':)

wobei type der Typ des Eingabeelementes (Beschreibung unten), name der Name des Elements und value der Anfangswert ist. Parameter werden benutzt, um die zusätzlichen Attribute des Elements anzugeben. Wenn value Leerzeichen enthält, gehört es in Anführungszeichen. Wenn es Zeilenumbrüche enthält (Textarea, hidden Elements), schließen Sie es in [=...=] ein.

Das Folgende erstellt beispielsweise ein Texteingabefeld mit eine Größe von 30 Zeichen.

(:input text authorid "Jane Doe" size=30:)

Ein Autor kann auch den Namen und den Wert direkt angeben mit name=- und value=-Attributen.

(:input text name=authorid value="Jane Doe" size=30:)

Für das Textarea-Element kann seit PmWiki 2.2.0beta45 ein Wert gesetzt werden. Schließen Sie den Wert in [=...=] ein, wenn er Leerzeichen oder Zeilenumbrüche enthält.

Das submit-Element wird häufiger geschrieben als:

    (:input=] submit value="label":)

Hier ist ein komplexeres Beispiel, etwa für eine Aufforderung sich anzumelden:

(:input form "http://www.example.com":)
(:input hidden action login:)
||     Name:||(:input text username:)    ||
|| Passwort:||(:input password password:)||
||          ||(:input checkbox terms yes "Bedingungen akzeptiert"  required=required:) ||
|| ||(:input submit value="Anmelden":) ||
(:input end:)

Generelle Formularfeldattribute

• (:input ... focus=1:) Setzt man focus=1, erhält das Element den anfängliche Focus, wenn das Formular das erste Mal erscheint.
• Die folgenden erweiterten HTML-Attribute werden unterstützt: name, value, id, class, rows, cols, size, maxlength, action, method, accesskey, tabindex, multiple, checked, disabled, readonly, enctype, src, alt, title, required, placeholder, autocomplete, min, max, step, pattern, list, formnovalidate, accept, autofocus, lang, form. Für eine weiterführende Beschreibung, siehe ihre Entsprechungen unter w3c reference: HTML5 form attributes (nicht alle von ihnen können für jedes Formularelement eingesetzt werden).
• Für Checkboxen und Radiobuttons wird der Text des "label"-Attributs hinter dem Eingabeelement als ein Label-Element angezeigt. Ein Klick darauf aktiviert oder deaktiviert das Eingabeelement. Das Label darf nur reiner Text sein (ohne Inlineformatierung wie fett oder Verweise).
• Zusätzlich zu diesen Atrributen können die folgenden Attribute für die Zugänglichkeitverbesserung benutzt werden: role, aria-label, aria-labelledby, aria-describedby, aria-expanded, aria-pressed, aria-current, aria-hidden.
• Zusätzlich zu den vorgegebenen Attributen können Sie selbst erstellte data-Attribute wie data-some-variable=value oder data-other="Some data" einsetzen (benutzbar in eigenen JavaScripts, CSS oder einigen Libraries). Das Attribut muss mit "data-" beginnen und darf nur lateinische Kleinbuchstaben [a-z] und Bindestriche [-] enthalten.
  Das kann in der config.php-Datei mit der Zeile $EnableInputDataAttr = 0; abgeschaltet werden.
• (:input form ... data-pmconfirm="Daten wirklich senden?":) oder (:input submit ... data-pmconfirm="Fortfahren?":), wird, wenn das Formular abgeschickt wird oder wenn der Benutzer auf die Schaltfläche klickt, eine Bestätigungsbox mit der Frage öffnen, die dem Benutzer erlaubt, fortzufahren oder abzubrechen (seit PmWiki 2.3.22). Das funktioniert für die Elemente form, submit, reset und button. Der Text in Anführungszeichen wird dem Benutzer gezeigt. Beispiel:

(:input button bname "Alle Seiten löschen" data-pmconfirm="Sind Sie sicher, dass alle Seiten gelöscht werden sollen?  Das kann nicht rückgängig gemacht werden.":)

• Alle nicht unterstützten Attribute im Wiki-Markup werden nicht in der HTML-Ausgabe erscheinen.

(:input select ... :)

Die Basis für eine Auswahlbox ist eine Liste von Optionen:

(:input form:)
(:input select name=abc value=1 label=alpha :)
(:input select name=abc value=2 label=beta  :)
(:input select name=abc value=3 label=gamma :)
(:input submit:)
(:input end:)

Die Werte können (ohne Parameternamen) durch ihre Position angegeben werden.

 (:input select abc 1 alpha :)

Sie können die Größe der Auswahlbox angeben:

 (:input select abc 1 alpha size=3 :)

Sie können eine Auswahlbox für Mehrfachwahlen angeben (nur das erste Item muss die Attribute "size=3 multiple" haben):

 (:input select abc 1 alpha size=3 multiple:)

Damit ein Element ausgewählt erscheint, benutzen Sie: selected=selected:

 (:input select abc 2 beta selected=selected:)

Anmerkung: Damit zwei Auswahlboxen nebeneinander erscheinen, müssen Sie ihnen nicht nur verschiedene name=-Parameter geben, Sie müssen zwischen sie auch noch einen Trenner setzen, d. h. ein Zeichen, ein   oder wenigstens eine Nullsequenz [==].

(:input form:)
(:input select name=FIRST value=1:)(:input select name=FIRST value=2:)[==]
(:input select name=SECOND value=3:)(:input select name=SECOND value=4:)
(:input end:)

Beachten Sie, dass in der HTML-Ausgabe nur die Attribute label, value und selected auf das <option>-HTML-Tag angewendet werden. Alle anderen Attribute einschließlich name, id, class und title werden auf das umschließende <select>-HTML-tag angewendet, und spätere Definitionen ersetzen die früheren.

(:input datalist ... :)

Dies erlaubt ein Drop-Down-Menü einzurichten, das es dem Benutzer erlaubt, einen der präsentierten Werte (Vorschläge) auszuwählen oder einen neuen, anderen Wert einzutragen. Das Markup nimmt benannte oder positionierte Attribute an.

  (:input datalist ''id'' ''value'':)
  (:input datalist id=''id'' value=''value'':)

Ein dazugehörendes, existierendes (:input text:)-Feld muss ein Attribut list=ID_der_Datenliste haben, an das man die Vorschläge anbinden kann.

Das Datenlistenelement ist unsichtbar und kann an beliebiger Stelle der Seite eingetragen werden. Die Liste der Vorschläge erscheint, wenn der Benutzer mit dem Tippen in dem Textfeld beginnt und filtert die vorgeschlagen Werte aus, die die eingetippten Zeichen in dem Textfeld enthält.

Geben Sie einen Browsernamen ein: (:input text browsers list=dlist_id :)
(:input datalist dlist_id Firefox:)
(:input datalist dlist_id Chrome:)
(:input datalist dlist_id Safari:)
(:input datalist dlist_id Edge:)
(:input datalist dlist_id MSIE:)
(:input datalist dlist_id Opera:)
(:input datalist dlist_id Lynx:)

Das Datenlistenelement ist kürzlich zum HTML-Standard hinzugefügt worden, siehe https://caniuse.com/#feat=datalist wegen der Unterstützung aktueller Browser.

(:input datalist dl_1 First:)
(:input datalist dl_1 Second:)[==]
(:input datalist dl_2 First:)
(:input datalist dl_2 Second:)

(:input pmtoken:)

Dies fügt einen einmaligen Sitzungsidentifizierer als verstecktes Eingabefeld ein, um 'cross-site request forgeries' (etwa Website-übergreifende Anfragenfälschung, CSRF) zu verhindern. Das kann in eigene Formulare eingefügt werden, und der Aktion-Händler, der das Formular empfängt, kann prüfen, ob die Anfrage gültig ist, indem er pmtoken(1) aufruft.

Der "Name" des HTML-Eingabe-Elements, standardmäßig 'pmtoken', kann durch Setzen von zum Beispiel $FmtV['$TokenName'] = 'myCSRFtoken'; geändert werden. In Ihrem Formular brauchen Sie weiterhin (:input pmtoken:), das dann den neuen Namen für das HTML-Element benutzt.

Siehe auch

• Cookbook:Input Default -
• Cookbook:Form Validation -
• Cookbook:Form Extensions -
• Cookbook:Input Forms and JavaScript -
• PageLists#searchbox - Die (:searchbox:)-Direktive erzeugt ein Formular zur Suche im Wiki

Kompatible Rezepte:

• Cookbook:PmForm -
• Cookbook:Fox -
• Cookbook:Wiki Forms -
• Cookbook:ProcessForm -

für die Liste aller Seiten