TYPO3 CMS Sitepackage

This sitepackage sticks as closely as possible to the recommended standard and maps all conceivable functional areas. There are also various examples of common use cases.

For more details there is a documentation link in the comments of each file.

Features

Full blown directory and file structure

This sitepackage contains almost all the directories and files (except resource files) you need when creating your own sitepackage.

Color scheme selector

As an example of how to add new fields to pages records through ext_tables.sql and /Configuration/TCA/Overrides/pages.php and how to implement custom Symfony Conditions (with files Configuration/ExpressionLanguage.php, Classes/ExpressionLanguage/CustomTypoScriptConditionProvider.php and Classes/ExpressionLanguage/FunctionsProvider/CustomConditionFunctionsProvider.php) to be used in the TypoScript/TSconfig context (Configuration/TypoScript/Setup/page.typoscript) this sitepackage contains a method to provide choosable color schemes to backend users.

Backend Style Customization

This sitepackage can customize the TYPO3 login mask style (background image, footnote, highlight color, login logo and login logos alt text) and the backend style (backend favicon and logo). It uses the function of EXT:backend. But instead of relying on a backend user to set these variables through the extension settings it overrides them in ext_localconf.php with the Extension Configuration of this sitepackage in ext_conf_template.txt (which is an easier and centralized way).

Example Backend Layouts

Example BackendLayouts can be found here Configuration/TsConfig/Page/Default/mod.web_layout.BackendLayouts/ (as part of the always loaded default Page TSconfig) and here Configuration/TsConfig/Page/Include/mod.web_layout.BackendLayouts (as part of the user included Page TSconfig).

Example Custom Content Element

This sitepackage includes an example of a custom content element. Its icon has been defined in Configuration/Icons.php, it is registered and configured in Configuration/TCA/Overrides/tt_content.php and added to the newContentElement wizard in Configuration/TsConfig/Page/Include/mod.wizards.newContentElement.wizardItems/common.tsconfig. The frontend rendering based on EXT:fluid_styled_content is configured in Configuration/TypoScript/Setup/tt_content/sitepackage_newcontentelement.typoscript and finally rendered by Fluid template Resources/Private/Templates/Page/Example.html.

Custom ViewHelper

As an example of how to add custom ViewHelpers this sitepackage adds the possibility to modify attributes of the html tag by the HtmlTagAttributesViewHelper in file Classes/ViewHelpers/HtmlTagAttributesViewHelper.php. The ViewHelper namespace xmlns:s="http://typo3.org/ns/VendorName/Sitepackage/ViewHelpers" has been added to the Fluid Template file Resources/Private/Layouts/Page/Default.html and it is used to add information about the currently selected layout as data attribute with tag <s:htmlTagAttributes data="{data-layout:current}"/>.

Custom Symfony Command

If you want to run any process from your sitepackage using the command line interface (CLI) such as a time-consuming import of data from an external system, symfony commands are the way to go. A simple example is shown in this sitepackage under Classes/Command/DoSomethingCommand.php. Command Classes like this are registered under Configuration/Services.yaml.

To run the example command enter the following line:

Composer-based installation:

vendor/bin/typo3 sitepackage:dosomething anyArgument -o anyOptionValue

Legacy installation:

typo3/sysext/core/bin/typo3 sitepackage:dosomething anyArgument -o anyOptionValue

XML Sitemap configuration

When EXT:seo is loaded, its static TypoScript is automatically included. The sitepackage adds the ability to hide pages in the XML sitemap by setting the sitemap priority to 0 with the constant Configuration/TypoScript/Constants/plugin/tx_seo.typoscript. Please make sure to add the following lines to your site configuration to be able to access the sitemap via its human-readable URI sitemap.xml if you have not used this sitepackage as a distribution:

routeEnhancers:
  PageTypeSuffix:
    type: PageType
    map:
      sitemap.xml: 1533906435

Cross Browser Favicons

Based on resources of RealFaviconGenerator v0.16 the sitepackage includes all recommended cross browser definitions for Favicons / App Icons. The sitepackage adds all html header information in file Configuration/TypoScript/Setup/page.typoscript.

The file Configuration/TypoScript/Setup/browserconfig.typoscript configures a separete PAGE object with mime type text/xml to output the browserconfig.xml.

The file Configuration/TypoScript/Setup/site.webmanifest.typoscript configures a separete PAGE object with mime type application/json to output the site.webmanifest.

To be able to also display browserconfig.xml and site.webmanifest you need to add the following lines in your site configuration if you have not used this sitepackage as a distribution:

