Xtmembers fieldeditor

Diese Erweiterung ermöglicht es, eigene Mitgliederfelder zu erstellen und diese der Contao-Installation hinzuzufügen.

Editor zum Erstellen von Datenfeldern für Mitglieder

Die Erweiterung xtmembers_fieldeditor erlaubt das Anlegen eigener Datenfelder für Contao-Mitglieder. Mit der aktuellen Version ist es möglich, Datenfelder vom Typ text (Textfelder) und select (Drop-Down-Felder) anzulegen. Die neu erstellen Felder werden dann über eine Exportschnittstelle als neue Contao-Erweiterung zur Verfügung gestellt, entweder durch Kopieren der Erweiterung in das TL_ROOT/system/modules-Verzeichnis oder durch das Komprimieren in einer ZIP-Datei, die Sie herunterladen können.

Da bei der Zusammenstellung der Erweiterung die neuen Felder immer hinter bestehenden Feldern in die Backend-Formulare eingefügt werden, muss beachtet werden, ob die bestehenden Felder nicht bereits von einer Contao-Erweiterung definiert wurden. In dem Fall kann es bei ungünstiger Benennung der eigenen Erweiterung dazu führen, dass diese Felder noch gar nicht 'bekannt' sind, da Contao-Erweiterungen alphabetisch in der Folge ihres Auftretens initialisiert werden. Man sollte deshalb unter Umständen einen Namen für die Erweiterung verwenden, der im Alphabet hinter Erweiterungen liegt, die zusätzliche Mitgliederfelder definieren.

Äußern wird sich ein fehlerhaftes Verhalten dadurch, dass die neuen Felder eventuell nicht an der Position eingefügt werden, die man vorgesehen hat. xtmembers_fieldeditor wird die neuen Felder aber auch in einem solchen Problemfall auf jeden Fall einfügen, dann aber leider erst am Ende der zu diesem Zeitpunkt bekannten Felder.

Aufrufen des Editors

Der Editor sollte sich in der Liste der Backend-Module zwischen den Mitgliedern und den Benutzern in der Sektion Benutzerverwaltung befinden.

Position des Editors in der Liste der Backend-Module

Man klickt auf das Symbol des Editors um den Editor zu öffnen. Der Editor präsentiert sich als Übersicht, in der man neue Mitgliederfelder erstellt, bestehende Mitgliederfelder bearbeiten oder die vorhandenen Mitgliederfelder als Erweiterung exportieren kann.

Übersicht über bereits angelegte Mitgliederfelder

Erstellen eines neuen Mitgliederfeldes

Dazu wählt man 'Neues Mitgliederfeld' aus. Der Editor für ein neues Feld besteht aus den folgenden Komponenten:

Titel-Sektion

Die Titelsektion besteht aus den Feldern Titel, Name des Datenbankfeldes und Beschreibung.

Titel-Sektion eines Mitgliederfeldes

• Titel bezeichnet den Titel des Mitglieder-Feldes, der z.B. im Mitglieder-Bearbeitungsformular des Backends als Titel des Feldes angezeigt wird.
• Name des Datenbankfeldes ist der Name des Mitglieder-Feldes in der Datenbank. Dieser Name darf nur aus Kleinbuchstaben von a bis z und dem Unterstrich bestehen. Vor diesen Namen wird bei der Generierung der Erweiterung automatisch das Präfix 'xt_' gestellt, um Namenskonflikte mit bestehenden Mitgliederfeldern zu vermeiden.
• Beschreibung ist die Beschreibung des Mitglieder-Feldes, die z.B. im Mitglieder-Bearbeitungsformular des Backends als Beschreibung unter dem Feld angezeigt wird.

Feld-Daten-Sektion

Die Feld-Daten-Sektion besteht aus Feldern, die die Darstellung und die Daten des Mitglieder-Feldes festlegen. Diese Felder sind Feldtyp, Pflichtfeld, Standardwert, Minimale Länge (nur Textfeld), Maximale Länge (nur Textfeld), Regulärer Ausdruck (nur Textfeld), Feld-Optionswerte (nur Auswahlfeld), Leeren Optionswert zufügen (nur Auswahlfeld), CSS-Klasse.

Gemeinsame Feld-Daten

