Sitepackage Starter Kit für TYPO3 v12 und v13

Heute einmal viel Text zu etwas vollkommen Unspektakulärem: mein runderneuertes TYPO3-Sitepackage.

Sogenannte Sitepackage-Extensions (kurz: Sitepackage) werden in TYPO3 verwendet, um alle Frontend-Templates, -Assets und projekt­spezifische Konfigurationen zu bündeln. Technisch gesehen ist es eine normale TYPO3-Extension, die in der jeweiligen TYPO3-Installation eine zentrale Rolle einnimmt.

Als Maintainer einer Website habt ihr die Wahl:

1. ihr erstellt euch manuell ein eigenes Sitepackage, beispielsweise anhand des offiziellen Sitepackage-Tutorials;
2. ihr nutzt den Sitepackage Builder als Kickstarter;
3. oder ihr greift auf die wachsende Zahl öffentlicher Sitepackages anderer Entwickler zurück

Für TYPO3-Einsteiger ist das Tutorial auf jeden Fall sinnvoll, um die Komponenten und Zusammenhänge kennenzulernen.

Der Sitepackage Builder wiederum ist sehr nützlich, um sich mit ein paar Formulareingaben ein fertiges Grundgerüst generieren zu lassen. Die Konfigurationen sind hier minimal gehalten.

Wenn es dann um die weitere Ausgestaltung des eigenen Sitepackages geht, können die Sitepackages anderer Entwickler eine hilfreiche Inspirationsquelle sein. Oder man entschließt sich, eines davon direkt zu nutzen.

Die von Entwicklern und Agenturen öffentlich bereitgestellten Sitepackages unterscheiden sich alle in Umfang und Funktion. Manche liefern ein komplettes Frontend-Setup (z.B. Gulp oder Webpack) zur Erstellung eigener Templates mit, andere sind als Grundgerüst gedacht. Jedes Sitepackage ist so aufgebaut, dass es die eigene Arbeitsweise am besten unterstützt. Es kann sich für jeden lohnen, einmal zu schauen, wie andere Entwickler gewisse Dinge lösen.

Jede Sitepackage-Lösung – so sehr sie sich auch am TYPO3-Core und empfohlenen Praktiken orientiert – kann immer nur subjektiv sein.
Mein "basetemplate" bildet da keine Ausnahme.

Egal welchen Ansatz ihr wählt: Im Verlauf der Entwicklung werdet ihr das Sitepackage verändern und erweitern. Ihr ladet daher nicht (wie etwa bei TYPO3-Extensions) regelmäßig den neuesten Stand aus einer externen Quelle, sondern erstellt einmalig eine Kopie (oder halt eine ganz neue Extension) in einem separaten Projektverzeichnis, z.B. in "packages/" oder "extensions/".

Ein vollständiges Tutorial zu Sitepackages findet ihr in der offiziellen TYPO3-Dokumentation.

Mein Templating Starter Kit (oder halt Sitepackage) habe ich erstmals 2016 für TYPO3 6.2 und 7.6 veröffentlicht.

Seitdem gab es für jede neue TYPO3-Version ein eigenes GitHub-Repository mit Versionsnummer (z.B. "basetemplate8"). Fragt nicht nach dem Grund dafür.

Die einzelnen "basetemplate"-Versionen nutzten die jeweils aktuellsten Möglichkeiten der dazugehörigen TYPO3-Version, etwa die geänderte Syntax von TypoScript-Importen oder Conditions.

Nur für TYPO3 v11 hatte ich keine neue Version erstellt. Erstens war "basetemplate10" auch mit TYPO3 v11 nutzbar, da es wenig relevante Neuerungen in dem Bereich gab. Zweitens habe ich im Agenturalltag die dort vorgefundene Lösung verwendet und weiterentwickelt.

Im Laufe des vergangenen Jahres habe ich mich schließlich doch dazu entschlossen, das Projekt fortzuführen und für TYPO3 v12 auf neue Füße zu stellen.

Im neuen GitHub-Repository "basetemplate" ist die Versionsnummer im Namen endlich entfallen. Vorerst ist der main-Branch für TYPO3 v12 und v13 nutzbar.

So schnell kann's gehen.