routeEnhancers:
  PageTypeSuffix:
    type: PageType
    map:
      # The above-mentioned configuration for "sitemap.xml" may already be here. 
      browserconfig.xml: 2943879438
      site.webmanifest: 3478304621

Note: Since all resources are referenced with paths generated by TYPO3, this solution is compatible with the future changeover by typo3/cms-composer-installers:4.0. Here you can get further information about the changes.

Site Configuration Auto Initialization

If you install this sitepackage in an empty TYPO3 CMS installation it will create a new site configuration with configuration for sitemap.xml, browserconfig.xml and site.webmanifest, a first root page with a link to the static TSconfig of this sitepackage, a template record with a link to the static TypoScript of this sitepackage and pages records for various HTTP error codes (404, 403, 500, 503 and undefined), which are referenced in the site configuration.

By default the language en-US is used. If you want to change it, just edit the site configuration in your TYPO3 installation under config/sites/sitepackage/config.yamlor via the Site Management > Sites module in the TYPO3 backend.

Ready to use Task Runner for SCSS and JavaScript

This site package provides a Gulp task runner that handles the following tasks:

• Compile SCSS from Resources/Public/Scss/ to CSS directory Resources/Public/Css/
• Improve backwards compatibility of your CSS code by using the well known Autoprefixer PostCSS plugin
• Minify JavaScript and CSS files and save them as separate files with ending *.min.css / *.min.js
• Static JavaScript code analysis with (JSHint Documentation), feel free to adjust the configuration file .jshintrc to your needs
• Concatenate and minify all JavaScript files from directory Resources/Public/JavaScript/Src and save the result under Resources/Public/JavaScript/Dist

To initially install Gulp and all necessary modules execute command npm install. Now you are able to run all tasks at once by executing command gulp. To run specific tasks use gulp <taskname>. To get an overview wich tasks can be executed run gulp --tasks.

Basic Structure

• Classes → Contains all PHP Classes
  • .htaccess → Prevents public access to directory Classes
  • Command → Contains all PHP Symfony Command Classes
    • DoSomethingCommand.php → Example of a custom Symfony Command
  • Controller → Contains all PHP controller Classes
  • Domain → Contains all PHP Domain Classes
    • Model → Contains all PHP Domain Model Classes
    • Persistence → Contains all PHP Domain Persistence Classes
    • Repository → Contains all PHP Domain Repository Classes
    • Validator → Contains all PHP Domain Validator Classes
  • ExpressionLanguage → Contains Expression Language Provider PHP Classes
    • FunctionsProvider → Contains Expression Language Functions Provider PHP Classes
      • CustomFunctionsProvider.php → Custom Expression Language Function Provider
    • CustomProvider.php → Custom Expression Language Provider
  • Hook → Contains all PHP Hook Classes
  • Middleware → Contains all PHP Middleware Classes
  • Service → Contains all PHP Service Classes
  • Utility → Contains all PHP Utility Classes
  • View → Contains all PHP View Classes
  • ViewHelpers → Contains all PHP ViewHelper Classes to be used in Fluid
    • HtmlTagAttributesViewHelper.php → Example ViewHelper file to add HTML tag attributes