• Man wählt den Feldtyp aus, um die Art des Mitglieder-Feldes festzulegen. Auswahlmöglichkeiten sind: Textfeld und Auswahlfeld. Je nach Auswahl wird das Eingabeformular neu geladen und die benötigten Felder in der Feld-Daten-Sektion angezeigt.
• Wenn man das Feld als Pflichtfeld festlegt, muss das Mitglieder-Feld bei der Eingabe über einen Inhalt verfügen.
• Der Standardwert gibt den Wert an, mit dem das Mitglieder-Feld vorbelegt wird, wenn ein neues Mitglied in Contao angelegt wird. Bei Auswahlfeldern muss der Standardwert dem Wert eines der erstellten Optionsfelder entsprechen, falls er angegeben wird.
• Die CSS-Klasse ist eine der verfügbaren Contao-Klassen für den Eval-Ausdruck tl_class des Mitglieder-Feldes. Dieser Wert dient zur Ausrichtung des Feldes im Backend-Formular. Mögliche Werte findet man unter http://www.contao.org/palettes.html. Zum Zeitpunkt dieser Dokumentation handelte es sich dabei um: w50, clr, wizard, long, m12.

Feld-Daten eines Textfeldes

Feld-Daten eines Textfeldes

• Minimale Länge gibt die minimale Anzahl von Zeichen an, die in das Mitglieder-Feld eingegeben werden müssen. Wenn man dieses Feld leer lässt, muss keine minimale Anzahl von Zeichen eingegeben werden.
• Maximale Länge gibt die maximale Anzahl von Zeichen an, die in das Mitglieder-Feld eingegeben werden dürfen. Wenn man dieses Feld leer lässt, gibt es keine Beschränkung der maximalen Anzahl von Zeichen.
• Regulärer Ausdruck bezeichnet einen Ausdruck zur Validierung des Feldinhaltes. Contao gibt eine Reihe von Ausdrücken vor, die zur Sicherstellung des Inhaltes verwendet werden können. Diese sind (zum Zeitpunkt dieser Dokumentation):
  digit: nur numerische Eingabe erlaubt
  alpha: nur Zeichen aus dem Alphabet erlaubt
  alnum: nur alphabetische Zeichen und Zahlen erlaubt
  prcnt: nur Zahlen zwischen 0 und 100 erlaubt
  extnd: Verbietet die Zeichen #&()/>=<
  phone: Erwartet eine Telefonnummer
  date: Erwartet ein gültiges Datum
  datim: Erwartet ein gültiges Datum und eine gültige Uhrzeit
  time: Erwartet eine gültige Uhrzeit
  email: Erwartet eine gültige E-Mail-Adresse
  url: Erwartet eine gültige URL-Zeichenkette
  Natürlich kann man auch eigene Ausdrücke angeben, die man mit Hilfe von Erweiterungen zu Contao hinzugefügt hat. Weitere Informationen findet man unter http://www.contao.org/reference.html.

Feld-Daten eines Auswahlfeldes

Feld-Daten eines Auswahlfeldes

• Bei den Feld-Optionswerten handelt es sich um die Optionswerte, die im Auswahlfeld angezeigt werden sollen. Diese müssen immer im Paar eingegeben werden und bestehen aus einem Wert, der in der Datenbank abgelegt wird und einer Beschreibung, die als Text im Auswahlfeld erscheint.
• Leeren Optionswert zufügen fügt an den Beginn des Auswahlfeldes einen leeren Optionswert hinzu. Der leere Optionswert ist keine gültige Auswahl, wenn es sich bei dem Feld um ein Pflichtfeld handelt.

Feld-Kategorisierung-Sektion

Die Feld-Kategorisierung-Sektion legt fest, in welche Kategorien das Mitgliederfeld integriert wird, wenn es im Frontend verwendet wird. Außerdem können Anzeige- und Bearbeitungsmöglichkeiten festgelegt werden:

Feld-Kategorisierung des Mitglieder-Feldes

• Man legt eine Frontend-Gruppe fest, der das Mitglieder-Feld zugeordnet werden soll. Die Frontend-Gruppe wird für Kategorisierungen im Frontend verwendet, z.B. bei der Gruppierung und Ausgabe von Mitglieder-Daten. Auswahlmöglichkeiten sind personal (Daten zur Person), address (Adressdaten), contact (Kontaktdaten), login (Logindaten), helpdesk (Helpdesk-Daten), profile (Daten des Benutzerprofils), newsletter (Daten für Newsletter). Weitere Auswahlmöglichkeiten können vorhanden sein, wenn diese durch Contao-Erweiterungen erzeugt wurden.
• Ist das Mitglieder-Feld als Editierbar gekennzeichnet, darf es im Frontend bearbeitet werden, wenn dies mit einem entsprechenden Modul erlaubt wird.
• Ist das Mitglieder-Feld als Sichtbar gekennzeichnet, darf es im Mitgliederlisten-Modul im Frontend angezeigt werden.

