Joomla! Documentation™

Einführung

Formularfelder sind Felder in einem HTML-Formular (<form>). Joomla! 2.5 und neuer enthält die JForm-Klasse, um bequem und flexibel Formulare mit vielen Formularfeldern zu erstellen. Jeder Formularfeldtyp ist eine Unterklasse von JFormField.

JFormFields ist nicht nur ein flexibles Werkzeug zur Erstellung von Seiten. Es wird auch verwendet, um Administratoren die Konfiguration von Joomla! oder seiner Erweiterungen zu ermöglichen, ohne den zugrunde liegenden Code zu ändern. In Joomla! 1.5 wurde dies durch die jetzt veralteten Klassen JParameter und JElement gehandhabt.

Um Formularfelder für den Konfigurationsbereich einer Erweiterung zu definieren, müssen sie in ein benanntes Fieldset, wie z. B. <fieldset name="basic"> innerhalb des Abschnitts <fields name="params"> des <config>-Elements in der XML-Manifestdatei eingebettet werden.

Validierung von Formulardaten

Joomla hat Möglichkeiten der client- und server-seitigen Formularüberprüfung.
Die serverseitige Überprüfung ist das Mindeste, da alles vorher auf der Benutzerseite überschrieben werden kann. Allerdings ist die client-seitige Überprüfung benutzerfreundlicher, daher ist es keine schlechte Idee, beide zu verwenden.

Clientseitige Überprüfung

... wird mit JavaScript umgesetzt, während der Benutzer die Formularfelder ausfüllt.
Es nutzt die HTML-Klassen required und validate-[xxx] (mit [xxx] als selbst erstellte oder Joomla-Regel, z. B. validate-numeric).

Weitere Informationen sind hier zu finden: Clientseitige Formularüberprüfung

Serverseitige Überprüfung

... wird durchgeführt, nachdem das Formular abgeschickt wurde. Wenn das Formular ungültige Daten enthält, wird der Benutzer normalerweise mit entsprechenden Nachrichten zum Formular zurückgeleitet.
Sie nutzt die HTML-Attribute required ("true" oder "required") und validate (mit einem Wert als selbst erstellte oder Joomla-Regel, z. B. validate="email").

Weitere Informationen sind hier zu finden: Serverseitige Formularüberprüfung

Standard-Formularfeldtypen

In Joomla! sind zahlreiche Formular-Elemente integriert. Die folgende Tabelle listet die standardmäßig enthaltenen Eingabe-Felder und die Version auf, ab der sie integriert sind. Wenn du die Referenz der Formular-Elemente ausdrucken möchtest, nutze die Einseitige Referenz.

Bitte beachte, dass viele dieser Felder als Parameter-Typen in Joomla! 1.5 verfügbar sind. Eine Liste der Parameter-Typen findest du unter J1.5:Standard Parameter-Typen. Einen Vergleich zwischen Formular-Feldern und Parameter-Typen findest du unter Standard Formular-Elemente und Parameter-Typen.

