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:

  1. Erstellen eines Forums-Objekts mit $obj = new Doku_Form()
  2. Hinzufügen der „Pflicht-Elemente“ (id, do, gegebenenfalls page bei Admin-Pages)
  3. Hinzufügen der benötigten Elemente (Textfelder, Auswahlboxen usw.)
  4. Hinzufügen eines „submit“-Buttons mit $obj->addElement(form_makeButton('submit','','Button-Beschriftung'))
  5. 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 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:

    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>');
    }

Eine Übersicht der globalen Sprach-Inhalte kann (z.B. für deutsch) hier eingesehen werden.

Beispiel des handle()

Die Abarbeitung der Aktionen/Eingaben des Formulars geschieht in der Funktion handle():

    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 ...
            }
        }
    }

Beispiele für die Verwendung des $INPUT-Objekts können hier eingesehen werden.

Quellennachweis