[2256 Aufrufe]

3.5 Der Abschnitt: Fields

In diesem Abschnitt stelle ich die Einstellungsmöglichkeiten der Felder dar. In einem der nächsten Texte werde ich dann Beispiele für die gebräuchlisten Felder zeigen. Da die verschiedenen Feldtypen unterschiedlich konfiguriert werden, werden die Einstellungsmöglichkeiten bezogen auf die einzelnen Felder dort dargestellt. Hier wird zunächst ein allgemeiner Überblick gegeben.

Beispielkonfiguration

<?php
$GLOBALS['TL_DCA']['tl_testtable'] = [
    // Config ...
    // List ...
    // Palettes ...
    // Subpalettes ...
    'fields' => [
        'id' => [
            'sql'       => 'int(10) unsigned NOT NULL auto_increment'
        ],
        'tstamp' => [
            'sql'       => "int(10) unsigned NOT NULL default '0'"
        ],
        'title' => [
            'exclude'   => true,
            'inputType' => 'text',
            'eval'      => ['mandatory' => true, 'maxlength' => 255, 'tl_class' => 'w50'],
            'sql'       => "varchar(255) NOT NULL default ''"
        ]
    ]
];

Zunächst braucht jedes Feld einen Namen. Er wird als Key im Array fields und in den Paletten verwendet (s. "Der Abschnitt: Palettes und Subpalettes"). In diesem Beispiel sind dies id, tstamp und title. Weiterhin hat jedes Feld Einstellungen wie den Eingabetyp, die SQL-Konfiguration und Angaben zur Anzeige und dem Verhalten im Backend. Nachfolgend gehe ich die einzelnen Einstellungen durch.

Einstellung: label

Variablentyp:	array
Beispiel:	&$GLOBALS['TL_LANG']['tl_testtable']['title']

Die Einstellung label enthält die Übersetzung der Bezeichner für das Feld. Das Spracharray wird unter demselben Namen, wie das DCA im Ordner Resources/contao/languages/de/ gespeichert. Es kann für jede beliebige Sprache ein Ordner in Resources/contao/languages/ angelegt werden. Für das Beispiel oben würde das Spracharray im Ordner der Erweiterung unter Resources/contao/languages/de/tl_testtable.php gespeichert.

Ab Contao 4.9 kann diese Einstellung entfallen, wenn der Eintrag im Spracharray denselben Namen trägt, wie das Feld.

Einstellung: default

Variablentyp:	mixed
Beispiel:	'Titel', 1, true

Mit default kann der Vorgabewert festgelegt werden. Dieser wird beim Anlegen eines neuen Datensatzes im Feld angezeigt. Wird der Datensatz bearbeitet und das Feld ist leer, findet der Vorgabewert keine Anwendung.

Einstellung: exclude

Variablentyp:	bool
Beispiel:	true

Ist der Wert von exclude auf true gesetzt, kann Backendnutzern in den Benutzereinstellungen der Zugriff auf dieses Feld entzogen oder gestattet werden.

Einstellung: toggle

Variablentyp:	bool
Beispiel:	true

Ist es auf true gesetzt, kann das Feld eine Toggle-Aktion triggern. Wir haben bereits im Text "Eine Togglefunktion für eine eigene Liste" eine eigene Toogle-Funktion erstellt. Diese Einstellunge haben wir dort nicht verwendet, leder habe ich auch keine weiteren Hinweise auf die Funktion gefunden.

Diese Einstellung gibt es seit Contao 4.13.

Einstellung: search

Variablentyp:	bool
Beispiel:	true

Mit search kann man das Feld als durchsuchbar kennzeichnen. Es wird dann in die Suchfunktion im Kopf der Liste aufgenommen. Es ist erforderlich, das die Liste entsprechend konfiguriert ist (s. Option: panelLayout in "Der Abschnitt: List").

Einstellung: sorting

Variablentyp:	bool
Beispiel:	true

