Lernseite · Formulare, Datensätze und CSV
Formulare bauen, Datensätze pflegen, CSV verstehen
Auf dieser Seite begleitest du Lena, Redakteurin der Stadtbibliothek Weidenau. Sie baut ein Kontaktformular, pflegt Datensätze wie Website-Benutzer und Veranstaltungen und tauscht Listen als CSV-Datei mit anderen Programmen aus. Tom ist der Administrator. Danach kennst du den Formulareditor, das Modul Records mit Zwischenablage und Download und weißt, warum aus einem „ü“ manchmal zwei seltsame Zeichen werden.
Formulare in TYPO3: das Modul Forms
Die Bibliothek braucht Formulare für Fragen, für den Lesekreis und für einen Fotowettbewerb. In TYPO3 entstehen solche Formulare mit dem Form Framework. Es ist eine System-Extension des Core und seit TYPO3 8 dabei. Der Administrator muss sie aktivieren und den Redakteuren das Modul freigeben. Tom hat das erledigt, also sieht Lena im Bereich Content das Modul Forms. Es hieß früher Web, Forms und zeigt in der Übersicht alle Formulare, den sogenannten Form Manager.
Das Form Framework kann eine Menge:
- Du baust Formulare mit der Maus, siehst eine Vorschau und nutzt ein Formular auf vielen Seiten.
- Es gibt Pflichtfelder, Prüfungen der Eingaben, mehrstufige Formulare und einen automatischen Spamschutz.
- Nach dem Absenden laufen Aktionen, die Finisher, zum Beispiel eine E-Mail an die Redaktion.
Es hat aber auch Grenzen. Eingeschränkt sind die Formatierung von Feldbeschriftungen, die Mehrsprachigkeit und die Textgestaltung von E-Mails. Seit TYPO3 14.2 können die Mail-Finisher zwar eine eigene, formatierte Nachricht enthalten, und einige Felder bekommen einen Rich-Text-Editor. Für sehr gestaltete Mails oder viele Sprachen braucht es aber weiterhin Hilfe aus der Entwicklung.
Ein neues Formular anlegen
Im Modul Forms klickt Lena auf Create new form. Ein Assistent führt sie in wenigen Schritten durch:
- Sie wählt den Start: ein leeres Formular, im Assistenten „Blank form“, oder ein vordefiniertes Formular, „Predefined form“. TYPO3 bringt als Vorlage ein einfaches Kontaktformular mit, das „Simple contact form“.
- Sie wählt, wo das Formular gespeichert wird. Seit TYPO3 14.2 gibt es dafür die Datenbank, und sie ist der empfohlene Speicher. Das Speichern als YAML-Datei in einem Dateispeicher ist veraltet. Ist nur ein Speicher erlaubt, überspringt der Assistent diesen Schritt.
- Sie gibt einen Namen ein, den sie später wiedererkennt, etwa „Kontakt Bibliothek“. Er erscheint nur im Backend. Beim vordefinierten Formular wählt sie hier auch die Vorlage.
- Sie prüft ihre Angaben und legt das Formular an. Danach öffnet sich der Formulareditor.
Im Editor fügt Lena über Create new element Felder hinzu. Per Drag and Drop sortiert sie vorhandene Felder um. Rechts im Inspektor stellt sie das gewählte Feld ein. Ganz oben in der Baumansicht steht der Formularname. Ein Klick darauf öffnet die allgemeinen Einstellungen des Formulars mit den Finishern. Über das Vorschau-Symbol sieht sie eine einfache Vorschau.
In der Vorschau fällt ihr eine Überschrift „Step“ auf. Ein Formular besteht aus mindestens einem Schritt, und dieser Titel wird mit ausgegeben. Bei einem einstufigen Formular passt er nicht. Die Überschrift soll ohnehin von der Seite kommen. Lena klickt deshalb links im Baum auf „Step“ und löscht das Wort.
Formularelemente und ihre Einstellungen
Für jede Art von Eingabe gibt es ein Element. Die wichtigsten:
- Text ist ein einzeiliges Feld, etwa für den Namen.
- Textarea ist ein mehrzeiliges Feld für längere Eingaben wie eine Nachricht.
- Email address, Telephone number und URL sind Textfelder für genau diese Angaben.
- Number und Date nehmen Zahlen und Datumsangaben auf.
- Checkbox ist ein einzelnes Kästchen. Multi checkbox, Radio button, Single select und Multi select bieten Auswahllisten.
- File upload und Image upload nehmen Dateien entgegen.
- Hidden ist ein verstecktes Feld, das Besucher nicht sehen. Static text zeigt nur einen Text an.
Dazu kommen Container. Ein Fieldset fasst inhaltlich zusammengehörige Felder mit einer Überschrift zusammen, zum Beispiel Straße, Postleitzahl und Ort einer Postadresse. Screenreader lesen diese Gruppe als Einheit vor, das verbessert die Barrierefreiheit. Felder nebeneinander in Spalten anzuordnen ist dagegen Aufgabe des Elements Grid: Row, einer Rasterzeile mit Spalten.
Die meisten Elemente haben dieselben Grundeinstellungen:
- Label ist die sichtbare Beschriftung des Feldes.
- Description ist ein Hilfetext unter dem Feld.
- Field visible blendet das Feld ein oder aus.
- Placeholder zeigt ein Beispiel im leeren Feld.
- Default value ist ein Standardwert, der schon im Feld steht.
- Der Haken Field required macht das Feld zum Pflichtfeld. Die Editors-Doku nennt das auch Mandatory field oder Required field. Dazu gehört eine Custom error message, also eine eigene Fehlermeldung.
- Validators prüfen die Eingabe, dazu gleich mehr.
- Autocomplete sagt dem Browser, welche Art Angabe gefragt ist, zum Beispiel Vorname oder E-Mail-Adresse.
Ein Pflichtfeld muss vor dem Absenden ausgefüllt sein. Fehlt die Eingabe, erscheint die Fehlermeldung, und das Formular wird nicht abgeschickt.
Platzhalter oder Standardwert? Der Platzhalter ist nur ein grauer Hinweis, etwa ein Muster für die Telefonnummer. Er verschwindet, sobald man tippt, und wird nie mitgeschickt. Der Standardwert ist dagegen ein echter, vorausgefüllter Wert. Er steht im Feld, bis man ihn ändert, und wird sonst so abgeschickt.
Validatoren: Eingaben prüfen
Ein Validator prüft, ob eine Eingabe gültig ist. Er übersetzt nichts und speichert nichts. Ist die Eingabe ungültig, zeigt das Formular eine Fehlermeldung, die man ebenfalls anpassen kann. Im Formulareditor stehen unter anderem diese Validatoren bereit:
- Alphanumeric erlaubt nur Buchstaben und Ziffern. Non-XML text verbietet HTML-Code.
- String length begrenzt die Länge eines Textes.
- Email prüft, ob eine gültige E-Mail-Adresse eingegeben wurde.
- Integer number, Floating-point number und Number prüfen Zahlen, Number range einen Zahlenbereich.
- Regular expression prüft gegen ein frei definiertes Muster.
- Date range prüft einen Datumsbereich.
- Number of submitted values zählt die gewählten Optionen einer Mehrfachauswahl.
- File size und Number of files prüfen hochgeladene Dateien.
Das Element Email address bringt seinen Validator gleich mit: Email ist automatisch aktiv und zugleich der einzige, den man dort wählen kann. Auf Smartphones erscheint dazu eine Tastatur mit dem At-Zeichen.
Uploads. Beim Fotowettbewerb „Mein Lieblingsbuch“ dürfen Teilnehmende bis zu drei Bilder hochladen. Seit TYPO3 14.2 erlauben Upload-Felder mehrere Dateien. Lena setzt am Element Image upload den Haken Allow multiple upload und fügt den Validator Number of files mit einem Maximum von drei hinzu. Die Größe jeder Datei begrenzt der Validator File size.
Uploads haben eine Datenschutzseite. Im Feld Uploads save path wählt man den Ordner, in dem die Dateien landen. Liegt dieser Ordner öffentlich erreichbar, kann jeder die Dateien aufrufen, und Suchmaschinen können sie indexieren. Verschlüsselt oder automatisch gelöscht werden die Dateien nicht von selbst. Für sensible Dokumente wie Bewerbungen bittet Lena deshalb Tom, einen geschützten Speicherpfad anzulegen.
Finisher: was nach dem Absenden passiert
Ein Finisher ist eine Aktion, die läuft, nachdem jemand das Formular abgeschickt hat. Er ist weder ein Feld noch ein Knopf noch ein Validator. Lena wählt ihn in den allgemeinen Einstellungen des Formulars. Zur Auswahl stehen:
- Email to receiver (you) schickt eine Mail an den Betreiber der Website, bei der Bibliothek an das Postfach der Auskunft.
- Email to sender (form submitter) schickt der ausfüllenden Person eine Mail, etwa eine Eingangsbestätigung.
- Confirmation message zeigt nach dem Absenden einen Dank auf der Seite.
- Redirect to a page leitet auf eine andere Seite weiter.
- Delete uploads löscht hochgeladene Dateien, nachdem sie zum Beispiel per Mail verschickt wurden.
Bei den Mail-Finishern trägt Lena Betreff, Empfänger, Namen und eine Kopie ein. Über einen Knopf mit Pluszeichen fügt sie Werte aus dem Formular ein, etwa Vor- und Nachnamen als Absendernamen.
Die Reihenfolge zählt. Finisher laufen genau in der Reihenfolge, in der sie in der Liste stehen. TYPO3 sortiert nichts um. Die Weiterleitung beendet die Ausführung, danach läuft kein Finisher mehr. Deshalb gehört Redirect to a page immer ans Ende.
Das Formular auf einer Seite einbinden
Ein fertiges Formular erscheint noch nirgends. Lena bindet es so ein:
- Sie öffnet das Modul Layout und wählt im Seitenbaum die Seite „Kontakt“.
- Sie legt ein neues Inhaltselement an und wählt im Reiter „Form elements“ das Element Form.
- Im Reiter Plugin wählt sie die Formulardefinition „Kontakt Bibliothek“.
- Sie speichert das Inhaltselement und prüft die Seite im Frontend.
Weil die Formulardefinition getrennt vom Inhaltselement liegt, kann Lena dasselbe Formular auf vielen Seiten nutzen. Auf „Kontakt“, „Medien“ und „Öffnungszeiten“ legt sie je ein Element Form an, alle mit derselben Definition. Die Überschrift trägt sie jeweils im normalen Header-Feld des Inhaltselements ein. Deshalb hatte sie den Titel „Step“ im Formular geleert. Kopien der Formulardefinition braucht sie nicht. Änderungen an der Definition wirken überall, wo sie eingebunden ist. Im Plugin lassen sich zudem einzelne Finisher-Einstellungen für diese eine Seite überschreiben, zum Beispiel der Empfänger.
Datensätze im Modul Records
Nicht alles in TYPO3 ist eine Seite oder ein Inhaltselement. Website-Benutzer, Benutzergruppen, Kategorien oder News sind Datensätze. Für viele davon gibt es kein eigenes Modul. Dann arbeitest du im Modul Records im Bereich Content. Es hieß bis TYPO3 13 Web, List.
Lena wählt im Seitenbaum eine Seite oder einen Ordner, zum Beispiel den Ordner „Website-Benutzer“. Records zeigt alle Datensätze dort, nach Typ gruppiert. Oben im Modul liegen Knöpfe, etwa zum Anlegen eines neuen Datensatzes und zum Einblenden von Suche und Zwischenablage.
- Öffnen und bearbeiten: Ein Klick auf den Titel oder auf das Stift-Symbol öffnet das Formular des Datensatzes.
- Verstecken und löschen: Daneben stehen Symbole zum Verstecken, Wieder-Einblenden und Löschen. Weitere Aktionen bietet das Menü mit den drei Punkten.
- Suchen: In langen Listen hilft das Suchfeld. Wie viele Ebenen von Unterseiten mit durchsucht werden, stellst du ein.
Sprachen. Seit TYPO3 14 hat Records oben rechts ein Sprachmenü. Darin hakt Lena an, welche Sprachen die Liste zeigt. Wählt sie Französisch, sieht sie die französischen Übersetzungen unter ihren Originalen. Die Datensätze der Standardsprache bleiben immer stehen, ebenso Datensätze mit der Sprache „All languages“. TYPO3 merkt sich die Wahl je Seite, und das Modul Layout zeigt dieselben Sprachen.
Kopieren und verschieben. Einen einzelnen Datensatz kopierst du über das Kontextmenü. Lena öffnet es über die drei Punkte oder das Symbol links vom Datensatz und wählt Copy, zum Verschieben Cut. An der Zielstelle fügt sie mit Paste ein. Inhaltselemente versteckt TYPO3 nach dem Kopieren zunächst. Liegt am Ziel schon ein Element mit demselben Titel, hängt TYPO3 an den Titel der Kopie „(copy 1)“ an.
Zwei Meldungen beim Einfügen sollte man kennen:
- Falscher Ort: Manche Datensätze dürfen nur in Ordnern liegen, etwa Website-Benutzer und Website-Benutzergruppen. Fügt Lena eine Benutzergruppe auf einer normalen Seite ein, erscheint eine Fehlermeldung, und nichts wird eingefügt. Sie wechselt in den passenden Ordner und fügt dort erneut ein.
- Eindeutige Werte: Kopiert Lena den Website-Benutzer „max“ in denselben Ordner, heißt die Kopie „max1“. Benutzernamen müssen im selben Ordner eindeutig sein, darum hängt TYPO3 eine Zahl an. Lena öffnet die Kopie und vergibt einen passenden Namen.
Zwischenablage und Massenbearbeitung
Für mehrere Datensätze auf einmal gibt es die Zwischenablage, englisch Clipboard. Lena blendet sie über das Menü View oben im Modul Records ein. Unten erscheint nun die Ablage. Die normale Ablage nimmt nur einen Datensatz auf. Lena wählt deshalb eine nummerierte Ablage wie Clipboard 1. Nur damit kann sie mehrere Datensätze auf einmal in die Zwischenablage legen.
Vor jedem Datensatz steht ein Kästchen zum Markieren. Sobald Datensätze markiert sind, zeigt die Liste neue Knöpfe für die Auswahl:
- Edit bearbeitet alle markierten Datensätze.
- Delete löscht sie.
- Transfer to clipboard legt sie in die Zwischenablage. Diesen Knopf gibt es nur bei einer nummerierten Ablage.
- Remove from clipboard nimmt sie wieder heraus, ebenfalls nur bei einer nummerierten Ablage.
Die Zwischenablage sammelt Datensätze, auch von verschiedenen Seiten. In der Ablage ist standardmäßig Move elements gewählt, also Verschieben. Wer kopieren will, klickt Copy elements. Dann bleibt die Ausgangsseite unverändert. Auf der Zielseite klickt Lena „Paste in clipboard content“ und bestätigt die Rückfrage.
Spalten und Massenbearbeitung. Die Liste zeigt je Tabelle nur wenige Felder. Über Show columns öffnet Lena einen Dialog, wählt weitere Felder und klickt Update. Die Felder erscheinen nun als Spalten. Zum Markieren aller Datensätze wählt sie im Auswahlmenü links Check all. Toggle selection kehrt die Auswahl um. Dann hat sie zwei Wege:
- Edit zeigt alle Felder aller markierten Datensätze untereinander.
- Edit columns zeigt nur die Felder, die gerade als Spalten eingeblendet sind.
Nur eine Tabelle zeigen. In der Übersicht aller Tabellen zeigt Records standardmäßig 20 Einträge je Tabelle. Ein Klick auf List only this table beim Titel einer Tabelle zeigt nur diese, mit 100 Einträgen je Seite. List all tables führt zurück. Beide Werte kann ein Integrator per TSconfig ändern.
Datensätze herunterladen: CSV und JSON
Records bietet bei jeder Tabelle einen Download an. Der Dialog kennt genau zwei Formate: CSV und JSON. Lena stellt ein:
- Spalten: nur die gewählten Spalten oder alle Spalten.
- Format der Werte: Raw values sind die rohen Datenbankwerte, etwa Zahlen-IDs oder Zeitstempel. Processed values sind für Menschen aufbereitet, mit lesbaren Bezeichnungen und Datumsangaben wie im Backend.
- Dateiname: frei wählbar.
- Format und formatabhängige Optionen.
Bei CSV wählt Lena das Trennzeichen, den Delimiter: comma, semicolon oder pipe. Voreingestellt ist das Komma. Außerdem wählt sie das Anführungszeichen, den Quote character: doppeltes oder einfaches Anführungszeichen oder Leerzeichen. Voreingestellt ist das doppelte Anführungszeichen. Ein eigenes Zeichen kann ein Integrator per TSconfig vorgeben. Es erscheint dann im Dialog als zusätzliche Wahl „user defined“ und ist voreingestellt. Bei JSON gibt es stattdessen die Option Meta information. Sie bestimmt, ob vor den Datensätzen alle Zusatzinformationen, nur Tabellenname und Seiten-ID oder gar nichts stehen.
CSV-Dateien verstehen
CSV steht für Character Separated Values, also durch Zeichen getrennte Werte. Eine CSV-Datei ist eine einfache Textdatei mit Tabellendaten. Jede Zeile ist ein Datensatz, und ein Trennzeichen trennt die Werte. Oft enthält die erste Zeile die Spaltennamen. CSV dient dem Datenaustausch zwischen Systemen, etwa zwischen TYPO3 und einer Tabellenkalkulation.
Üblich sind als Trennzeichen Komma und Semikolon, außerdem Tabulator und der senkrechte Strich, die Pipe. Öffnen und bearbeiten kannst du CSV mit jedem Texteditor oder übersichtlich in Spalten mit einer Tabellenkalkulation.
Das Begrenzungszeichen. Was passiert, wenn ein Wert selbst das Trennzeichen enthält? Dann umschließt ein Begrenzungszeichen, englisch Enclosure, meist ein doppeltes Anführungszeichen, den ganzen Wert. Das Trennzeichen darin zählt dann nicht. Steht ein Anführungszeichen im Wert, wird es verdoppelt, und der ganze Wert kommt in Anführungszeichen.
1;"Muster; Partner GmbH";Berlin
"Sie sagte ""Hallo"""Zeichenkodierung: warum aus Grün manchmal Unsinn wird
Computer speichern nur Zahlen. Eine Zeichenkodierung ist eine Zuordnung von Zeichen zu Zahlen. Sie legt fest, welche Zahl für „A“, für „ä“ oder für das Euro-Zeichen steht.
Warum gibt es mehrere Kodierungen? Frühe Kodierungen deckten nur wenige Sprachen ab. ASCII kennt 128 Zeichen, ohne Umlaute. ISO-8859-1, auch Latin-1 genannt, nutzt ein Byte pro Zeichen und kennt 256 Zeichen. Das reicht für westeuropäische Sprachen, aber nicht für Chinesisch oder Griechisch. Windows-1252 ist eine enge Verwandte von Latin-1. Unicode sammelt nahezu alle Schriftzeichen der Welt. Die Kodierung UTF-8 kann alle Unicode-Zeichen darstellen und braucht dafür ein bis vier Bytes je Zeichen. Die ersten 128 Zeichen sind mit ASCII identisch. UTF-8 ist heute der Standard im Web, und auch TYPO3 arbeitet mit UTF-8.
Was schiefgeht. Wird eine Datei mit einer anderen Kodierung gelesen, als sie geschrieben wurde, erscheinen Umlaute und Sonderzeichen falsch. Die Daten sind nicht verloren, sie werden nur mit der falschen Tabelle gelesen.
Steht in einer importierten Liste also ein großes A mit Tilde mitten in „Grün“, war der Text in UTF-8 gespeichert und wurde als ISO-8859-1 gelesen. Lena öffnet die Datei erneut und wählt UTF-8.
Kodierung herausfinden. Viele Texteditoren zeigen die Kodierung einer Datei in der Statuszeile an und können sie umstellen. Auf der Kommandozeile hilft das Programm file. Die Dateiendung umzubenennen ändert nichts.
Kodierung umwandeln. Der Bibliotheksverbund schickt Lena eine Medienliste als CSV in Windows-1252. Die Website und TYPO3 arbeiten mit UTF-8. Lena wandelt die Datei deshalb vor der Verarbeitung nach UTF-8 um, mit einem Editor oder einem Werkzeug wie dem Import-Dialog der Tabellenkalkulation. Unverändert zu übernehmen würde kaputte Umlaute erzeugen.
Das Wichtigste in Kürze
- Formulare baust du im Modul Forms. Seit TYPO3 14.2 liegen sie empfohlen in der Datenbank.
- Jedes Feld braucht ein klares Label. Validatoren prüfen die Eingaben.
- Finisher laufen in ihrer Reihenfolge. Die Weiterleitung beendet alles und steht am Ende.
- Eine Formulardefinition bindest du mit dem Inhaltselement Form auf vielen Seiten ein.
- Datensätze ohne eigenes Modul pflegst du in Records. Die Zwischenablage verschiebt standardmäßig.
- Edit zeigt alle Felder, Edit columns nur die eingeblendeten Spalten.
- Der Download kennt CSV und JSON. UTF-8 ist der Standard für Zeichen.
Begriffe
- Form Framework
- Die System-Extension form, mit der Redakteure Formulare im Modul Forms bauen.
- Formulardefinition
- Das gespeicherte Formular, das man mit dem Inhaltselement Form auf beliebig vielen Seiten einbindet.
- Finisher
- Eine Aktion nach dem Absenden, etwa eine E-Mail, eine Bestätigung oder eine Weiterleitung.
- Validator
- Eine Prüfung, ob die Eingabe in einem Feld gültig ist.
- Records
- Das Modul im Bereich Content, das alle Datensätze einer Seite oder eines Ordners nach Typ gruppiert zeigt.
- CSV
- Eine Textdatei mit Tabellendaten, deren Werte je Zeile durch ein Trennzeichen getrennt sind.
- Begrenzungszeichen
- Meist ein Anführungszeichen, das einen Wert mit Trennzeichen darin umschließt.
- Zeichenkodierung
- Die Zuordnung von Zeichen zu Zahlen, heute meist UTF-8.