Das Basetemplate war vorbereitet, dieser Blogbeitrag bereits geschrieben. Dann erschien im April die TYPO3-Version 13.1 mit einem neuen, sehr hilfreichen Feature zur Integration: Site Sets.

Letzten Endes habe ich mich dazu entschieden, mit dem Wechsel auf Site Sets alle alten Zöpfe abzuschneiden:

• Der main-Branch unterstützt TYPO3 v13 ausschließlich mit Site Sets
• Der 12.4-Branch kann mit TYPO3 v12+ auf die alte Weise mit Static Includes verwendet werden

Das "basetemplate" ist als Grundgerüst gedacht, mit dem Entwickler ihr eigenes Frontend-Template in TYPO3 integrieren können.
Nach Installation erhält man eine Frontend-Ausgabe und ausreichend Konfiguration, um das eigene Projekt umsetzen zu können.

Diese Extension kann zudem als praktisches Beispiel für einzelne Features oder Arbeitsweisen dienen.

Als Muster dienten natürlich der TYPO3-Core, das Bootstrap Package, ebenso wie die vielen hilfreichen Lösungsansätze im TYPO3 Slack und aus anderen Quellen.

Dazu kommen meine eigenen Erfahrungen aus verschiedensten großen wie kleinen Kundenprojekten.

Es handelt sich um ein Sitepackage. Das ist kein Wunderwerk der Technik. Was enthalten ist:

• Praxiserprobte Verzeichnisstruktur für Konfigurationen und Templates
• Grundlegende Fluid-Templates für die Website und die Hauptnavigation
• Das wesentliche TypoScript-Setup
• Grundlegendes Page und User TSconfig
• Konfiguration für den Richtext-Editor CKEditor 5
• Gängige Route Enhancer für Seiten und EXT:news
• Konfigurierbare Favicons (und Web App Manifest)

Drei der letzten Anpassungen beschreibe ich nachfolgend noch etwas näher.

Der Seitentitel selbst kann durch die Page Title API beeinflusst werden. Auch der Präfix (oder eher genutzte Suffix) mit dem Firmennamen ist durch TypoScript konfigurierbar ("Sichere Websites mit TYPO3 | ACME GmbH"). Seit TYPO3 v12 gibt es dafür config.showWebsiteTitle, mit dem der Website-Titel aus der Site Configuration ausgelesen wird.

Bei Seiten mit einem optimierten Titel für Suchmaschinen (seo_title) halte ich es aber für sehr sinnvoll, den Default-Suffix nicht automatisch zu setzen. Dem Redakteur sollte dann die volle Zeichenlänge des Titels in Suchergebnissen zur Verfügung stehen.

Mit etwas eigenem TypoScript lässt sich dies wie folgt umsetzen:

• Als Default-Suffix wird der Website-Titel aus der Site Configuration verwendet (auch sprachabhängig)
• Das Trennzeichen zwischen Seitentitel und Suffix muss manuell mit noTrimWrap gesetzt werden. So wird es nur gesetzt, wenn ein Website-Titel gefunden wird und gleichzeitig der SEO-Titel fehlt.
• Ist ein Titel für Suchmaschinen in der Seite gepflegt, entfallen Suffix und Trennzeichen
• Diese Lösung funktioniert auch mit dem alternativen (SEO-)Titel der News-Extension

config {
    showWebsiteTitle = 0
    pageTitle.append = TEXT
    pageTitle.append {
        data = siteLanguage:websiteTitle // site:websiteTitle
        stdWrap.noTrimWrap = # | ##
        stdWrap.noTrimWrap.splitChar = #
        stdWrap.if.isTrue.data = siteLanguage:websiteTitle // site:websiteTitle
        if.isFalse.data = page:seo_title
    }
}

[request && traverse(request.getQueryParams(), 'tx_news_pi1/news') > 0]
    config.pageTitle.append.if.isFalse {
        data >
        dataWrap = DB:tx_news_domain_model_news:{GP:tx_news_pi1|news}:alternative_title
        wrap3 = {|}
        insertData = 1
    }
[end]

Diese Middleware-Lösung ist nicht meine Idee gewesen, sondern wurde dankens­werterweise von Kevin Appelt im TYPO3 Slack geteilt (ich hatte dies bereits in meinen Notizen zum TYPO3-v12-Upgrade erwähnt).