Will man den Nutzer die Liste nach einem bestimmten Feld sortieren lassen, setzt man bei dem entsprechenden Feld sorting auf true. Das Feld wird dann in das Auswahlfeld für die Sortierung im Kopf der Liste aufgenommen. Auch hier muss die Liste entsprechend konfiguriert werden (s. Option: panelLayout in "Der Abschnitt: List") und es funktioniert nicht in jedem Sortiermodus (s. Option: mode / Option: flag in "Der Abschnitt: List").

Einstellung: filter

Variablentyp:	bool
Beispiel:	true

Sollen nur Datensätze in der Liste angezeigt werden, die in einem bestimmten Feld einen gewissen Wert haben, setzt man filter bei dem Feld auf true. Im Kopf der Liste wird dann ein Auswahlfeld für dieses Feld mit allen Werte erzeugt, sodass der Nutzer die Liste dynamisch filtern kann. Auch hier muss die Liste entsprechend konfiguriert werden (s. Option: panelLayout in "Der Abschnitt: List").

Einstellung: flag

Variablentyp:	integer
Beispiel:	\Contao\DataContainer::SORT_INITIAL_LETTER_ASC

Mit dem flag kann man die Art der Sortierung angeben. Es gibt folgende Werte:

Wert	Konstante	Bedeutung
1	\Contao\DataContainer::SORT_INITIAL_LETTER_ASC	Datensätze werden nach dem ersten Buchstaben aufsteigend sortiert.
2	\Contao\DataContainer::SORT_INITIAL_LETTER_DESC	Datensätze werden nach dem ersten Buchstaben absteigend sortiert.
3	\Contao\DataContainer::SORT_INITIAL_LETTERS_ASC	Datensätze werden nach den ersten zwei Buchstaben aufsteigend sortiert.
4	\Contao\DataContainer::SORT_INITIAL_LETTERS_DESC	Datensätze werden nach den ersten zwei Buchstaben absteigend sortiert.
5	\Contao\DataContainer::SORT_DAY_ASC	Datensätze werden nach Tag aufsteigend sortiert. (Feld muss ein Datum enthalten.)
6	\Contao\DataContainer::SORT_DAY_DESC	Datensätze werden nach Tag absteigend sortiert. (Feld muss ein Datum enthalten.)
7	\Contao\DataContainer::SORT_MONTH_ASC	Datensätze werden nach Monat aufsteigend sortiert. (Feld muss ein Datum enthalten.)
8	\Contao\DataContainer::SORT_MONTH_DESC	Datensätze werden nach Monat absteigend sortiert. (Feld muss ein Datum enthalten.)
9	\Contao\DataContainer::SORT_YEAR_ASC	Datensätze werden nach Jahr aufsteigend sortiert. (Feld muss ein Datum enthalten.)
10	\Contao\DataContainer::SORT_YEAR_DESC	Datensätze werden nach Jahr absteigend sortiert. (Feld muss ein Datum enthalten.)
11	\Contao\DataContainer::SORT_ASC	Datensätze werden aufsteigend.
12	\Contao\DataContainer::SORT_DESC	Datensätze werden absteigend.

Einstellung: length

Variablentyp:	integer
Beispiel:	0, 1

Mit length kann die Anzahl der Zeichen, die für das Bilden der Gruppen bei der Sortierung herangezogen werden, angegeben werden. Dies funktioniert nur, wenn flag auf 3 (\Contao\DataContainer::SORT_INITIAL_LETTERS_ASC) oder 4 (\Contao\DataContainer::SORT_INITIAL_LETTERS_DESC) gesetzt ist.

Einstellung: inputType

Variablentyp:	string
Beispiel:	text, textarea, select, radio, pageTree

Eine der wichtigsten Einstellungsmöglichkeiten, ist die Art des Eingabefelds. Es wird der Eigenschaft inputType zugewiesen. Es gibt folgende Werte:

Wert	Name	Beispiel
checkbox	Checkbox
checkboxWizard	Checkbox Wizard
chmod	CHMOD table
fileTree	File tree
imageSize	Ein Auswahlfeld und zwei Textfelder, um die Größe von Bildern einzugeben.
inputUnit	Ein Textfeld und ein Auswahlfeld.
keyValueWizard	Ein Wirazd für die Eingabe von Schlüsseln und Werten, mit zwei Textfeldern pro Eintrag .
listWizard	Ein Wizard mit einem Eingabefeld pro Reihe, für die Eingabe eines Werts.
metaWizard	Einfabe der Metadaten im Dateimanager.
moduleWizard	Auswahl von Frontendmodulen, wird im Seitenlayout verwendet.
optionWizard	Auswahlfeld um Optionen festzulegen, wird z.B. im Formulargenerator beim Feldtyp "Select-Menü" verwendet.
pageTree	Auswahl einer Weiterleitungsseite.
password	Ein Textfeld für die versteckte Eingabe, mit der Möglichkeit die Eingabe sichtbar zu machen.
picker	Grundlegendes Auswahl-Widget, wird z. B. beim Einbinden eines Artikels in ein Inhaltselement verwendet.
radio	Radiobutton
radioTable	Tabelle mit Radiobuttons und Bildern, wird z. B. im Seitenlayout für die Auswahl der Zeielen und Spalten verwendet.
sectionWizard	Auswahl der benutzerdefinierten Bereiche im Seitenlayout.
select	Auswahlfeld
serpPreview	Suchmaschienenvorschau
tableWizard	Ein Wizard für die tabellarische Eingabe von Werten.
text	Textfeld
textStore	Ein Feld zur maskierten Eingabe von Werte, aber ohne die Möglichkeit, die Eingabe sichtbar zu machen.
textarea	Textarea (normal, mit TinyMCE, oder Codeeditor)
timePeriod	Textfeld mit einem Auswahlfeld
trbl	Vier Textfelder und ein Auswahlfeld für die Einheit, um den Abstand einzugeben.

Einstellung: options

