itzbund/gsb-core

GSB Core. This is Part of the Goverment Site Build (GSB) 11. Der GSB 11 ist eine Maßnahme der Dienstekonsolidierung Bund (DKB) des Bundesministeriums des Innern und für Heimat (BMI) und wird im Auftrag des Informationstechnikzentrums Bund (ITZBund) durchgeführt.

v3.2.0-rc.12 2024-12-13 08:22 UTC

This package is auto-updated.

Last update: 2024-12-13 08:25:15 UTC


README

TYPO3 12

GSB 11 Extension gsb_core

About

The extension gsb_core is the mainstay of the several GSB 11 extensions. The extension configures TYPO3 and extends it with selected extensions to provide better structured and appealing content while optimizing accessibility.

Learn more about the GSB 11.

Installation

The best way to install this extension is to start with the GSB Sitepackage Kickstarter extension.

Quick installation without GSB Sitepackage Kickstarter

In a composer-based TYPO3 installation you can install the extension EXT:gsb_core via composer:

composer config -g gitlab-domains gitlab.opencode.de && \
composer config -g repositories.gsb-core vcs https://gitlab.opencode.de/bmi/government-site-builder-11/extensions/gsb_core.git
composer require itzbund/gsb-core

In TYPO3 installations above version 11.5 the extension will be automatically installed. You do not have to activate it manually.

Usage

Nothing to do.

Feature Flags in gsb_core

This document explains how to use feature flags. Feature flags allow you to enable or disable specific features in your installation. This is of particular importance to not use features that have not passed the approval process.

Configuration

Feature flags are configured in the .env or the local-dev/.ddev/docker-compose.environment.yaml file on ddev machine. To add a feature flag, use the following syntax:

# Feature flag for the specific tickets. Set them to true to activate the features.
- TYPO3__SYS__features__ITZBUNDPHP-2877=%const(bool:true)%

In this example, the feature flag ITZBUNDPHP-2877 is set to true. To disable the feature, change the value to false or delete the setting.

Feature Flag Truth Table

This table illustrates the behavior of feature flags in various states.

Feature Flag StateEvaluated ValueDescription
featureFlag = truetrueThe feature is explicitly enabled.
featureFlag = falsefalseThe feature is explicitly disabled.
featureFlag = ''falseAn empty value is treated as false.
featureFlag not existfalseA non-existent flag defaults to false.

Curent feature flags of gsb_core

Feature flagDescription
brandingBackendLoginAt default branding to the login screen
ITZBUNDPHP-1615Replaces the TYPO3 core default email template footer text with a GSB11 footer text
ITZBUNDPHP-1996Form emails have the X-Request-Id header added to their field output table
ITZBUNDPHP-2328Streamline handling for linked pages in stage and singleteaser CEs. Fetches category and date value from target page and adds possibility to override/hide those values
ITZBUNDPHP-2877Enables general color management in the site module.
This sets the bootstrap colors --bs-primary --bs-secondary --bs-tertiary --bs-quaternary
ITZBUNDPHP-3176Enable Google Site Verification via SiteConfig
ITZBUNDPHP-3288Enable i18n of logo, 2nd logo, initiative-text etc
ITZBUNDPHP-3327Enable/Expose EXT:dpn_glossary in the TYPO3 backend
ITZBUNDPHP-3435Enable generic video renderer to add support for external video sources
The allowed external sources have to be configured via the extension configuration: allowedVideoDomains
ITZBUNDPHP-3969Extended handling for linked pages in single teaser CEs. Retrieves the value of the main category from the target page and offers the option of overwriting this value
ITZBUNDPHP-4070Enable a feature that allows additional file extensions for the uploads element
These can be configured via the extension configuration: additionalAllowedFileExtensionsForUploadsElement
ITZBUNDPHP-4083Enable generic audio renderer to add support for external audio sources
The allowed external sources have to be configured via the extension configuration: allowedAudioDomains

Usage in PHP Code

To use a feature flag in your PHP code, you can check the flag's value in the global TYPO3 configuration. Here's an example:

if (GeneralUtility::makeInstance(Features::class)->isFeatureEnabled('ITZBUNDPHP-2877')) {
    // Only if the feature flag is set to true the feature is activated
    // Feature-specific code goes here
}

In this example, the feature-specific code will only execute if the feature flag ITZBUNDPHP-2877 is set to true.

Usage in Fluid Templates

You can also use feature flags in your Fluid templates with a custom ViewHelper. First, ensure you include the namespace for the ViewHelper:

{namespace gsb=ITZBund\GsbCore\ViewHelpers}

Then, use the featureFlag ViewHelper to conditionally render content based on the feature flag:

<f:if condition="{gsb:featureFlag(featureKey: 'ITZBUNDPHP-2877')}">
    <!-- Feature-specific content goes here -->
</f:if>

In this example, the content inside the <f:if> tag will always be rendered if the feature flag ITZBUNDPHP-2877 is not set to false.

Site package

Site packages in EXT:gsb_core are alike to sets in TYPO3 13+.

A package is available in the site configuration if it matches one of the following criteria:

  • it's extension key includes gsb_core or site AND does not include impexp
  • it includes the following configuration in it's composer.json:
    {
        "extra": {
            "itzbund/gsb-core": {
                 "isSitePackage": true
            }
        }
    }

If a package has been selected as a site package, it's typoscript configuration (Configuration/TypoScript/{constants|setttings}.typoscript) will be loaded as the root template, which allows for zero configuration deployments.

Further Reading

For more information about feature flags in TYPO3, please refer to the TYPO3 Documentation on Feature Flags.

Special Endpoints

For infrastructure reasons this extension provides a version endpoint at /api/version which returns a json object with the following structure

{
    "versions": {
        "gsb": [string|null],
        "container": [string|null],
        "helmChart": [string|null],
        "TYPO3": "[string|null]",
        "packageCacheHash": "[string|null]"
    }
}

Contribute

As with TYPO3, we encourage you to join the project by submitting changes. Development of the GSB 11 mainly happens in the GSB 11 TYPO3 extension repositories.

To get started, have a look at our detailed contribution walkthrough.