Sitepackage Starter Kit for TYPO3 v12 and v13

A wall of text today about a fairly unspectacular topic: my renewed TYPO3 sitepackage.

So-called Sitepackage extensions (Sitepackage for short) are used in TYPO3 to bundle all frontend templates, assets, and project-specific configurations. From a technical point of view, it is a normal TYPO3 extension that plays a central role in a TYPO3 installation.

As the maintainer of a website, you have the following choices:

1. you create a sitepackage yourself, for example by following the official sitepackage tutorial;
2. you use the Sitepackage Builder as a kickstarter;
3. or you choose from the growing number of public sitepackages created by other developers

For TYPO3 beginners, the tutorial is absolutely useful for getting to know the components and correlations.

The Sitepackage Builder, on the other hand, is very useful for generating a ready-made basic structure with just a few form entries. The configurations are kept to a minimum here.

When it comes to the customization of your own sitepackage, the sitepackages of other developers can be a helpful source of inspiration. Or you can decide to use one of these directly.

The public sitepackages provided by developers and agencies all differ in terms of scope and features. Some provide a fully-fledged frontend setup (e.g. Gulp or Webpack) for creating custom templates, while others are intended as a basic framework. Each site package is designed to best support their particular way of working. It can be worthwhile for everyone to take a look at how other developers solve certain things.

Every sitepackage solution - as much as it is oriented towards the TYPO3 core and recommended practices - can only ever be subjective.
My “basetemplate” is no exception.

No matter which path you choose: During development, you will modify and extend the sitepackage. Therefore, you do not download the latest version regularly from an external source (as you would with TYPO3 extensions), but create a copy (or a completely new sitepackage) in a separate project directory, e.g. in “packages/” or “extensions/”.

You can find a complete tutorial on sitepackages in the official TYPO3 documentation.

I first published my Templating Starter Kit (or sitepackage) in 2016 for TYPO3 6.2 and 7.6.

Since then, I did create a separate GitHub repository with a version number for each new TYPO3 version (e.g. "basetemplate8"). Don't ask me why.

Each “basetemplate” version incorporated the latest features of the corresponding TYPO3 version, such as the changed syntax of TypoScript imports or conditions.

Only for TYPO3 v11, I had not created a new version. For one, “basetemplate10” was equally usable with TYPO3 v11, as there were few relevant improvements in that area. And secondly, I used and adapted the existing solution in my day-to-day work at the agency.

Over the past year, I eventually decided to continue the project and modernize it for TYPO3 v12.

In the new GitHub repository "basetemplate", the version number in the name has finally been dropped. For now, the main branch can be used for both TYPO3 v12 and v13.

It can happen so quickly.

The “basetemplate” was ready, this blog post already drafted. Then, in April, TYPO3 version 13.1 was released with a new, very useful feature for integration: Site Sets.

In the end, I decided to make a clean cut when introducing Site Sets:

• The main branch supports TYPO3 v13 exclusively with Site Sets
• The 12.4 branch can be used with TYPO3 v12+ with the old Static Includes

The “basetemplate” is intended as a basic framework with which developers can integrate their individual frontend template into TYPO3.
After installation, you immediately get a frontend rendering and enough configuration to implement your own project.

This extension can also serve as a practical example for individual features or approaches.

Of course, the TYPO3 core, the Bootstrap Package, as well as the many helpful solutions in TYPO3 Slack and other resources served as a reference.

I also applied my experiences from various large and small customer projects.

It is a sitepackage. It is not a wonder of technology. It includes:

• Field-tested directory structure for configurations and templates
• Basic Fluid templates for the website and the main navigation
• The essential TypoScript setup
• Basic Page and User TSconfig
• Configuration for the rich text editor CKEditor 5
• Common route enhancers for pages and EXT:news
• Configurable favicons (and web app manifest)

I will further describe at least three of the latest improvements below.

The page title itself can be influenced by the Page Title API. The prefix (or more commonly used suffix) with the company name can also be configured using TypoScript (“Secure websites with TYPO3 | ACME Inc.”). Since TYPO3 v12, there is config.showWebsiteTitle, which reads the website title from the Site Configuration.

However, for pages with an optimized title for search engine results (seo_title), I think it makes a lot of sense to omit the default suffix. The editor should then be able to use the full character length of the title in search results available.

We can achieve this with some custom TypoScript as follows:

• The website title from the Site Configuration is used as the default suffix (which can set by language)
• The separator between the page title and suffix must be set manually using noTrimWrap. It will only be set if a website title is found and the SEO title is not maintained.
• If a title for search engines is maintained in the page, the suffix and separator are omitted
• This solution also works with the alternative (SEO) title of the 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]

This middleware solution was not my idea, but was kindly shared by Kevin Appelt in the TYPO3 Slack (I had already mentioned this in my notes on the TYPO3 v12 upgrade).

For the basetemplate I have checked the latest requirements regarding favicons:

• The favicon.ico can nowadays be replaced by a favicon.png and a favicon.svg (even with dark mode support!) for web browsers.
• Some tools (e.g. RSS readers) still require a favicon.ico. However, this must not be linked in the <head> – otherwise the web browsers will prefer this file and ignore the higher-quality SVG version!
• A PNG image in the format 180x180 pixels is sufficient for the Apple Touch icon.
• For Android, you need two PNG icons in the formats 192x192 and 512x512 pixels. These icons are linked in the Web App Manifest.
• Additionally, a theme-color can be defined, which is taken into account by Android and iOS.

The middleware can be configured via Site Settings:

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

Meta tags will only be rendered for configured favicons:

<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">

At least since TYPO3 v12, the TYPO3 project directory config/sites/<site-identifier>/ has become the central repository for website-specific configurations:

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

I therefore replaced the page IDs and other variables that were previously defined as TypoScript constants with Site Settings. The advantages:

• The settings are directly available in TypoScript (as are/were the constants)
• This now also applies to Page TSconfig – the use of constants was not possible there until now
• In Fluid, they can be provided by a DataProcessor
• For PHP, there is the Site Object as a useful API

I have stored the new extension settings – together with the favicon configurations and common Route Enhancers – in the extension directory Configuration/Site/. You can import (or copy) them from there into the Site Configuration or Site Settings of your project.

In the latest version of the “basetemplate” I have moved the Site Settings into two new Site Sets:

• "Basetemplate (Favicon configuration)" contains the setting definitions for the favicon provider
• “Basetemplate (Sitepackage)” is the primary Site Set. It contains setting definitions for the website, e.g. page IDs for navigations. In addition, a subset sets the desired values of all dependencies, such as template paths of Fluid Styled Content.

I already keep an eye on the new cObject PAGEVIEW. It is currently marked as “experimental” – this means there might be some changes before the LTS release. I will replace the FLUIDTEMPLATE of the website in the “basetemplate” with this feature once it has been stabilized.

I do not intend to raise the version number 1.0.0 with future updates to the Sitepackage Starter Kit. The compatibility of the respective branch is noted in the README.md and composer.json, every adjustment will be documented in the git history. The current version will always be stable and operational.