• Configuration → Contains any configuration file for Backend and Frontend
  • .htaccess → Prevents public access to directory Configuration
  • Backend → Contains configuration that is important within the Backend
    • AjaxRoutes.php → Definitions for ajax routes for entry points
    • Modules.php → Definitions for Modules
    • Routes.php → Definitions for "regular" routes for entry points
  • ExpressionLanguage.php → Register Expression Language Provider
  • Extbase → Contains folder Persistence
    • Persistence → Contains PHP file Classes.php
      • Classes.php → Extbase persistence mapping for Classes
  • FlexForms → Contains FlexForm XML files
    • FlexFormExample.xml → Example FlexForm file to provide plugin settings
  • Form → Contains YAML files for form customization
    • CustomFormSetup.yaml → Customize form configuration
  • Icons.php → Registers custom Icons in the IconRegistry
  • RTE → Contains YAML files for RTE customization
    • RteConfig.yaml → Customize RTE configuration
  • RequestMiddlewares.php → Middleware Configuration for Frontend and Backend
  • Services.yaml → Configuration for automatic Symfony Service loading
  • TCA → Contains Table Configuration Array PHP files and Overrides
    • Overrides → Contains TCA Override PHP files
      • pages.php → Override TCA for table pages (e.g. add Page TSconfig includes)
      • sys_template.php → Override TCA for table sys_template (e.g. add TypoScript templates)
      • tt_content.php → Override TCA for table tt_content (e.g. prepare custom content elements)
  • TsConfig → Any TSconfig file for backend related adjustments
    • Page → Contains Page TSconfig files for backend configuration (primarily modules)
      • Default → Page TSconfig from Default directory is always included
      • Include → Page TSconfig from Include directory can be included manually
        • RTE.tsconfig → Customize RTE configuration
        • TCAdefaults.tsconfig → Override default values of TCA
        • TCEFORM.tsconfig → Detailed configuration of how editing forms are rendered
        • TCEMAIN.tsconfig → Configuration for the TYPO3 Core Engine (DataHandler)
        • mod.web_layout.BackendLayouts → Contains all BackendLayouts
          • default.tsconfig → Contains the default BackendLayout
          • example.tsconfig → Contains and additional example BackendLayout
        • mod.wizards.newContentElement.wizardItems → Contains configurations for the newContentElement Wizard
          • common.tsconfig → Defines content elements for the tab common
          • forms.tsconfig → Defines content elements for the tab forms
          • menu.tsconfig → Defines content elements for the tab menu
          • plugins.tsconfig → Defines content elements for the tab plugins
          • special.tsconfig → Defines content elements for the tab special
        • mod.tsconfig → Configuration for Backend Modules
        • options.tsconfig → Various options for the page affecting the core at various points
        • templates.tsconfig → Override fluid templates rendered by Backend controller
      • page.tsconfig → Included by user in page records (includes Include)
    • User → Contains User TSconfig files for backend configuration on a user or group basis
      • TCAdefaults.tsconfig → Override default values of TCA on a user or group basis
      • admPanel.tsconfig → Configuration of the Admin Panel in the Frontend for the user
      • auth.tsconfig → Override default values of TCA on a user or group basis
      • options.tsconfig → Various options for the user affecting the core at various points
      • page.tsconfig → Override any page TSconfig property on a user or group basis
      • permissions.tsconfig → Set access permissions on a user or group basis
      • setup.tsconfig → Default values and override values for the User Settings Module.
  • TypoScript → TypoScript files from this directory can be included manually
    • Constants → TypoScript Constant files
      • page.typoscript → Sitepackage constants for page rendering
      • plugin → Contains all TypoScript Constants definitions for the "plugin" top-level object
        • tx_seo.typoscript → TypoScript Constants for EXT:seo
      • plugin.typoscript → Constants plugins (includes plugin)
      • styles.typoscript → Frontend specific constants (mainly from EXT:fluid_styled_content)
    • Setup → TypoScript Setup files
      • _GIFBUILDER.typoscript → Configure global settings for GIFBUILDER by this top-level object
      • config.typoscript → Global configuration for Frontend rendering
      • constants.typoscript → Defines constants for replacement inside a parseFunc
      • lib → Contains all TypoScript Setup definitions for the "lib" top-level object
        • dynamicContent.typoscript → Helper object to dynamically get Content of any Content Column Position
        • getIndpEnv.typoscript → Helper object to get Environment-safe server and environment variables
        • parseFunc.typoscript → Helper object to parse content for stuff like special typo tags
      • lib.typoscript → Used for code "libraries" that can be referenced in TypoScript (includes lib)
      • module.typoscript → Backend Module configuration
      • page.typoscript → This defines what is rendered in the Frontend
      • plugin → Contains all TypoScript Setup definitions for the "plugin" top-level object
        • tx_form.typoscript → TypoScript Configuration for EXT:form
      • plugin.typoscript → Frontend set up for plugins (includes plugin)
      • tt_content → Contains all TypoScript Setup definitions for the "tt_content" top-level object
        • sitepackage_newcontentelement.typoscript → Frontend rendering definition for example content element for based on EXT:fluid_styled_content
      • tt_content.typoscript → Content rendering definitions (includes tt_content)
    • constants.typoscript → Manually added Static TypoScript Constants (includes Constants)
    • setup.typoscript → Manually added Static TypoScript Setup (includes Setup)
  • Yaml → Any YAML files used to configure this sitepackage
  • page.tsconfig → Automatically loaded during build time (includes Default)
• Documentation → Documentation files for this sitepackage
• Initialisation → Data to be used in an empty TYPO3 CMS installation for first initialization
  • Site → Site configuration data
    • sitepackage → Identifier for the site configuration
      • config.yaml → YAML configuration of the site configuration
  • data.xml → Data to be used in the database (contains a basic structure for this sitepackage)
