Form API (Form Builder)

Die API zur programmatischen Erstellung von Formularen in Drupal ist extrem leistungsstark. Mir ihr können komplexe Formulare in einer Array-Struktur definiert werden und sogar mit AJAX Status versehen werden (z.B. zeige ein Feld nur, wenn ein anderes Feld einen bestimmten Wert hat).

Die Form API dient nicht nur zur Erstellung der Formulare, sondern handelt auch die Validierung und Verarbeitung der Daten.

Einen Überblick über die Feldtypen bietet die Form API Reference.

Es ist oft sehr hilfreich zu wissen, wie Drupal intern Formulare nach dem Absenden verarbeitet, um sie a) richtig anzulegen und b) längeres Fehlersuchen so erspart wird.

• drupal_validate_form()
• _form_validate()
  • Prüft auf #maxlength
  • Prüft alle #required Felder
  • Bindet #validate und #element_validate ein
• Ruft die #validate Callbacks ($form['#validate'][]) auf
• Ruft die #element_validate Callbacks ($element['#element_validate'][]) auf

Das bedeutet, wenn ein Feld nur als Pflichtfeld (#required) gesetzt werden soll, wenn ein anderes Formularfeld einen bestimmten Wert enthält, so darf in der Formulardefinition das Feld nicht auf #required gesetzt werden. Denn, die required-Prüfung wird vor der eigenen Validierung ausgeführt und lässt die Validierung definitiv fehlschlagen.

In diesem Fall, muss das Feld in einer eigenen Validierungsfunktion entsprechend geprüft werden und entsprechende Fehlermeldungen zurückgegeben werden. In diesem Fall, wird aber leider auch nicht das Sternchen (*) als Indikator für das Pflichtfeld dem User angezeigt.

Über „#states“ ist es möglich, generiertes JavaScript zu einem Formularelement hinzuzufügen, um so seinen Status anhand von Bedingungen zu verändern (z.B. auszublenden oder einzublenden).

Dokumentiert ist #states hier:

• #states in Form API
• drupal_process_states()

Im Folgenden einige Codeschnippsel für Sonderfälle zum Nachschlagen.

Das Feld „test“ soll angezeigt werden, wenn das Feld „meine-bedingung“ den Wert „foo“ oder „bar“ hat.

$form['test'] = array(
  '#type' => 'textfield',
  '#title' => t('Test'),
  '#states' => array(
    'visible' => array(
      ':input[name="meine-bedingung"]' => array(
        array('value' => 'foo'),
        array('value' => 'bar'),
      ),
    ),
  ),
);