Eine Welt voller Länderinformationen nutzen
Mühelose Integration von mehrsprachigen Länderlisten in dein TYPO3-Projekt
Seit den Anfängen von TYPO3 ist die Erstellung einer einfachen Länderliste ein allgegenwärtiger Anwendungsfall – meist für die Gestaltung von Kontaktformularen oder für Extension-Autoren, die einen Benutzerregistrierungsprozess aufbauen.
Um eine Länderliste in ein beliebiges Frontend-Formular einzubinden, war eine Integration in das TYPO3-eigene Formular-Framework (über die Extension Form Country Select) oder eine Integration in die Powermail-Extension (Powermail Country Viewhelper) erforderlich.
Vor TYPO3 v12 gab es eine nützliche Erweiterung namens „Static Info Tables“. Diese Extension bietet eine statisch verfügbare Datenbanktabelle mit einer Liste aller Länder und anderen statischen Informationen, wie z.B. eine Liste aller Sprachen oder Währungen. Diese Erweiterung gibt es schon seit etwa 20 Jahren und sie war immer mit der neuesten Version von TYPO3 kompatibel.
Leider hat die Erweiterung ein paar Nachteile:
- Die Informationen waren nur mit dem englischen Namen verfügbar (z. B. „Switzerland“ und nicht „Schweiz“ wie für die Schweizer Nutzer).
- Die Daten wurden in einer Datenbank gespeichert, so dass jedes Mal eine Datenbankabfrage erforderlich war, wenn ein Nutzer ein Land aus einem Formular auswählte.
Das erste Hindernis wurde mit Zusätzen zur Erweiterung überwunden, meist mit einem Suffix wie „static_info_tables_da“ für die dänischen Übersetzungen dieser Liste. Diese Zusätze waren jedoch nicht immer so aktuell wie die Haupterweiterung.
Der zweite Punkt bezog sich auf die konzeptionelle Funktionalität des Systems und hatte historische Gründe. Die Liste der installierten Erweiterungsdaten war keinen Änderungen unterworfen, also gab es auch keinen Grund, die Datenbank regelmäßig mit solchen aktualisierten Informationen zu versorgen. Schließlich gibt es elegantere Möglichkeiten, diese Daten abzurufen.
Mit TYPO3 v12 wurden all diese Probleme gelöst, indem diese Funktionalität in Core aufgenommen wurde und die Länder-API verwendet wird, um eine vollständige Liste der aktuellen Länder abzurufen.
Wenn du mehr über die neueste Version von TYPO3 erfahren möchtest und wie du deine Installation aktualisieren kannst, kontaktiere uns.
Wie TYPO3 die Liste der Länder abruft
Die TYPO3 Core-Entwickler haben sich die Mühe gemacht, verschiedene bestehende Open-Source-Lösungen zu analysieren, um herauszufinden, wo man die „offizielle Liste“ der Länder findet. Das ist gar nicht so einfach, denn die Ländernamen selbst sind nicht statisch. Zum Beispiel hat die Türkei ihren offiziellen englischen Namen 2022 in Türkiye geändert.
Das weithin bekannte Open-Source-Projekt Debian Linux bietet eine aktuelle Liste aller Länder, ihrer vollständigen Namen und ihrer offiziellen englischen Namen, wie sie von den Vereinten Nationen und der ISO-Norm ISO 31-664 definiert sind. Glücklicherweise ist diese Liste auch im JSON-Format verfügbar und wird von einem PHP-Wrapper als Composer-Paket namens „sokil/php-isocodes-db-i18n“ bereitgestellt. Darüber hinaus enthält dieses Paket nicht nur die englische Version, sondern auch alle Namen und offiziellen Bezeichnungen in verschiedenen Sprachen — einschließlich aller offiziell unterstützten Sprachen (50+) von TYPO3 Core.
Anstatt dieses Paket im JSON-Format für jedes Projekt auszuliefern, benötigt TYPO3 nur dieses Paket im Mono-Repository und wandelt die JSON-Datei in eine vollständige PHP-Klasse um — die so von der PHP-Runtime optimiert wird und nativ von PHP gecached werden kann. Alle Übersetzungen werden dann als XLF-Dateien hinzugefügt, sodass das reguläre Verhalten von TYPO3 bei der Übersetzung von Strings berücksichtigt wird. Funktionen wie das Überschreiben von XLF-Dateien (wie bei jeder anderen XLF-Datei auch) können genutzt werden, und die korrekte Übersetzung wird mit der ausgewählten Site Language im TYPO3-Frontend oder der ausgewählten Sprache der Backend-Nutzer im TYPO3-Backend verbunden.
Ein Continuous-Integration-Job prüft regelmäßig, ob dieses Paket aktualisiert wird, so dass TYPO3 Core immer mit der vollständigen Liste aller Länder gemäß der Definition der Vereinten Nationen ausgeliefert wird.
Wie man die Länder-API in Erweiterungen verwendet
Für die Autoren von Erweiterungen ist die Country-API so einfach, wie sie nur sein kann.
Es gibt einen einzigen Entry Point:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
$provider = new \TYPO3\CMS\Core\Country\CountryProvider();
// get a list of all countries
$allCountries = $provider->getAll();
// get information about a specific country
$switzerland = $provider->getByIsoCode('CH');
$switzerland->getName(); // Switzerland
$switzerland->getOfficialName(); // Swiss Confederation
// And use the LanguageService to use a localized version
$languageService = GeneralUtility::makeInstance(\TYPO3\CMS\Core\Localization\LanguageServiceFactory::class)->create('de-CH');
$languageService->sL($switzerland->getLocalizedNameLabel()); // Schweiz
Es gibt Möglichkeiten, die gesamte Liste auf eine bestimmte Auswahl zu filtern, was für die Erstellung deiner Länder-Dropdowns praktisch ist, aber dazu kommen wir später.
Aber Achtung: Achte darauf, dass die Sprach- und Ländercodes richtig kopiert werden, wenn du sie zu TYPO3 hinzufügst.
Ein nativer Fluid ViewHelper
Die meisten Anwendungsfälle sind in Extbase- Extensions auf der Ebene von Fluid-Templates. Es wurde ein neuer ViewHelper <f:form.countrySelect> hinzugefügt:
1
2
3
4
5
6
7
<f:form.countrySelect
name="country"
value="CH"
sortByOptionLabel="true"
prioritizedCountries="{0: 'DE', 1: 'AT', 2: 'CH'}"
excludeCountries="{0: 'IR'}"
/>
Dieser ViewHelper nutzt die Country-API und bietet ein <select> HTML-Element mit einer Liste aller Länder, zeigt aber Deutschland, Österreich und die Schweiz ganz oben an, wobei die Schweiz vorausgewählt ist. Eine Liste von Ländern kann auch aus der Auswahl entfernt werden. Die Beschriftung innerhalb der Auswahloptionen für jedes Land wird automatisch in der aktuell verwendeten Sprache der Website lokalisiert.
Form Framework: Länderauswahl
Das Form Framework wird mit einem neuen Country Select-Element ausgeliefert, mit dem Redakteure jetzt ein Dropdown mit denselben Optionen wie im ViewHelper erstellen können.
TYPO3: Ein einfacher Weg für wiederkehrende Herausforderungen
Anstatt sich mit unendlich vielen zusätzlichen Erweiterungen für eine einfache Länderauswahl zu befassen, bietet TYPO3 diese Funktionalität out-of-the-box, in einer standardisierten und robusten Art und Weise, ohne jegliche Kompromisse bei der Leistung — einfach durch die Verwendung von PHP und den XLF-Übersetzungsdateien.
Natürlich werden einige bestehende Erweiterungen für Länderlisten, wie z.B. „static_info_tables“, nicht überflüssig, denn sie bieten Flexibilität und Listen mit statischen Daten (neben den reinen Ländernamen), die für einige Anwendungsfälle geeignet sind. Aber TYPO3 macht das Leben jetzt ein bisschen einfacher - für neue Projekte oder bei der Einschätzung eines Upgrades, um viele Erweiterungen von Drittanbietern zu vermeiden.
Du möchtest mehr über die neueste TYPO3 Version erfahren? Du brauchst Hilfe beim Upgrade? Kontaktiere uns!
Zusätzliche Informationen:
- Changelog v12.2 Feature #99618 - List of countries in the world and their localized names
- Changelog v12.3 Feature #99735 - New Country Select form element