Die TYPO3 Extension „Browser – TYPO3 without PHP“: Anwendungsbeispiel mit tt_address Daten

600 Seiten Dokumentation gibt es für diese sehr schöne Extension, die vor allem für TYPO3 Integratoren geeignet ist, die nicht selbst PHP programmieren können oder möchten. Anwendungsbeispiel hier ist die Auswahl von tt_address Datensätzen mit Hilfe zweier Select-Boxen.

Die Liste der Browser-Tutorials findet man hier:
typo3-browser.de/en/browser-tutorials/

Ziel: tt_address Datensätze (hier handelt es sich um eine Datenbank für Absolventen unterschiedlicher Ausbildungsrichtungen) sollen mit Hilfe der Browser-Extension sowohl nach Adressgruppen (Ausbildung) als auch nach PLZ-Bereichen (10000 – 19999, 20000 – 29999 etc.) durchsuchbar sein.

tt_address Datensätze anzeigen

Zunächst installiert man sich die Extension „Browser – TYPO3 without PHP„, legt eine neue Seite an (Seite 1) und installiert das statische Template der browser Extension (bei der neueren Version 7.3 ist das etwas kompliziert, da die Extension mit etlichen statischen Templates daher kommt – für unser Beispiel genügen folgende: Browser [1] Basis (browser) und Browser [1] + pageBrowser Wrap v.4.9 (browser). Weiterhin legt man eine Unterseite an (Sys Ordner, Seite 2) und gibt dort einige tt_address Datensätze samt Adressgruppen ein. Als nächstes legt man einen Browser-Plugin Datensatz auf Seite 1 an. Unter dem Reiter „Plugin Check“ erscheint folgende Fehlermeldung: Fehler: Es ist keine View konfiguriert. Dies wird folgendermaßen behoben: im Datensatz, mit dem das Browser-Plugin eingebunden wird, gibt es den Reiter „Verhalten“; hier muss dem Plugin gesagt werden, wo sich die tt_address Datensätze befinden („Datensatzsammlung“).

Um ein eigenes HTML Template verwenden zu können, kopiert man die Datei default.tmpl aus typo3conf/ext/browser/res/html (in der neueren Version liegt das benötigte Template hier: typo3conf/ext/browser/Resources/Private/Templates/HTML/default.tmpl) in ein beliebiges Verzeichnis in fileadmin (hier: fileadmin/templates/erweiterungen/browser.html). Im Plugin-Datensatz unter dem Reiter „Templating“ wählt man bei „Plugin: HTML-Vorlage“ „From TypoScript“.

Auf Seite 1 gibt man folgendes TypoScript ein:

plugin.tx_browser_pi1 {
 
  #template.file = fileadmin/templates/erweiterungen/browser.html
 
  views {
    list {
      1 {
        // [String] Name of the view. It will displayed in the plugin/flexform
        name = Browser Sample
        // [String] Select clause (don't confuse it with the SQL select)
        select (
          tt_address.name
        )
        // [String] Order By clause (don't confuse it with the SQL Order By)
        orderBy (
          tt_address.name DESC
        )
      }
    }
    single {
      1 {
        // [String] Select clause (don't confuse it with the SQL select)
        select (
          tt_address.name,
          tt_address.city,
          tt_address_group.title
        )
      }
    }
  }
}

Damit hat man im Frontend bereits eine rudimentäre Listen Darstellung der tt_address Datensätze sowie ein Suchformular.

Datensätze filtern mit Select-Boxen

Hierfür nehme man das Tutorial Browser Tutorial Search and Filter (en) zur Hand. Unser Ziel ist es, zwei Select-Boxen zu generieren, mit deren Hilfe man die Datensätze nach Adressgruppe und PLZ-Bereich durchsuchen kann.

Für die erste Select-Box, der Suche nach der Adressgruppe, gibt man im HTML Template im Bereich der „SEARCHFORM“ den Marker ###TT_ADDRESS_GROUP.TITLE### ein, z.B. unterhalb von dieser Zeile: <!-- Add filters with the ###TABLE.FIELD### syntax and configure your filters with TypoScript -->. Im TypoScript fügt man folgendes hinzu:

plugin.tx_browser_pi1 {
  ...
  views {
    list {
      1 {
        ...
        filter {
          tt_address_group {
            title < plugin.tx_browser_pi1.displayList.master_templates.selectbox
          }
        }
      }
    }
    ...
  }
}

Für die zweite Box, die den PLZ-Bereich anzeigen soll, also z.B. PLZ-Bereich 1 für alle PLZ, die mit 1 beginnen, könnte man folgendermaßen vorgehen:
Man kreiert die Select-Box im HTML Template folgendermaßen, sozusagen per Hand:

<div class="selectbox">
	<div class="selectbox_title">PLZ:</div>
	<select name="tx_browser_pi1[tt_address.zip][]" id="tx_browser_pi1_tt_address_zip" size="1">
		<option value="">Alle Einträge</option>
                <option value="1%">10000 - 19999</option>
		<option value="2%">20000 - 29999</option>
                <option value="3%">30000 - 39999</option>
		...
	</select>
</div>

Das TypoScript dazu:

plugin.tx_browser_pi1 {
  ...
  views {
    list {
        1 {
        ...
        filter {
          ...
          tt_address {
            zip < plugin.tx_browser_pi1.displayList.master_templates.selectbox
          }
        }
      }
    }
    ...
  }
}

Vorteil: Der PLZ-Bereich generiert sich aus den bereits eingegebenen PlZ von selbst.
Nachteil: Die Anzahl der Datensätze wird nicht angezeigt und die gewählte Auswahl bleibt in der Select-Box nicht erhalten.

Die Nachteile wiegen zu schwer, daher gehen wir folgendermaßen vor: tt_address wird um das Feld „PLZ-Bereich“ erweitert.

Extensions erstellen, um tt_address zu erweitern

Dafür benötigen wir zwei Extensions: die erste generiert die Datensätze für den PLZ-Bereich, die zweite integriert diese Datensätze in tt_address.

Hinweis: da es etliche Tutorials zur Extension Erstellung gibt, beschränke ich mich hier auf das minimal Nötige. Selbstredend sollte man die Extensions ordentlich erstellen, wozu ein vernünftiger Extension key, eine General Info sowie eine Lokalisierung gehört.

Im Kickstarter gibt man einen Extension Key ein (hier: qwe) und klickt auf das Plus neben „New Database Tables“. Hier füllt man die Felder folgendermaßen:

Tablename: tx_qwe_plzrange
Title of the table: PLZ-Bereich
NEW FIELD: Field name: ziprange
Field title: PLZ-Bereich
Field type: String input

Dann klickt man auf „Update …“. Nun kann man noch ein paar Änderungen im Bereich der Tabelle machen:

... order the table by this field: ziprange: PLZ-Bereich
Label-field: ziprange: PLZ-Bereich

Als nächstes klickt man auf „View result“, dann auf „WRITE“ und installiert die Extension.

Nun kann man über das Listenmodul bereits die gewünschten Datensätze erstellen. Wir machen das auf der selben Seite, auf der auch die tt_address und tt_address_group Datensätze angelegt sind.

Um die PLZ Datensätze in der tt_address Datenmaske erscheinen zu lassen, benötigen wir eine zweite Extension. Im Kickstarter vergeben wir wiederum einen Extension key (hier: qwe1) und klicken diesmal auf das Plus neben „Extend existing Tables“. Bei „Which table:“ wählen wir „tt_address (Adresse)“. „Field name“ und „Field title“ kann beliebig vergeben werden. Bei „Field type:“ handelt es sich um eine „Database relation“, bei „Create relation to table:“ wählen wir „Custom table /enter name below)“. Bei „Custom table name:“ schreiben wir „tx_qwe_plzrange“ (bzw. den entsprechenden Tabellennamen aus der ersten Extension). Weiterhin machen wir folgende Angaben:

Type: Selectorbox, select from current page
x Add a blank item to the selector
x Add "Add record" link
x Add "List records" link
x Add "Edit record" link

Nun klickt man wieder auf „View result“, dann auf „WRITE“ und installiert die Extension.

Wenn alles geklappt hat, sollte man im tt_address Datensatz nun ganz unten einen PLZ-Bereich auswählen können und auch neue PLZ-Bereich Datensätze anlegen können (sofern man sie nicht bereits über das Listenmodul erstellt hatte).

Integration des PLZ-Bereichs in die Browser-Extension

Im HTML Template innerhalb des Bereichs der „SEARCHFORM“ gibt man folgenden Marker ein: ###TX_QWE_PLZRANGE.ZIPRANGE###. Im Typoscript fügt man folgendes hinzu:

plugin.tx_browser_pi1 {
  ...
  views {
    list {
      1 {
        ...
        filter {
          ...
	  tx_qwe_plzrange {
	     ziprange < plugin.tx_browser_pi1.displayList.master_templates.selectbox
          }
        }
      }
    }
    ...
  }
}

Titel und ersten Eintrag der Select Box manipulieren

Damit sollte ein bereits zufriedenstellender Zustand erreicht sein: die beiden Select-Boxen werden angezeigt und funktionieren. Was stört sind zum einen die Überschriften der Select-Boxen (v.a. „Titel“ bei den Adressgruppen) und der erste Eintrag der Optionen „Alle Einträge“. Schöner wäre es, wenn die Überschriften ganz entfallen und die jeweils ersten Einträge geändert würden. Mit folgendem TypoScript macht man das möglich:

plugin.tx_browser_pi1 {
  ...
  views {
    list {
      1 {
        ...
        filter {
          tt_address_group {
            title < plugin.tx_browser_pi1.displayList.master_templates.selectbox
            #title.count_hits = 0
            title.first_item.cObject.20.data >
            title.first_item.cObject.20.value = Ausbildungen
            title.wrap = <div class="selectbox">|</div>
 
          }
          tx_qwe_plzrange {
            ziprange < plugin.tx_browser_pi1.displayList.master_templates.selectbox
            #ziprange.count_hits = 0
            ziprange.wrap = <div class="selectbox">|</div>
            ziprange.first_item.cObject.20.data >
            ziprange.first_item.cObject.20.value = PLZ-Bereich
          }
        }
      }
    }
    ...
  }
}

Die Entwickler der Extension haben an Hand eines wesentlich komplexeres Beispiels eine hervorragende und detaillierte Dokumentation zur Verfügung gestellt:
gruene-autos.org/typo3conf/ext/green_cars/doc/fall_studie.pdf.