Für das basetemplate habe ich die aktuellen Anforderungen bzgl. Favicons geprüft:

• Das favicon.ico kann für Webbrowser heute problemlos durch ein favicon.png und ein favicon.svg (bei Bedarf mit Dark-Mode-Support!) abgelöst werden.
• Einzelne Tools (z.B. RSS-Reader) suchen weiterhin ein favicon.ico. Das darf aber nicht im <head> verlinkt werden – sonst bevorzugen die Webbrowser diese Datei und ignorieren die bessere SVG-Version!
• Als Apple Touch Icon genügt ein PNG-Bild im Format 180x180 Pixel.
• Für Android benötigt man zwei PNG-Icons in den Formaten 192x192 und 512x512 Pixel. Diese Icons werden im Web App Manifest verlinkt.
• Ergänzend kann eine theme-color definiert werden, die von Android und iOS berücksichtigt wird.

Die Middleware kann über Site Settings konfiguriert werden:

favicons:
  full_name: 'My fancy website'
  short_name: 'My website'
  theme_color: '#ff8800'
  favicon_path: 'EXT:basetemplate/Resources/Public/Images/Favicons/'
  favicon_svg: favicon.svg
  favicon_png: favicon-32x32.png
  apple_touch_icon: apple-touch-icon.png
  android_192: android-chrome-192x192.png
  android_512: android-chrome-512x512.png

Nur für konfigurierte Favicons werden am Ende Meta-Tags gerendert:

<link rel="manifest" href="/site.webmanifest">
<link rel="icon" href="/path/to/favicon.svg" type="image/svg+xml">
<link rel="icon" href="/path/to/favicon-32x32.png" type="image/png" sizes="32x32">
<link rel="apple-touch-icon" href="/path/to/apple-touch-icon.png" sizes="180x180">
<meta name="theme-color" content="#ff8800">

Das TYPO3-Projektverzeichnis config/sites/<site-identifier>/ entwickelt sich spätestens mit TYPO3 v12 zur zentralen Ablage für Website-spezifische Konfigurationen:

1. config.yaml (Site Configuration)
2. settings.yaml (Site Settings)
3. csp.yaml (Content-Security-Policy)

Die bislang als TypoScript Constants definierten Seiten-IDs und andere Variablen habe ich daher nun durch Site Settings ersetzt. Die Vorteile:

• In TypoScript stehen die Settings (wie Constants) direkt zur Verfügung
• Das gilt ebenso für Page TSconfig – die Nutzung von Constants war dort bis jetzt nicht möglich
• In Fluid können sie durch einen DataProcessor bereitgestellt werden
• Für PHP gibt es das Site Object als praktische API

Die neuen Extension-Settings habe ich – zusammen mit den Favicon-Konfigurationen sowie gängigen Route Enhancern – im Extension-Verzeichnis Configuration/Site/ abgelegt. Von dort können sie in der Site Configuration bzw. den Site Settings des eigenen Projekts importiert (oder dorthin kopiert) werden.

In der neuesten Version des “basetemplate” habe ich die Site Settings in zwei neue Site Sets verlagert:

• "Basetemplate (Favicon configuration)" enthält die Setting-Definitionen für den Favicon-Provider
• “Basetemplate (Sitepackage)” ist das primäre Site Set. Enthalten sind Setting-Definitionen für die Website, z.B. Seiten-IDs für Navigationen. Außerdem setzt ein Subset die gewünschten Werte der Dependencies, wie etwa Template-Pfade von Fluid Styled Content.

Das neue cObject PAGEVIEW habe ich auf dem Schirm. Aktuell ist es als “Experimental” eingestuft – bis zum LTS-Release können sich hier also noch Änderungen ergeben. Das FLUIDTEMPLATE der Website im “basetemplate” werde ich damit ersetzen, wenn sich das Feature stabilisiert hat.

Bei zukünftigen Neuerungen am Sitepackage Starter Kit plane ich nicht, die Versionsnummer 1.0.0 anzuheben. Die Kompatibilität des jeweiligen Branchs ist in der README.md und composer.json vermerkt; jede Anpassung in der Git-Historie dokumentiert. Der aktuelle Stand ist immer stabil nutzbar.