Variablentyp:	array
Beispiel:	['h1', 'h2', 'h3]

Einige Feldtypen, wie select, radio und timePeriod benötigen Optionen, die man auswählen kann. Diese können der Einstellung options zugewiesen werden. In der Regel werden hier die Schlüssel hinterlegt und die Übersetzungen in das Spracharray eingetragen. Das Spracharray kann der Einstellung reference zugewisen werden (s. u.).

Einstellung: options_callback

Variablentyp:	array
Möglicher Werte:	[class, method]
Beispiel:	[\Ctocb\Example\Classes\Contao\Operations\TlTesttable::class, 'myMethod']

Manchmal stehen die Optionen erst zur Laufzeit zur Verfügung und müssen z. B. aus der Datenbank geladen werden. In diesem Fall kann man einen options_callback verwenden. Man weisst der Einstellung die Klasse und die Methode zu, die aufgerufen werden soll. Die Methode muss dann ein Array mit den Optionen zurückgeben. (Auf Callbacks gehen wir im nächsten Kapitel noch gesondert ein.)

Einstellung: foreignKey

Variablentyp:	string
Beispiel:	tl_article.title, tl_user.name, tl_member.CONCAT(firstname,' ',lastname)

Soll einfach ein Datensatz aus einer andern Tabelle ausgewählt werden, kann die Einstellung foreignKey verwendet werden um die Optionen zu erzeugen. Es wird ein String zugewiesen, der aus dem Namen der Tabellen und dem Namen des Felds besteht. Der Inhalt des angegebenen Felds wird als Bezeichnung verwendet, als Schlüssel dient immer die id. Man kann auch mehrere Felder mit CONCAT() verbinden (z. B. tl_member.CONCAT(firstname,' ',lastname)).

Einstellung: reference

Variablentyp:	array
Beispiel:	&$GLOBALS['TL_LANG']['COLS']

Gibt man die Optionen direkt an und weist die Schlüssel zu, kann der Einstellung reference ein Spracharray zugewiesen werden, welches die Übersetzung enthält. Das Array muss in der entsprechenden Sprachdatei erstellt werden (z. B. Resources/contao/languages/de/tl_testtable.php im Ordner der Erweiterung).

Einstellung: explanation

Variablentyp:	string
Beispiel:	myExplanation

Der Einstellung explanation wird ein Schlüssel für das Spracharray $GLOBALS['TL_LANG']['XPL'] zugewiesen. Der entsprechende Eintrag wird dann vom HelpWizard angezeigt. (Details befinden sich im Handbuch). Auf den HelpWizard gehen wir in einem späteren Text noch ein.

Einstellung: input_field_callback

Variablentyp:	array
Möglicher Werte:	[class, method]
Beispiel:	[\Ctocb\Example\Classes\Contao\Operations\TlTesttable::class, 'myMethod']

Mit dem input_field_callback kann man individuelle Eingabefelder für das Backend erstellen. Es wird die Klasse und die Methode übergeben. Die Methode muss dann das HTML des Eingabefelds zurückgeben. (Auf Callbacks gehen wir im nächsten Kapitel noch gesondert ein.)

Einstellung: eval

Variablentyp:	array
Beispiel:	['mandatory'=>ture, 'maxlength'=>255, 'tl_class'=>'w50']

Die Einstellung eval (Evaluation/Auswertung) regelt die Anzeige und den Umgang mit dem Feld. Hier kann die maximal Zeichenzahl festgelegt werden, oder ob ein Feld ein Pflichtfelt ist und vieles mehr. Auf die Details dieser Einstellungen gehen wir im übernächsten Text ein.

Einstellung: wizard

Variablentyp:	array
Möglicher Werte:	[class, method]
Beispiel:	[\Ctocb\Example\Classes\Contao\Operations\TlTesttable::class, 'myMethod']

Dieser Callback erstellt einen Hilfebutton. (Auf Callbacks gehen wir im nächsten Kapitel noch gesondert ein.)

Einstellung: sql

Variablentyp:	string|array
Beispiel:	VARCHAR(32) NOT NULL DEFAULT '', ['type' => 'string', 'length' => 32, 'default' => '']

In die Einstellung sql wird die Definiotion für das Datenbankfeld eingetragen. Details zur Konfiguration stehen im Handbuch und werden bei den Beispeilen im nächsten Text noch veranschaulicht.

Einstellung: relation

Variablentyp:	array
Beispiel:	['type'=>'hasOne', 'table'=>'tl_member]

In relation wird die Beziehung zur Elterntabelle angegeben. Auch diese Details befinden sich im Handbuch. Auch zu diesem Thema wird später noch ein eigener Text erscheinen.

Einstellung: load_callback

Variablentyp:	array
Möglicher Werte:	[class, method]
Beispiel:	[\Ctocb\Example\Classes\Contao\Operations\TlTesttable::class, 'myMethod']

Der load_callback wird beim Laden des Felds aufgerufen. Man kann mit ihm z. B. einen Standardwert setzen, oder Werte aus der Datenbank konvertieren. (Auf Callbacks gehen wir im nächsten Kapitel noch gesondert ein.)

Einstellung: save_callback

Variablentyp:	array
Möglicher Werte:	[class, method]
Beispiel:	[\Ctocb\Example\Classes\Contao\Operations\TlTesttable::class, 'myMethod']

Der save_callback wird beim Sepichern des Felds aufgerufen. Man kann mit ihm z. B. Werte für die Datenbank konvertieren. (Auf Callbacks gehen wir im nächsten Kapitel noch gesondert ein.)

Einstellung: xlabel

Variablentyp:	array
Möglicher Werte:	[class, method]
Beispiel:	[\Ctocb\Example\Classes\Contao\Operations\TlTesttable::class, 'myMethod']

Der xlabel-Callback wird beim Rendern des Widgets aufgreufen und erlaubt es, HTML nach dem Label einzufügen.