• LICENSE.txt → Official license file for GPL-2.0-or-later
• README.md → The file you currently look at
• Resources → Contains any public and private resource files
  • Private → Private resource files like Fluid Templates, Language files or Form Definitions
    • .htaccess → Prevents public access to directory Private
    • Forms → Can contain form definitions (read/write access granted)
      • .gitignore → Ignore all files inside this directory
    • Language → Any language files to provide translated labels in backend and frontend
      • de.locallang.xlf → German translations of Frontend labels
      • de.locallang_be.xlf → German translations of Backend labels
      • de.locallang_db.xlf → German translations of labels used in TCA
      • locallang.xlf → Source file for Frontend labels (english)
      • locallang_be.xlf → Source file for Backend labels (english)
      • locallang_db.xlf → Source file for labels used in TCA (english)
    • Layouts → Any Fluid Layout files
      • Content → Fluid Layout Overrides for EXT:fluid_styled_content
      • Form → Fluid Layout Overrides for EXT:form
        • Frontend → Fluid Layout Frontend Overrides for EXT:form
      • Page → Fluid Layout for PAGE rendering of this sitepackage
        • Default.html → Default Frontend layout file
    • Partials → Any Fluid Partial files
      • Content → Fluid Partial Overrides for EXT:fluid_styled_content
      • Form → Fluid Partial Overrides for EXT:form
        • Frontend → Fluid Partial Frontend Overrides for EXT:form
      • Page → Fluid Partials for PAGE rendering of this sitepackage
        • Navigation.html → Partial for basic navigation rendering
    • Templates → Any Fluid Template files
      • Content → Fluid Template Overrides for EXT:fluid_styled_content
        • NewContentElement.html → Fluid Template for example content element
      • Form → Fluid Template Overrides for EXT:form
        • Frontend → Fluid Template Frontend Overrides for EXT:form
      • Page → Fluid Templates for PAGE rendering of this sitepackage
        • Default.html → Template File for default layout (configured in /Configuration/TsConfig/Page/Default/mod.tsconfig)
        • Example.html → Template File for example layout (configured in /Configuration/TsConfig/Page/Include/mod.tsconfig)
  • Public → Public resource files accessible by the browser (e.g. CSS, JavaScript, Images, etc.)
    • Css → Any CSS files to be loaded by the sitepackage
      • Backend → Backend CSS files to be loaded by the sitepackage (compiled and minified by Gulp)
        • ... → Compiled Backend CSS files
      • Frontend → Frontend CSS files to be loaded by the sitepackage (compiled and minified by Gulp)
        • ... → Compiled Frontend CSS files
    • Fonts → Any Font files to be loaded by the sitepackage
    • Icons → Any Icon files to be loaded by the sitepackage
      • BackendLayouts → Contains Icons for BackendLayouts
        • columns-2.svg → Example BackendLayout Icon file to display two columns
        • default.svg → Default BackendLayout Icon file to display one column
      • Favicon → Contains Cross Browser Favicon Icons
        • ... → Resources created by RealFaviconGenerator v0.16
      • Extension.svg → Extension icon
    • Images → Any Image files to be loaded by the sitepackage
      • Backend → Contains Images that are used in the backend
        • loginBackgroundImage.svg → Login Background Image configured in ext_localconf.php
      • Distribution.png → Preview image for the distribution list in the Extension Manager
      • DistributionWelcome.png → The welcome image is displayed in the distribution detail view inside the Extension Manager.
    • JavaScript → Any JavaScript files to be loaded by the sitepackage
      • Dist → Contains minified redistributable JavaScript files (compiled by Gulp)
        • ... → Compiled JavaScript files
      • Src → Contains source JavaScript files (used by Gulp)
        • main.js → A starting point to write your own JavaScript (this should be compiled by Gulp)
    • Scss → Any SCSS files to be compiled to CSS files
      • Backend → Backend SCSS files to be compiled by Gulp
        • rte.scss → Backend RTE styles that inherit frontend RTE styles
      • Frontend → Frontend SCSS files to be compiled by Gulp
        • _rte.scss → Frontend RTE styles (prepending "_" means, that this file will be included by other files and compiled by itself)
        • _variables.scss → Global variables to be used in all scss files (prepending "_" means, that this file will be included by other files and compiled by itself)
        • main.scss → Main styles (imports _rte.scss and _variables.scss)
        • main-color1.scss → Main styles with definitions for color scheme 1 (imports main.scss)
        • main-color2.scss → Main styles with definitions for color scheme 2 (imports main.scss)
