Quelltext der Seite Xtmembers fieldeditor

[[Kategorie:Extensions]]

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

{{ExtInfo
| Dev=Helmut Schottmüller ([[User:hschottm|hschottm]])
| DevSite=http://www.aurealis.de
| ExtVersion=1.0.0
| Version=2.9.0 - 2.9.1
| TLVersion=2.7.0 - 2.8.4
| ERLink=http://www.contao.org/erweiterungsliste/view/xtmembers_fieldeditor.de.html
| DonateLink=http://aurealis.de/spenden.html
}}

== 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.

{{msgImportant|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. 

[[Datei:xtmembers_fieldeditor_tree.png|Position des Editors in der Liste der Backend-Module|center|frame]]

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.

[[Datei:xtmembers_fieldeditor_overview.png|Übersicht über bereits angelegte Mitgliederfelder|center|frame]]
=== 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'''.

[[Datei:xtmembers_fieldeditor_title.png|Titel-Sektion eines Mitgliederfeldes|center|frame]]

* '''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 ===

[[Datei:xtmembers_fieldeditor_fielddata_text.png|Feld-Daten eines Textfeldes|center|frame]]

* '''Pflichtfeld''' legt fest, ob für dieses Feld ein Wert eingegeben werden muss.
* '''Standardwert''' legt einen Standardwert fest, mit dem das Feld automatisch belegt wird.
* '''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):<br />''digit:'' nur numerische Eingabe erlaubt<br />''alpha:'' nur Zeichen aus dem Alphabet erlaubt<br />''alnum:'' nur alphabetische Zeichen und Zahlen erlaubt<br />''prcnt:'' nur Zahlen zwischen 0 und 100 erlaubt<br />''extnd:'' Verbietet die Zeichen #&()/>=<<br />''phone:'' Erwartet eine Telefonnummer<br />''date:'' Erwartet ein gültiges Datum<br />''datim:'' Erwartet ein gültiges Datum und eine gültige Uhrzeit<br />''time:'' Erwartet eine gültige Uhrzeit<br />''email:'' Erwartet eine gültige E-Mail-Adresse<br />''url:'' Erwartet eine gültige URL-Zeichenkette<br />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.
* '''Zeilenumbruch''' gibt die Art des Zeilenumbruchs für Feldinhalte an, die wegen ihrer Länge nicht mehr in den dafür vorgesehenen Bereich passen.
* '''Keine Leerzeichen''' legt fest, ob Leerzeichen eingegeben werden dürfen oder nicht.
* '''HTML-Tags erhalten''' erlaubt die Verwendung von HTML-Tags in Benutzereingaben.
* '''HTML-Entities dekodieren''' legt fest, ob die HTML-Entities dekodiert werden.
* '''Leerzeichen umwandeln''' wandelt alle Leerzeichen in Unterstriche um.
* '''Einzigartiger Inhalt''' legt fest, dass der Feldinhalt nur ein einziges Mal vorkommen darf.
* '''Verschlüsseln''' speichert den Feldinhalt verschlüsselt.
* '''HTML erlauben'''  legt fest, ob HTML-Eingaben erlaubt sind.
* '''Formatierung'''  erlaubt CSS-Formatierungen für das Feld einzugeben.
* '''CSS-Klasse'''  erlaubt die Angabe einer oder mehrerer durch Leerzeichen getrennter CSS-Klassennamen, mit denen das Feld formatiert wird.

=== Feld-Daten eines Auswahlfeldes ===

[[Datei:xtmembers_fieldeditor_fielddata_select.png| Feld-Daten eines Auswahlfeldes|center|frame]]

* 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:

[[Datei:xtmembers_fieldeditor_categories.png|Feld-Kategorisierung des Mitglieder-Feldes|center|frame]]

* 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.

[[Datei:xtmembers_fieldeditor_fieldpos.png|Feld-Positionierung des Mitglieder-Feldes|center|frame]]

* 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 [[#Erstellen_eines_neuen_Mitgliederfeldes|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. 

[[Datei:xtmembers_fieldeditor_export.png|Exportieren von Mitglieder-Feldern als Contao-Erweiterung|center|frame]]

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.


--[[Benutzer:Hschottm|Hschottm]] 13:33, 11. Sep. 2010 (CEST)