====== Formulare erstellen ======

In/seit "Weatherwax" gibt es eine Classe um Formulare zu erstellen. Diese ist deswegen sehr nützlich, da hier in den Formularen bereits das "sectok" mit gesetzt wird um eine gewisse Sicherheit zu erhalten.

Des Weiteren kann auch bei der Abarbeitung der Eingaben mit dem globalen Objekt ''$INPUT'' anstatt der üblichen globalen Variablen (''$_GET'', ''$_POST'' und ''$_REQUEST'') eine Datenprüfung zur Sicherheit mit verwendet werden.

Leider hab ich bisher keine wirkliche Dokumentation darüber gefunden, weswegen ich hier für mich selbst versuche zumindest einen gewissen Grundstock zu dokumentieren.

===== Voraussetzungen =====

Um an die Sprach-Variablen zu gelangen sollte ''%%$this->setupLocale();%%'' zumindest in der entsprechenden Funktion ausgeführt sein. Alternativ kann auch mit ''global $lang;'' gearbeitet werden, wodurch ein Array mit den lokalisierten Daten zur Verfügung steht.

Des weiteren gibt es ein paar Grund-Elemente, die in einem Formular (zumindest versteckt) eingebunden seien sollten. Diese sind:
^ Element  ^ Wert                     ^ Bemerkung                                                         ^
| id       | <name current wikipage>  |                                                                   |
| do       | admin                    | bei einem Admin Plugin und dessen Admin-Page                      |
| :::      | show                     | bei einem Formular, dass in einer Wiki-Seite zur Anwendung kommt  |
| page     | <plugin name>            | wird nur in Admin-Pages benötigt                                  |

===== Vorgehen =====

Um ein Formular zu erstellen ist eigentlich nicht viel nötig.

Der grundlegende Ablauf besteht aus folgenden Schritten:
  - Erstellen eines Forums-Objekts mit ''$obj = new Doku_Form()''
  - Hinzufügen der "Pflicht-Elemente" (''id'', ''do'', gegebenenfalls ''page'' bei Admin-Pages)
  - Hinzufügen der benötigten Elemente (Textfelder, Auswahlboxen usw.)
  - Hinzufügen eines "submit"-Buttons mit ''%%$obj->addElement(form_makeButton('submit','','Button-Beschriftung'))%%''
  - Ausgabe/Rendern des Formulars

Es empfiehlt sich ein verstecktes Element für die Kennzeichnung der eigentlichen Aktion mit zu integrieren.

Ein einfaches Beispiel ist in [[#beispiel_1|Beispiel 1]] zu sehen.

==== Initialisieren des Formula-Objekts ====

TODO

==== die Formular-Elemente ====

TODO

=== Element-Funktionen ===

== startFieldset() ==
== endFieldset() ==
== addHidden() ==
== addElement() ==
== insertElement() ==
== replaceElement() ==
== findElementByType() ==
== findElementById() ==
== findElementByAttribute() ==
== getElementAt() ==
== addRadioSet() ==

=== die einzelnen Elemente ===

== form_makeTag() ==
== form_makeOpenTag() ==
== form_makeCloseTag() ==
== form_makeWikiText() ==
== form_makeButton() ==
== form_makeField() ==
== form_makeFieldRight() ==
== form_makeTextField() ==
== form_makePasswordField() ==
== form_makeFileField() ==
== form_makeCheckboxField() ==
== form_makeRadioField() ==
== form_makeMenuField() ==
== form_makeListboxField() ==
== form_tag() ==
== form_opentag() ==
== form_closetag() ==
== form_openfieldset() ==
== form_closefieldset() ==
== form_hidden() ==
== form_wikitext() ==
== form_button() ==
== form_field() ==
== form_fieldright() ==
== form_textfield() ==
== form_passwordfield() ==
== form_filefield() ==
== form_checkboxfield() ==
== form_radiofield() ==
== form_menufield() ==
== form_listboxfield() ==

==== Ausgabe/Rendern des Formulars ====

TODO

=== getForm() ===
=== printForm() ===
=== Event-Trigger mit html_form() ===

==== Abarbeiten/Auswerten der Eingabe ====

TODO

===== Beispiele =====
Hier nun ein paar Beispiele für ein Formular in einem Admin-Plugin.

==== Beispiel 1 ====

Hier wird mit der Classe zur Lokalisierung gearbeitet:
<code php>
    function html() {
        global $lang;                               // wird benötigt, wenn globale Sprach-Inhalte benötigt werden.
        $this->setupLocale();

        ptln('<div id="'.$this->getPluginName().'_manager" class="formular">');
        $form = new Doku_Form('formID',wl($ID));
        $form->addHidden('id',$ID);
        $form->addHidden('do','admin');
        $form->addHidden('page',$this->getPluginName());
        $form->addHidden('act','save');             // Die von der Funktion "handle()" abzuarbeitende Aktion.
        
//        $form->addElement(form_makeButton('submit','',$this->getLang('own_btn_submit')));
        $form->addElement(form_makeButton('submit','',$lang['btn_save']));
        $form->printForm();
//        html_form('formsave', $form);            // Formular-Ausgabe mit Trigger auf HTML_{$name}FORM_OUTPUT
        ptln('</div>');
    }
</code>
<wrap lo>Eine Übersicht der globalen Sprach-Inhalte kann (z.B. für deutsch) [[http://xref.dokuwiki.org/reference/dokuwiki/inc/lang/de/lang.php.source.html|hier]] eingesehen werden.</wrap>

==== Beispiel des handle() ====
Die Abarbeitung der Aktionen/Eingaben des Formulars geschieht in der Funktion ''handle()'':
<code php>
    function handle() {
        global $INPUT;
        if ($INPUT->str('act') && checkSecurityToken()) {    // Prüfen des Sicherheits-Tokens (sectoc)
            if ($INPUT->str('act') == "save") {              // Die erste Aktion aus dem ersten Beispiel
              // ... tue was auch immer bei dieser Aktion ...
            }
        }
    }
</code>
<wrap lo>Beispiele für die Verwendung des $INPUT-Objekts können [[doku>devel:request_vars|hier]] eingesehen werden.</wrap>

===== Quellennachweis =====

  * [[http://xref.dokuwiki.org/reference/dokuwiki/inc/form.php.html|PHP Cross Reference of DokuWiki -> inc/form.php]]
  * [[doku>devel:security|Security Guidelines for Plugin Authors]]
  * [[doku>devel:request_vars|Accessing Request Variables]]
  * [[doku>devel:admin_plugins|Admin Plugins]]

{{keywords>formular plugins entwicklung development}}
{{tag>dokuwiki programmierung}}
<WRAP rightalign><wrap lo>//Dieser Artikel ist publiziert unter: {{license>by-nc-sa,small}}//</wrap></WRAP>