• Tests → This directory contains tests, e.g. unit tests in the subfolder Unit
  • Functional →
    • Domain →
      • Repository →
        • Fixtures →
  • Unit →
    • Controller →
    • Domain →
      • Model →
      • Repository →
• .gitignore → Exclude any unnecessary/temporary data from versioning
• .jshintrc → Basis JSHint configuration file used by Gulp (JSHint Documentation)
• composer.json → Registration file for composer based installations
• ext_conf_template.txt → Extension Configuration that will be accessible in the TYPO3 backend from Settings module
• ext_emconf.php → Registration file for legacy installations
• ext_localconf.php → Always included in global scope, in Frontend, Backend and CLI context
• ext_tables.php → Register Backend Modules / scheduler tasks, add table options, $GLOBALS assignments, BE User settings extensions
• ext_tables.sql → Table-structure dump of tables used by the sitepackage
• ext_tables_static+adt.sql → Static SQL data to be used by the sitepackage
• ext_typoscript_constants.typoscript → Default TypoScript constants that will be included in all templates
• ext_typoscript_setup.typoscript → Default TypoScript setup that will be included in all templates
• gulpfile.js → Gulp Task Runner Configuration file, after initial npm install run gulp for all tasks or gulp --tasks for an overview
• LICENSE.txt → Official GNU general public license file
• package.json → Node Package Manager (npm) to set up Gulp Tasks, for first initialization run npm install

FAQ:

How to get rid of the README.md files?

If you get disturbed by the README.md files in your current project, run the following command inside the sitepackage root to delete them:

find ./packages/sitepackage/ -name "README.md" -type f -delete

or in DDEV:

ddev exec find ./packages/sitepackage/ -name "README.md" -type f -delete

How do I easily change the namespace, composer name and extension key?

If you want to change the Namespace used in all files from VendorName/Sitepackage to FancyCompany/GreatExtension (adjust this example to your needs) use the following commands:

find ./packages/sitepackage \( -iname \*.html \) -type f -print0 | xargs -0 sed -i 's/VendorName\/Sitepackage/FancyCompany\/GreatExtension/g'
find ./packages/sitepackage \( -iname \*.php -o -iname \*.yaml \) -type f -print0 | xargs -0 sed -i 's/VendorName\\\Sitepackage/FancyCompany\\\GreatExtension/g'
find ./packages/sitepackage \( -iname \*.php -o -iname \*.json \) -type f -print0 | xargs -0 sed -i 's/VendorName\\\\\\\Sitepackage/FancyCompany\\\\\\\GreatExtension/g'

To change the composer name and extension key use the following commands:

find ./packages/sitepackage \( -iname \*.json \) -type f -print0 | xargs -0 sed -i 's/vendorname\/sitepackage/fancy-company\/great-extension/g'
find ./packages/sitepackage \( -iname \*.php -o -iname \*.xml -o -iname \*.yaml -o -iname \*.typoscript -o -iname \*.tsconfig -o -iname \*.xlf -o -iname \*.json \) -type f -print0 | xargs -0 sed -i 's/sitepackage/great-extension/g'
mv ./packages/sitepackage ./packages/great-extension

or in DDEV:

ddev exec "find ./packages/sitepackage \( -iname \*.html \) -type f -print0 | xargs -0 sed -i 's/VendorName\/Sitepackage/FancyCompany\/GreatExtension/g'"
ddev exec "find ./packages/sitepackage \( -iname \*.php -o -iname \*.yaml \) -type f -print0 | xargs -0 sed -i 's/VendorName\\\Sitepackage/FancyCompany\\\GreatExtension/g'"
ddev exec "find ./packages/sitepackage \( -iname \*.php -o -iname \*.json \) -type f -print0 | xargs -0 sed -i 's/VendorName\\\\\\\Sitepackage/FancyCompany\\\\\\\GreatExtension/g'"

ddev exec "find ./packages/sitepackage \( -iname \*.json \) -type f -print0 | xargs -0 sed -i 's/vendorname\/sitepackage/fancy-company\/great-extension/g'"
ddev exec "find ./packages/sitepackage \( -iname \*.php -o -iname \*.xml -o -iname \*.yaml -o -iname \*.typoscript -o -iname \*.tsconfig -o -iname \*.xlf -o -iname \*.json \) -type f -print0 | xargs -0 sed -i 's/sitepackage/great-extension/g'"
ddev exec mv ./packages/sitepackage ./packages/great-extension

© 2022 Eric Bode