Typ	Beschreibung	Verfügbar ab
verfügbare Medien	bietet dem Benutzer, mit entsprechenden Rechten, einen modalen Zugriff auf den Medien-Manager zum Einfügen von Bildern per Upload und ein Textfeld zum Hinzufügen eines Alternativtextes.	und neuer
Zugriffsstufen	Dropdown-Liste zur Anzeige der Zugriffsstufen	und neuer
Cachehandler	Liste mit den verfügbaren Cache-Optionen	und neuer
Kalender	Stellt ein Textfeld für die Eingabe eines Datums zur Verfügung. Neben dem Textfeld ist ein Icon zum Öffnen eines Popup-Kalenders. Dieser kann zur Auswahl des Datums genutzt werden.	und neuer
Captcha	Verwendung des Captcha-Plugins.	und neuer
Kategorie	Dropdown-Liste für die Kategorien einer Erweiterung.	und neuer
Checkbox	Ein einfaches Kontrollkästchen, das aktiviert oder deaktiviert werden kann.	und neuer
Checkboxen	Unendliche Anzahl von Kontrollkästchen mit Mehrfach-Auswahl.	und neuer
Chrome-Style	Liste mit Chrome-Style-Vorlagen, die nach Templates gruppiert sind.	und neuer
Farbe	Stellt eine Farbauswahl bereit, wenn in das Eingabefeld geklickt wird.	und neuer
Inhaltssprache	Eine Liste der Inhaltssprachen.	und neuer
Inhaltstyp	Eine Liste mit den Inhalts-Typen.	und neuer
Kombinationsfeld	Ein Kombinationsfeld (Combo-Box)	und neuer
Komponentenlayout	Bietet eine gruppierte Liste von Kern- und alternativen Template-Layouts für eine Komponente.	und neuer
Inhaltssprache	Bietet zur Verwendung eine Liste der installierten Inhaltssprachen, in Verbindung mit dem Sprachumschalter-Plugin.	und neuer
Datenbankverbindung	Bietet eine List der verfügbaren Datenbankverbindungen, welche optional auf eine bestimmte Liste beschränkt werden können.	und neuer
Editor	Bietet ein Editorfeld.	und neuer
Editoren	Bietet ein Dropdown-Liste der verfügbaren WYSIWYG-Editoren. Seit werden stattdessen Plugin-Formularfeldtypen genutzt.
E-Mail	Bietet ein E-Mail-Feld.	und neuer
Datei	Bietet ein Eingabefeld für das Hochladen von Dateien.	und neuer
Dateienliste	Bietet eine Dropdown-Liste von Dateien aus einem bestimmten Verzeichnis.	und neuer
Ordnerliste	Bietet eine Dropdown-Liste von Ordnern eines bestimmten Verzeichnisses.	und neuer
Gruppierte Liste	Bietet eine Dropdown-Liste von organisierten Elementen in Gruppen.	und neuer
Header-Tag	Bietet eine Dropdown-Liste von Überschriften-Tags. (h1-h6).	und neuer
Hilfsseite	Bietet eine Dropdown-Liste von Hilfsseiten für deine Joomla-Installation.	und neuer
Versteckt	Bietet ein verstecktes Feld zum Speichern eines Formularfeldes, dessen Wert nicht direkt durch einen Benutzer im Administratorenbereich verändert werden kann. (Eine Änderung könnte im Code oder durch das Verändern der Datei params.ini erfolgen)	und neuer
Bilderliste	Bietet eine Dropdown-Liste von Bilddateien eines bestimmten Verzeichnisses.	und neuer
Natürliche Zahl	Bietet eine Dropdown-Liste von natürlichen Zahlen zwischen einem Minimum und einem Maximum.	und neuer
Sprache	Bietet eine Dropdown-Liste von installierten Sprachen für das Frontend oder Backend.	und neuer
Liste	Bietet eine Dropdown-Liste von benutzerdefinierten Einträgen.	und neuer
Medien	Bietet modalen Zugriff auf den Medienmanager zum Einfügen von Bildern, mit Upload-Möglichkeit für Benutzer mit entsprechenden Berechtigungen.	und neuer
Menü	Bietet eine Dropdown-Liste von verfügbaren Menüs deiner Joomla-Seite.	und neuer
Menüelement	Bietet eine Dropdown-Liste von verfügbaren Menüeinträgen deiner Joomla-Seite.	und neuer
Fortschrittsanzeige	Bietet eine Fortschrittsanzeige, um Werte in einem Bereich anzuzeigen.	und neuer
Modul-Layout	Bietet eine Liste der alternativen Layouts für ein Modul, gruppiert nach Core und Template.	und neuer
Modul-Reihenfolge	Bietet eine Dropdown-Liste, um die Reihenfolge des Moduls an einer bestimmten Position festzulegen	und neuer
Modul-Position	Bietet eine Texteingabe, um die Position eines Moduls festzulegen.	und neuer
Modul-Tag	Bietet eine Liste von HTML5-Elementen (in die ein Modul eingebettet wird)	und neuer
Notiz	Bietet ein einzeiliges Textfeld	und neuer
Zahl	Bietet eine einzeilige Textbox um eine Ziffer mit Auf-und-Ab-Reglern festzulegen.	und neuer
Passwort	Bietet eine Textbox zum Eintragen eines Passwortes. Die Passwortzeichen werden bei der Eingabe unkenntlich gemacht.	und neuer
Plugins	Bietet eine Liste von Plugins aus einem bestimmten Ordner.	und neuer
Vordefinierte Liste	Formularfeld, um eine Liste von vordefinierten Werten zu laden.	und neuer
Radiofeld	Radio-Buttons zur Auswahl von verschiedenen Optionen.	und neuer
Bereich	Bietet eine horizontalen Scrollleiste, um einen Wert aus dem Bereich anzugeben.	und neuer
Wiederholbares Feld	Erstellt Formularfelder, die beliebig wiederholt werden können.	und neuer
Regeln	Bietet eine Matrix von Gruppen zum Verwalten der Zugriffssteuerung durch Aktionsoptionen. Die Anzeige hängt vom Kontext ab.	und neuer
Session-Handler	Bietet eine Dropdown-Liste der Session-Handler-Optionen	und neuer
Trenner	Ein visuelles Trennzeichen zwischen Formularfeldern. Es dient als visuelle Hilfe. Deshalb wird kein Wert gespeichert.	und neuer
sql	Bietet eine Dropdown-Liste von erhaltenen Einträgen durch die Ausführung einer Abfrage in der Joomla-Datenbank. Die erste Spalte, welche durch die Abfrage zurückgeben wurde, stellt dabei die Werte der Dropdown-Liste dar.	und neuer
Unterformular	Bietet eine Möglichkeit, XML-Formulare ineinander zu verschachteln oder vorhandene Formulare in einem aktuellen Formular wiederzuverwenden.	und neuer
Tag	Bietet einen Einstiegspunkt für Tags (entweder AJAX oder verschachtelt).	und neuer
Telefon	Ein Eingabefeld für eine Telefonnummer	und neuer
Template-Stil	Dropdown-Liste mit Template-Stilen.	und neuer
Text	Ein Textfeld zur Eingabe von Daten.	und neuer
Textfeld	Textbereich für die Eingabe von mehrzeiligen Text.	und neuer
Zeitzone	Dropdown-Liste mit Zeitzonen	und neuer
URL	Eingabefeld für URLs	und neuer
Benutzer	Feld zum Auswählen eines Benutzers von einer modalen Liste. Zeigt den Benutzernamen und die gespeicherte Benutzer-ID an.	und neuer
Benutzer - aktiv	Feld, welches eine Liste der verfügbaren aktiven Benutzerstatus anzeigt.	und neuer
Benutzergruppe	Bietet eine Dropdown-Liste von Benutzergruppen. Seit benutze stattdessen die usergrouplist.	und neuer
Liste der Benutzergruppen	Feld, um eine Dropdown-Liste zu laden, welche die verfügbaren Benutzergruppen enthält. Ersetzt usergroup aus den Formularfeldtypen.	und neuer
Benutzerstatus	Feld, um eine Liste der verfügbaren Benutzerstatus zu laden.	und neuer