Feld-Positionierung-Sektion

Die Feld-Positionierung legt die Position des Mitglieder-Feldes im Mitglieder-Editor des Backends fest.

Feld-Positionierung des Mitglieder-Feldes

• Man wählt eine Einfügeposition aus, hinter der das Mitglieder-Feld in den Mitglieder-Editor integriert werden soll. Es ist zu beachten, dass die Einfügeposition nicht nur aus den in Contao vorgegebenen Mitglieder-Feldern bestehen kann, sondern auch aus Feldern, die durch zusätzliche Erweiterungen definiert werden. Eine detaillierte Beschreibung dieser Problematik findet man in dem als Wichtig gekennzeichneten Abschnitt am Anfang dieses Dokuments. Die Optionswerte in geschweiften Klammern bezeichnen den Beginn einer neuen Sektion, eine Legende. Die Optionswerte ohne geschweifte Klammern bezeichnen bestehende Mitglieder-Felder.
• Man kann vor dem neuen Mitglieder-Feld eine neue Legende erzeugen und damit eine neue aufklappbare Sektion eröffnen. Dazu muss man das Feld Neue Legende ausfüllen. Erlaubt sind Kleinbuchstaben von a bis z und der Unterstrich. Es ist zu beachten, dass alle nachfolgenden Felder automatisch Teil dieser Sektion werden, bis eine weitere Sektion begonnen wird.
• Wenn man eine neue Legende hinzufügt, sollte man dieser Legende auch eine Bezeichnung geben, den man im Feld Titel der Legende eintragen kann.

Erstellen einer Erweiterung mit neuen Mitglieder-Feldern

Um aus den neu erstellten Mitglieder-Feldern eine Contao-Erweiterung zu machen, klickt man auf Mitgliederfelder als Contao-Erweiterung exportieren im Kopf des Mitglieder-Feldeditors.

Exportieren von Mitglieder-Feldern als Contao-Erweiterung

Im nun erscheinenden Exportformular muss man den Namen der Contao-Erweiterung angeben und für das Erstellen der Urheberinformationen den Autor, einen Copyright-Vermerk und die Lizenz, unter der die Erweiterung veröffentlicht werden soll eingeben.

Wenn man Erweiterung als ZIP-Datei herunterladen auswählt, wird die Contao-Erweiterung in einer ZIP-Datei geschrieben und zum Download angeboten. Wenn man das Kontrollkästchen dieses Feldes nicht auswählt, wird die Erweiterung unter dem im Feld Autor angegebenen Namen in dem Contao-Modulverzeichnis erstellt. Falls sich bereits eine Erweiterung dieses Namens dort befindet, so muss man diese erst händisch löschen oder aber einen anderen Namen für die Erweiterung definieren.

Verwenden der eigenen Erweiterung in Contao

Wenn man die aus den neuen Mitgliederfeldern erzeugte Erweiterung nun in sein Contao system/modules-Verzeichnis geschrieben hat oder eine erzeugte ZIP-Datei dort ausgepackt hat, muss man die üblichen Schritte für eine Erweiterung gehen und in diesem Fall, da neue Datenbankfelder erzeugt werden, natürlich das Contao-Installationsskript (http://PFAD_ZU_Contao/Contao/install.php) aufrufen, um dort die Datenbank zu aktualisieren.

Dieser Schritt muss natürlich auch immer nach Änderungen an Feldern im Mitglieder-Feldeditor durchgeführt werden. Das ist leider etwas umständlich, aber durch die Tatsache, dass hier Datenbankmanipulationen vorgenommen werden, leider nicht zu vermeiden.

xtmembers_fieldeditor ist keine Erweiterung, die man regelmäßig benutzt. Man sollte sich ein Mal überlegen, welche Felder man zusätzlich zu den vorhandenen Feldern erstellen möchte, diese erzeugen und installieren. So hält sich die Aufwand, regelmäßig Datenbank-Update-Skripte aufrufen zu müssen in Grenzen.

Anmerkung des Autors: Ich hoffe, ich erleichtere denjenigen etwas die Arbeit, die mal eben eine Contao-Erweiterung für zusätzliche Mitgliederfelder definieren möchten, aber nicht so tief in der Entwicklung stecken, dass es ein Selbstgänger ist.

--Hschottm 13:33, 11. Sep. 2010 (CEST)