Eigene Formularfeldtypen

Eine Erweiterung kann eigene Formularfeldtypen definieren, die dann in eigenen oder von einer anderen Erweiterung erstellten Formularen verwendet werden können. Siehe Erstellen eines eigenen Formularfeldtyps für eine Anleitung.

Modale Formularfeldtypen

Wenn ein Feld so viele Werte hat, dass sie nicht in ein Auswahlfeld passen, kann ein modales Formularfeld erstellt werden. Damit kann der Benutzer einen Eintrag aus einem modalen Fenster mit einer Tabelle, Filteroptionen usw. auswählen – ähnlich den Administrator-Tabellen, z. B. „Beiträge“. Siehe auch Erstellen eines modalen Formfelds.

Oft verwendete Attribute

Labelclass

Durch das Hinzufügen des Attributs labelclass wird eine CSS-Klasse für die Beschriftung von Formularfeldern hinzugefügt. Quelle: http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemEdit&tracker_item_id=28450

Showon

Das Hinzufügen des Attributs showon ermöglicht es, das Feld auf der Grundlage des/der Werte(s) eines anderen Feldes auszublenden.

Als Beispiel die Syntax, um das Feld bar nur dann anzuzeigen, wenn sowohl foo als auch baz auf „1“ gesetzt sind:

<field
    name="foo"
    type="list"
    >
    <option value="1">JYES</option>
    <option value="0">JNO</option>
</field>
<field
    name="bar"
    type="text"
    showon="foo:1"
/>

Um mehrere Werte abzugleichen, kann eine durch Komma getrennte Liste von Werten genutzt werden, wie z. B. showon="foo:1,2".

Um mehrere Felder zu kombinieren, kann [AND] verwendet werden, wie z. B. showon="foo:1[AND]bar:1".

Hier die Syntax, um das Feld bar nur dann anzuzeigen, wenn foo und baz auf „1“ gesetzt sind:

<field
    name="foo"
    type="list"
    >
    <option value="1">JYES</option>
    <option value="0">JNO</option>
</field>
<field
    name="baz"
    type="list"
    >
    <option value="1">JYES</option>
    <option value="0">JNO</option>
</field>
<field
    name="bar"
    type="text"
    showon="foo:1[AND]baz:1"
/>

Um eine Auswahl zwischen mehreren Feldern zu treffen, kann [OR] verwendet werden, wie z. B. showon="foo:1[OR]bar:1".

Hier die Syntax, um das Feld bar nur dann anzuzeigen, wenn entweder "foo" auf „1“ oder „baz“ auf „1“ gesetzt sind:

<field
    name="foo"
    type="list"
    >
    <option value="1">JYES</option>
    <option value="0">JNO</option>
</field>
<field
    name="baz"
    type="list"
    >
    <option value="1">JYES</option>
    <option value="0">JNO</option>
</field>
<field
    name="bar"
    type="text"
    showon="foo:1[OR]baz:1"
/>

Es können auch Werte, die nicht übereinstimmen, abgefragt werden, wie z. B. hier: showon="field1!:1".

Hier die Syntax, um das Feld bar nur dann anzuzeigen, wenn foo nicht gleich „1“ ist:

<field
    name="foo"
    type="list"
    >
    <option value="1">JYES</option>
    <option value="0">JNO</option>
</field>
<field
    name="baz"
    type="list"
    showon="foo!:1"
    >
    <option value="1">JYES</option>
    <option value="0">JNO</option>
</field>

Um ein Feld anzuzeigen, wenn ein anderes Feld (z.B. foo) ausgewählt wurde (sofern dieses andere Feld nicht leer ist), verwendet man showon="foo!:" (ohne Angabe eines Wertes).

Dies wurde mit einem PullRequest eingeführt und ist ab Joomla 3.2.4 verfügbar.

Fehlerbehebung: Attribute funktionieren nicht

Wenn du eine ältere Version unserer Entwicklerdokumentation gelesen oder den Code für die Formularanzeige von einer vorhandenen Erweiterung übernommen hast, funktionieren Attribute wie showon vielleicht nicht. Damit bestimmte Attribute funktionieren, müssen die Felder mit der Methode renderField() angezeigt werden. Zum Beispiel:

<div class="row-fluid">
    <div class="span6">
        <?php
            foreach($this->form->getFieldset() as $field) {
                echo $field->renderField();
            }
        ?>
    </div>
</div>